> For the complete documentation index, see [llms.txt](https://docs.computesdk.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.computesdk.com/providers/archil.md).

# Archil

{% embed url="<https://www.computesdk.com/benchmarks/sandboxes/archil/>" %}

Archil provider for ComputeSDK

## Installation & Setup

```bash
npm install @computesdk/archil
```

Add your Archil credentials to a `.env` file:

```bash
ARCHIL_API_KEY=your_archil_api_key
ARCHIL_REGION=aws-us-east-1
ARCHIL_DISK_ID=your_archil_disk_id
```

## Usage

Archil is exec-only — `create()` resolves a handle to an existing Archil disk id. Each command runs in an Archil-managed container with that disk attached.

```typescript
import { archil } from '@computesdk/archil';

const compute = archil({
  apiKey: process.env.ARCHIL_API_KEY,
  region: process.env.ARCHIL_REGION,
});

// Attach to an existing Archil disk by id
const diskId = process.env.ARCHIL_DISK_ID;
if (!diskId) throw new Error('ARCHIL_DISK_ID is not set');

const sandbox = await compute.sandbox.create({ diskId });

// Run a shell command against the mounted disk
const result = await sandbox.runCommand('echo hello > /mnt/note && cat /mnt/note');
console.log(result.stdout); // "hello"

// destroy() is a no-op — disk lifecycle is managed by Archil
await sandbox.destroy();
```

### Configuration Options

```typescript
interface ArchilConfig {
  /** Archil API key - if not provided, will use ARCHIL_API_KEY env var */
  apiKey?: string;
  /** Archil region (e.g. "aws-us-east-1") - if not provided, will use ARCHIL_REGION env var */
  region?: string;
  /** Override the control-plane base URL (useful for testing) */
  baseUrl?: string;
}
```

### Supported Operations

| Method       | Supported | Notes                                                              |
| ------------ | --------- | ------------------------------------------------------------------ |
| `create`     | ✅         | Resolves an existing disk from top-level `diskId`.                 |
| `getById`    | ✅         | Requires the disk id.                                              |
| `list`       | ✅         | Lists all disks visible to the API key.                            |
| `destroy`    | no-op     | Disk lifecycle is managed by Archil.                               |
| `runCommand` | ✅         | Calls Archil's HTTP `exec` endpoint and waits for completion.      |
| `getInfo`    | ✅         |                                                                    |
| `getUrl`     | ❌         | Each exec runs in a fresh ephemeral container — no port to expose. |
| `filesystem` | ✅         | Implemented via shell commands (`cat`, `find`, `mkdir`, etc.).     |

### Limitations

* Each `exec` call provisions a fresh container — no persistent state between calls beyond what is written to the disk.
* Responses are truncated to \~5 MB by the Archil control plane.
* `getUrl` is not supported — each exec runs in a fresh ephemeral container, so there is no long-lived process to expose a port on.
* Filesystem operations are implemented as shell commands, so each call costs one HTTP round trip.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.computesdk.com/providers/archil.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.