disk

SDK and CLI for Archil disks. Create disks, list and inspect them, manage who can mount them, and run commands against them — all from scripts, CI, or an interactive terminal. It also ships drop-in filesystem tools for AI SDK, Mastra, and Langchain.

disk talks to the Archil control plane over HTTPS and has no native dependencies. If you also want to mount a disk's data plane from Node (rare — most users want disk exec or the archil CLI), install @archildata/native alongside disk.

Install

npm install disk

CLI

# Authenticate
export ARCHIL_API_KEY=key-...
export ARCHIL_REGION=aws-us-east-1

# Create a disk — the response includes a one-time disk token you'll need to mount it
npx disk create my-disk

# List and inspect
npx disk list
npx disk get dsk-abc123

# Run a command against the disk's contents — Archil spins up a container with the disk
# mounted, runs the command, and returns stdout/stderr/exit code.
npx disk dsk-abc123 exec "ls -la /mnt"

# Delete
npx disk delete dsk-abc123

# Manage account-level API keys
npx disk api-keys list
npx disk api-keys create ci-bot
npx disk api-keys delete key-abc123

list and get pretty-print tables by default; pass -o json to pipe into jq. Credentials come from ARCHIL_API_KEY / ARCHIL_REGION, or --api-key / --region / --base-url flags.

Profiles

disk and sandbox share named profiles:

npx disk profile create --profile test-yellow --region aws-us-east-1
npx sandbox profile use test-yellow
npx sandbox list

profile create securely prompts for the API key. Flags override environment variables, which override the selected profile. The library API does not read profiles.

Sandbox CLI

The sandbox executable manages persistent sandboxes:

npx sandbox list
npx sandbox create dev --vcpu-count 4 --mem-size-mib 8192 --env NODE_ENV=development
npx sandbox pause dev
npx sandbox resume dev --no-wait
npx sandbox wait dev --status running --timeout 60
npx sandbox fork dev agent-task
npx sandbox run dev -- sh -c 'echo "$NODE_ENV"'
npx sandbox shell dev
npx sandbox stop dev
npx sandbox delete dev

Commands accept an exact ID or unique name. Lifecycle commands wait by default; use --no-wait to return once accepted. Use -o json for structured output. Starting a paused sandbox discards its memory snapshot and prompts unless --yes is passed. In a shell, Ctrl+] is the emergency escape.

Library

Setup:

import * as archil from "disk";

// Configure once per process — falls back to ARCHIL_API_KEY / ARCHIL_REGION env vars.
archil.configure({ apiKey: process.env.ARCHIL_API_KEY, region: "aws-us-east-1" });

// Create a disk. `token` here is the disk token — the one-time credential for mounting.
const { disk, token } = await archil.createDisk({ name: "my-disk" });
console.log(`Created ${disk.id}, disk token: ${token}`);

// List and look up disks
const all = await archil.listDisks();
const d = await archil.getDisk(disk.id);

Per-disk operations are methods on the Disk object itself, not top-level functions:

const d = await archil.getDisk("dsk-abc123");

// Run a command in a container with the disk mounted
const { stdout, stderr, exitCode } = await d.exec("ls -la /mnt && cat /mnt/config.json");

// Manage who can mount the disk
const user = await d.addUser({ type: "token", nickname: "ci" });
await d.removeUser("token", user.identifier!);

// Delete
await d.delete();

Sandboxes

Use Archil.sandboxes to manage persistent VMs:

const client = new archil.Archil({
  apiKey: process.env.ARCHIL_API_KEY,
  region: "aws-us-east-1",
});
const sandbox = await client.sandboxes.create({
  name: "prepared-environment",
  vcpuCount: 4,
  memSizeMiB: 8192,
});

const result = await sandbox.exec("uname -a");
console.log(result.stdout);

const terminal = await sandbox.processes.start("codex", {
  terminal: { cols: 120, rows: 40 },
  onOutput: ({ data }) => process.stdout.write(data),
});
const processId = terminal.id;
await terminal.sendInput("Review this repository\n");
await terminal.resize({ cols: 160, rows: 50 });
const cursor = terminal.cursor;
await terminal.disconnect();

