Archil

Archil Sandbox BenchmarksComputeSDK

Archil provider for ComputeSDK

Installation & Setup

npm install @computesdk/archil

Add your Archil credentials to a .env file:

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.

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

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	✅	Accepts normal paths and maps them into /mnt/archil; shared-mode checkout/checkin is automatic.

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 accept normal absolute paths and map them into /mnt/archil internally.
• Raw runCommand strings are not rewritten. Commands that access the disk directly must use /mnt/archil themselves.