const resumed = await sandbox.processes.connect(processId, {
  offset: cursor,
  onOutput: ({ data }) => process.stdout.write(data),
});
await resumed.kill();

await sandbox.start();
await sandbox.resume();

await sandbox.stop();
const fork = await sandbox.fork({ name: "agent-task" });
await fork.stop();
await fork.delete();

const all = await client.sandboxes.list();
const usingDisk = await client.sandboxes.list({ disk: "dsk-abc123" });

Network egress can optionally be restricted when creating a sandbox:

const restricted = await client.sandboxes.create({
  network: {
    egress: {
      default: "deny",
      allow: [
        "github.com",
        "*.github.com",
        "140.82.112.0/20",
        {
          target: "api.openai.com",
          transform: {
            headers: { Authorization: `Bearer ${process.env.OPENAI_API_KEY}` },
          },
        },
      ],
    },
  },
});

An egress policy accepts IPv4 addresses, CIDR ranges, exact domains, and *. wildcard domains. The default action applies when no target matches. allow and deny can both be specified; deny matches take precedence. Domain matching applies to plaintext HTTP and HTTPS traffic, and a wildcard such as *.github.com matches subdomains, not github.com itself. An object-form allow rule can transform outbound HTTPS requests to its exact lowercase domain. Header transformations overwrite values supplied by the sandbox; matching plaintext HTTP requests are rejected. Omit network for unrestricted egress. A running sandbox's complete policy can be replaced without restarting it; existing connections are not terminated:

const effective = await restricted.updateNetwork({
  egress: { default: "deny", allow: ["api.github.com"] },
});
console.log(effective, await restricted.getNetwork());

await restricted.updateNetwork({}); // Restore unrestricted egress.

Sandboxes support 1–32 vCPUs and 256–65,536 MiB of memory. When omitted, vcpuCount defaults to 1 and memSizeMiB defaults to 2,048 MiB.

sandbox.processes.start() always returns a runtime-owned process immediately. Pass terminal: true when the command needs terminal behavior, or provide { cols, rows } for an initial size. Terminal processes merge stdout and stderr into stdout; non-terminal processes keep the streams separate. Disconnecting leaves the process running. Reconnect with sandbox.processes.connect(id) to replay buffered output from the beginning, or pass { offset: process.cursor } to continue where the previous connection stopped. onOutput receives raw bytes with their stream and absolute offset. Call closeStdin() to deliver EOF to a non-terminal process. sendInput() streams large input as 1 MiB WebSocket frames. Set collectOutput: false to stream through onOutput without retaining decoded output in the process handle or result. Resize and kill use separate one-shot process controls, so they do not wait behind stdin. kill() returns after the control is acknowledged; wait() observes exit. maxConcurrentExecs limits attached process sessions; detached processes and one-shot controls do not count. Pausing a sandbox disconnects attachments but preserves its processes for reattachment after resume. Processes end when their sandbox is stopped or expires. sandbox.exec() is the one-call start-and-wait convenience for ordinary commands. It uses sandbox.processes internally and does not create a durable control-plane exec record; use sandbox.processes.start() when you need the process handle.

Transfer files through the sandbox process connection without buffering the whole file in memory:

await sandbox.files.uploadFile(file.stream(), "/workspace/input.tar.gz");

const writable = await fileHandle.createWritable();
await sandbox.files.downloadFile("/workspace/result.json", (chunk) =>
  writable.write(chunk),
);
await writable.close();

Downloads request one bounded chunk at a time. A short or empty chunk marks end-of-file, so the source does not need to be sized before transfer.

uploadFile() accepts a Uint8Array, ArrayBuffer, Blob, async iterable, or ReadableStream. downloadFile() passes each chunk to the provided writer and waits for it before requesting more data. Uploads replace the remote target only after the transfer succeeds.

API keys live at the account level, so those helpers are top-level:

await archil.listApiKeys();
await archil.createApiKey({ name: "ci-bot", description: "GitHub Actions" });
await archil.deleteApiKey("key-abc123");

Reading and writing objects

A Disk doubles as an S3-compatible bucket: read, write, delete, and list its files by key without mounting it. These methods talk to Archil's S3 endpoint using your same API key (no separate S3 credentials or SigV4 signing on your part).

const d = await archil.getDisk("dsk-abc123");

// Write — accepts a string, Uint8Array/Buffer, or ArrayBuffer. Returns the etag.
const { etag } = await d.putObject("reports/2026-01/data.json", JSON.stringify(report), "application/json");

// Read — returns the bytes (a Uint8Array).
const bytes = await d.getObject("reports/2026-01/data.json");
const text = new TextDecoder().decode(bytes);

// Metadata / existence without downloading the body
const meta = await d.headObject("reports/2026-01/data.json"); // null if absent
if (await d.objectExists("reports/2026-01/data.json")) { /* … */ }

// Delete (idempotent — deleting a missing key succeeds)
await d.deleteObject("reports/2026-01/data.json");

POSIX ownership and directories

Pass uid, gid, and mode when the files will be used by a non-root process:

await d.putObject("path/a/b/file.txt", "hello", {
  uid: 1000,
  gid: 1001,
  mode: 0o640,
});

If path/ already exists as 2000:2000 0700 and a/ and b/ are missing, the resulting tree is:

| Path | Owner | Mode | Result | | --- | --- | --- | --- | | path/ | 2000:2000 | 0700 | Existing directory; unchanged | | path/a/ | 1000:1001 | 0755 | Implicit parent created by the upload | | path/a/b/ | 1000:1001 | 0755 | Implicit parent created by the upload | | path/a/b/file.txt | 1000:1001 | 0640 | Published file with the requested attributes |

The requested file mode never applies to implicit parents; they use 0755 so they remain traversable. Existing directories are never re-owned or re-moded, so in this example a FUSE process running as uid 1000 still cannot traverse the pre-existing path/ directory.

Create an explicit directory by putting an empty directory-marker key ending in /:

await d.putObject("path/a/private/", "", {
  uid: 4000,
  gid: 4001,
  mode: 0o750,
});

This creates private/ as 4000:4001 0750. If the marker already exists, its attributes are unchanged. When attributes are omitted, files default to root:root 0644 and directories to root:root 0755. Automatic multipart uploads and append-created files use the same directory rules.

The disk root itself defaults to root:root 0755, which means an unprivileged process cannot create entries directly under the mount root. To avoid a post-mount chown, set the root's owner and mode when creating the disk (creation-time only; a later chown/chmod through a mount changes the live attributes as usual):

const { disk } = await archil.createDisk({
  name: "my-disk",
  rootAttrs: { uid: 1000, gid: 1000, mode: 0o755 },
});

mode is octal (pass 0o750, not 750). On regions that don't support rootAttrs yet the field is ignored and the disk is created with the defaults — check the rootAttrs field on the created disk to confirm it was applied.

rootAttrs only sets the root directory itself — it does not change how later writes get their attributes:

• Through a mount, normal POSIX rules apply: entries are owned by the creating process's uid/gid, with mode derived from its umask. A process running as the rootAttrs uid therefore owns everything it creates, with no attributes to pass anywhere.
• Through putObject and friends, omitted attributes still mean the server defaults (root:root 0644 files, root:root 0755 directories) — the disk's rootAttrs is not used as a fallback. Keep passing uid/gid on object writes when a non-root process will read them.

listObjects auto-paginates by default, returning every matching key. The first argument is a key prefix; a non-recursive listing (the default) returns the immediate level as objects plus subdirectory commonPrefixes:

const { objects, commonPrefixes } = await d.listObjects("reports/");      // one level
const all = await d.listObjects("reports/", { recursive: true });          // whole subtree
const first100 = await d.listObjects("reports/", { limit: 100 });          // cap the total

// Stream pages instead of buffering everything (large listings):
for await (const page of d.listObjectsPages("reports/")) {
  for (const obj of page.objects) console.log(obj.key, obj.size, obj.lastModified);
}

// Or drive pagination yourself:
const page = await d.listObjects("reports/", { singlePage: true });
if (page.isTruncated) {
  const next = await d.listObjects("reports/", { singlePage: true, continuationToken: page.nextContinuationToken });
}

Large uploads and bulk delete

putObject handles any size with one call. Small bodies go through a single request; large ones are uploaded as a multipart upload automatically — split into parts, uploaded with bounded concurrency, and assembled, aborting the upload if any part fails so nothing is left half-staged. You don't pick a different method for big files. For very large objects the part size is grown automatically so the upload never exceeds S3's 10,000-part limit.

// Small or multi-gigabyte — same call.
await d.putObject("reports/2026-01/data.json", JSON.stringify(report), "application/json");

const { etag } = await d.putObject("backups/2026-01.tar", bigBytes, {
  contentType: "application/x-tar",
  multipartThreshold: 5 * 1024 * 1024, // switch to multipart above 5 MiB; default = partSize
  partSize: 32 * 1024 * 1024,          // ≥ 5 MiB; default 16 MiB
  concurrency: 8,                      // parts in flight at once; default 4
});

For manual control over the multipart lifecycle (e.g. uploading parts from separate processes), the raw S3 primitives live in the opt-in d.multipart namespace — create, uploadPart, complete, abort, listParts, listUploads. Most code never needs these.

const { uploadId } = await d.multipart.create("big.bin");
const p1 = await d.multipart.uploadPart("big.bin", uploadId, 1, firstChunk);
const p2 = await d.multipart.uploadPart("big.bin", uploadId, 2, secondChunk);
await d.multipart.complete("big.bin", uploadId, [p1, p2]);

deleteObjects removes many keys in one round trip (auto-batched at S3's 1000-key limit). Unlike deleteObject, per-key failures are returned rather than thrown:

const { deleted, errors } = await d.deleteObjects(["a.txt", "logs/b.txt", "c.txt"]);
for (const e of errors) console.warn(`${e.key}: ${e.code} ${e.message}`);

appendObject appends bytes to an existing object (creating it if absent) — handy for log-style writes. Each call may append at most 1 MiB; append in chunks to grow past that.

await d.appendObject("logs/app.log", "first line\n");
await d.appendObject("logs/app.log", "second line\n"); // concatenated

Transient failures (HTTP 429 and 5xx, plus network errors) are retried automatically with jittered exponential backoff before surfacing; caller errors (other 4xx) are not retried. The two non-idempotent operations — completeMultipartUpload and appendObject — are not auto-retried, since a retry after a succeeded-but-unacknowledged call would return a spurious NoSuchUpload (complete) or duplicate the appended bytes (append).

Failures throw ArchilS3Error with status (HTTP status), code (the S3 error code, e.g. "NoSuchKey"), requestId, and the raw body on raw. getObject on a missing key throws a 404 — use headObject/objectExists to probe without catching. All SDK errors extend ArchilError, so catch (e) { if (e instanceof ArchilError) … } handles control-plane and S3 failures uniformly.

The S3 endpoint is derived from your region automatically. To target a custom environment, set s3BaseUrl on the Archil constructor (or the ARCHIL_S3_BASE_URL env var).

Sharing files

share mints a signed, time-limited link to a single file. Anyone with the link can download that file — no API key, no mounting. The link carries a cryptographically signed token (disk + key + expiry); when it expires it stops working.

const d = await archil.getDisk("dsk-abc123");

// Default lifetime is 24 hours.
const { url, expiresIn } = await d.share("reports/2026-01/summary.pdf");
console.log(url); // https://control.…/api/shared/<token>

// Set the lifetime in seconds (any positive integer, up to 604800 = 7 days):
const weekLink = await d.share("reports/2026-01/summary.pdf", { expiresIn: 604800 });

Multiple accounts or regions

For multi-tenant scripts, instantiate Archil directly instead of using the module-level configure:

import { Archil } from "disk";

const prod = new Archil({ apiKey: prodKey, region: "aws-us-east-1" });
const staging = new Archil({ apiKey: stagingKey, region: "aws-us-east-1" });

const prodDisks = await prod.disks.list();
const stagingDisks = await staging.disks.list();

Filesystem tools

Support for providing agents with a set of tools for using an Archil disk live in their own @archildata/* packages. | Package | Framework | | --- | --- | | @archildata/ai-sdk | AI SDK | | @archildata/eve | eve | | @archildata/mastra | Mastra | | @archildata/langchain | LangChain / LangGraph |

Workspaces

For usage with multiple disks, you can create a workspace, which acts as a virtual disk where each mounted disk appears as a top-level directory:

import { Archil } from "disk";

const archil = new Archil();
const source = await archil.disks.get(process.env.ARCHIL_SOURCE_DISK_ID!);
const output = await archil.disks.get(process.env.ARCHIL_OUTPUT_DISK_ID!);

const workspace = archil.workspace({
  source: { disk: source, readOnly: true },
  output,
});

Workspace paths route to the right disk by their first segment. readOnly mounts return an error from operations that mutate the disk.

Workspace mounts can also request delegations:

const workspace = archil.workspace({
  repo: {
    disk: repoDisk,
    checkoutPaths: ["src", "tmp/cache"],
    queueMs: 5_000,
  },
});

When queueMs is set without checkoutPaths, the mount root is acquired during mount setup instead.

Delegations

A delegation grants a client exclusive write access to an inode on a shared disk. List the delegations currently held on a disk and forcibly revoke one — useful for reclaiming write access from a client that crashed or lost connectivity without checking its delegations in:

const disk = await archil.disks.get("dsk-0123456789abcdef");

for (const d of await disk.listDelegations()) {
  // { clientId, inodeId, path?, isPending, isOrphaned }
  if (d.isOrphaned) {
    await disk.revokeDelegation(d);
  }
}

A delegation has no ID of its own — it is identified by the (clientId, inodeId) pair. isOrphaned entries are held by clients no longer connected to the disk. path is resolved best-effort by the server and may be absent.

A Workspace is a full filesystem in its own right — it has the same object API a Disk does (getObject / putObject / deleteObject / listObjects / grep / exec; both implement the FileSystem interface), so you can use it directly, and add or remove disks at runtime. A workspace's keys carry the disk name as their first segment:

const data = await ws.getObject("data/reports/q1.csv"); // routes to the "data" disk
ws.addDisk("scratch", diskTmp); // mount another disk live; ws.removeDisk("scratch")

Connecting to a disk's data plane

To run a command against a disk, use Disk.exec() — it returns stdout, stderr, and an exit code from an Archil-managed container with the disk pre-mounted. No local filesystem involved.

To mount a disk as a real filesystem on your machine, use the archil CLI — it mounts through the OS kernel via FUSE, so any program can read and write files with standard APIs.

For the rare case where you need raw Archil protocol access from Node.js (inodes, delegations, byte-level reads), install @archildata/native alongside disk:

npm install disk @archildata/native

Then Disk.mount() lazy-loads the native client:

import { getDisk } from "disk";

const d = await getDisk("dsk-abc123");
const client = await d.mount({ authToken: "<disk-token>" });
// `client` is an ArchilClient from @archildata/native — see that package's README.
await client.close();

@archildata/native supports Linux (x64 / arm64, glibc) and macOS (arm64). On other platforms, mount() throws; the rest of disk still works.

Supported regions

| Region | Provider | | ----------------- | -------- | | aws-us-east-1 | AWS | | aws-us-west-2 | AWS | | aws-eu-west-1 | AWS | | gcp-us-central1 | GCP |

FAQ

What's the difference between an API key and a disk token?

Archil has two credential types, and the examples above use both:

• API key — account-level credential for the control plane. You use one whenever you call disk (CLI or library). Create and manage them at console.archil.com or with disk api-keys create. Goes in the ARCHIL_API_KEY env var or the --api-key flag.
• Disk token — per-disk credential that lets a client mount a specific disk. Created automatically when you disk create <name> (the value is shown once; save it). You don't need one to run disk itself — only when something is actually mounting a disk.

Support

Questions, feature requests, or issues? Reach us at [email protected].