TypeScript SDK

The Archil TypeScript SDK is the disk package on npm. It’s a pure-JavaScript control-plane client and CLI: create disks, list and inspect them, manage who can mount them, and run commands against them with disk.exec.

npm install disk

disk has no native dependencies and requires Node.js 22.19 or later. For the rare case where you need raw protocol access from Node (inodes, delegations, byte-level reads), there’s a separate @archildata/native package — most users will not need it.

Package	When to use
`disk`	Manage disks, run commands with `disk.exec`, manage API keys. The default.
`@archildata/native`	Speak the Archil filesystem protocol directly from Node. Linux/macOS only. Not recommended unless you’re building a custom client runtime.

Looking for the FUSE mount client? That’s the archil CLI, which mounts a disk as a real local filesystem. The TypeScript SDK does not mount disks; it talks to the control plane and runs serverless commands.

Configuration

The recommended pattern is a module-namespace import with a one-time configure call:

import * as archil from "disk";

archil.configure({
  apiKey: process.env.ARCHIL_API_KEY,
  region: "aws-us-east-1",
});

Both options fall back to environment variables (ARCHIL_API_KEY, ARCHIL_REGION) if omitted, so in most environments configure({}) — or skipping configure entirely — is enough. For multi-tenant scripts that need multiple credentials in one process, instantiate Archil directly instead:

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" });

For endpoints signed by a private certificate authority, pass tls.ca (a PEM string, Buffer, or array of either) to new Archil({ ..., tls: { ca } }). Like Node’s TLS ca option, it replaces the default trust list, so include getCACertificates() from node:tls if you still need the public CAs.

The API key is an account-level credential and is not the same thing as a disk token. API keys authenticate calls to the control plane (everything in this page); a disk token grants mount access to a single disk. See the disk users concept page.

Managing disks

import * as archil from "disk";

// Create a disk. The returned token is the disk token — save it; it isn't
// retrievable again.
const { disk, token } = await archil.createDisk({
  name: "my-disk",
  mounts: [{
    type: "s3",
    bucketName: "my-bucket",
    accessKeyId: "AKIA...",
    secretAccessKey: "...",
  }],
});

// 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");

// Add an additional mount token
const user = await d.createToken("ci");
// save user.token — it's only returned once

// Revoke access
await d.removeUser("token", user.identifier);

// Delete the disk (this does not delete data in your bucket)
await d.delete();

Executing commands

Disk.exec(command) runs a bash command inside a container with the file system already mounted, and returns stdout, stderr, exit code, and timing. See the Serverless Execution concept page for the full picture.

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

const { stdout, stderr, exitCode, timing } = await d.exec(
  "du -sh logs",
);

console.log(`ran in ${timing.executeMs}ms (queued ${timing.queueMs}ms)`);

The disk is the working directory inside the container — commands can reference files using relative paths. For multi-disk execs (mount several disks at once, optionally pinned to a subdirectory or read-only), call archil.exec({ disks, command }) instead of Disk.exec. See Mounting multiple disks in one command.

`ExecResult`

interface ExecResult {
  exitCode: number;
  stdout: string;
  stderr: string;
  timing: ExecTiming;
}

interface ExecTiming {
  /** End-to-end wall-clock measured on the server. */
  totalMs: number;
  /** Time spent queueing, scheduling, booting a container, and mounting the filesystem. */
  queueMs: number;
  /** Time the user's command itself ran, measured by the runtime. */
  executeMs: number;
}

Billing is based on executeMs — the wall-clock time your command runs — in 1ms increments, with a 100ms minimum per call. Queue time is not billed. The HTTP response returns after 5 minutes, and stdout and stderr are each capped at 128 KiB per invocation — pipe larger outputs to a file on the disk instead.

Fan-out

Because each exec runs in its own container, Promise.all is a map-reduce:

const files = (await d.exec("ls logs")).stdout.trim().split("\n");

const results = await Promise.all(
  files.map((f) => d.exec(`wc -l logs/${f}`)),
);

For the common case of searching files for a pattern, don’t hand-roll this — use Disk.grep, which fans the same work out for you and returns structured matches. See the bash tool for agents guide for an end-to-end example wiring disk.exec into an AI agent loop.

Searching files

Disk.grep(opts) searches the files on a disk for lines matching a regular expression, fanning the listing and matching out across many ephemeral containers so the search scales across many machines instead of one. It’s the productized version of the fan-out above — reach for it instead of Promise.all over exec("grep …") whenever you just want matching lines. See Search Files for the full model.

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

const { matches, stoppedReason, durationMs } = await d.grep({
  directory: "logs",
  pattern: "ERROR|FATAL",
  recursive: true,
});

for (const m of matches) {
  console.log(`${m.file}:${m.line}: ${m.text}`);
}
console.log(`${matches.length} matches in ${durationMs}ms (${stoppedReason})`);

You control cost and latency with three knobs:

maxDurationSeconds — wall-clock deadline (default 30, capped at 30).
concurrency — max parallel workers (default 50). More workers scan a large dataset faster, at proportionally more compute.
maxResults — short-circuit once this many matches are collected (default 1000).

Always check stoppedReason — it tells you whether the search was exhaustive. When it stops early, the returned matches are a sample of whichever workers reported first, not the lexicographically first N:

`stoppedReason`	Meaning
`completed`	Every file under the directory was scanned successfully. The matches are exhaustive.
`max_results`	Stopped after collecting `maxResults` matches before scanning everything.
`deadline`	Hit `maxDurationSeconds` before scanning everything.
`incomplete`	The pipeline finished but one or more batches errored (invalid regex, unreadable file). Results may be partial.
`list_failed`	Directory listing failed; only partial results, if any, are present.

`GrepResult`

interface GrepResult {
  matches: GrepMatch[];
  stoppedReason: GrepStoppedReason; // "completed" | "incomplete" | "max_results" | "deadline" | "list_failed"
  filesScanned: number;
  containersDispatched: number;
  computeSecondsUsed: number; // ≈ billable container-seconds
  durationMs: number;         // end-to-end wall clock
  listingMs: number;          // overlaps grepMs, so the two can sum past durationMs
  grepMs: number;
}

interface GrepMatch {
  file: string; // relative to the disk root
  line: number; // 1-based
  text: string; // the matching line
}

Grep runs on the same container runtime as exec, so it bills the same way — on computeSecondsUsed, the summed execution time across the containers it dispatched.

Persistent sandboxes

Archil.sandboxes manages persistent Linux VMs. Each sandbox has a dedicated disk, accepts multiple commands over its lifetime, and can preserve CPU and memory state across pause and resume. See Persistent sandboxes for the lifecycle, interactive shells, services, forks, and limits.

import { Archil } from "disk";

const client = new Archil({
  apiKey: process.env.ARCHIL_API_KEY,
  region: "aws-us-east-1",
});

const sandbox = await client.sandboxes.create({
  name: "prepared-environment",
  baseImage: "node:24-bookworm",
  vcpuCount: 4,
  memSizeMiB: 8192,
  env: { NODE_ENV: "development" },
  maxTtlSeconds: 14_400,
  maxConcurrentExecs: 32,
});

const execution = await sandbox.run("node --version");
const result = await execution.wait();
console.log(result.stdout);

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

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

maxTtlSeconds sets the hard timeout from 60 seconds to 24 hours (the default). idleTtlSeconds sets an optional idle timeout from 0 to 24 hours; 0 disables it. Both pause the VM, preserving memory and processes for resume(). Use sandbox.setTimeout() to update either setting; a session cannot exceed 24 hours even after a timeout reset. See Setting a time to live for examples and reset behavior. create, pause, resume, stop, start, and fork wait for completion by default. The server handles the initial wait; if its request budget expires first, the SDK continues polling. Pass { wait: false } to return as soon as the operation is accepted. A waited pause() throws SandboxPauseError if the sandbox does not reach paused. fork() pauses a running sandbox while the snapshot is taken and resumes it once the fork is accepted.

const running = await sandbox.run("sleep 600", {
  timeoutSeconds: 600,
});

const processId = running.id;
const cursor = running.cursor;
await running.disconnect();

const resumed = await sandbox.attach(processId, { offset: cursor });
await resumed.kill();

Use client.sandboxes.list() and .get(id) to retrieve sandboxes. A Sandbox provides refresh, fork, delete, pause, resume, stop, start, and setTimeout; exposePort, listPorts, unexposePort, and port-token methods for network services; getNetwork and updateNetwork for the firewall; plus run and attach for starting and reattaching to sandbox processes. exec runs a command and waits for its result. Pass an absolute cwd to run or exec to choose a working directory. The older processes.start and processes.connect methods are deprecated compatibility aliases. For an interactive command, provide terminal dimensions. The returned SandboxProcess accepts input and terminal resizes while streaming output to onOutput:

const shell = await sandbox.run("/bin/sh", {
  terminal: { cols: 120, rows: 40 },
  onOutput: ({ data }) => process.stdout.write(data),
});

await shell.sendInput("pwd\n");
await shell.resize({ cols: 160, rows: 50 });
const { exitCode } = await shell.wait();

Mounting existing disks

Pass mounts when creating a sandbox to attach existing disks in addition to its internal root disk:

const workspace = await client.sandboxes.create({
  mounts: [{ disk: "dsk-0123456789abcdef", path: "/mnt/data" }],
});
console.log((await workspace.exec("ls /mnt/data")).stdout);

await workspace.stop();
await workspace.start({ mounts: [] });

Each mount accepts disk (a disk ID or Disk object), path, subdirectory, readOnly, conditional, and queueMs. With a single mount, path is optional and defaults to /mnt/archil. Omitting mounts on start() keeps saved mounts; [] clears them and a list replaces them. See Persistent sandboxes for sharing and forking behavior.

Private images

const image = await client.images.build({
  source: "ghcr.io/acme/agent-runtime:v2",
  registryAuth: { username: "bot", password: process.env.REGISTRY_TOKEN! },
});
const agent = await client.sandboxes.create({ imageId: image.imageId });

images.build() waits until the image is ready, retrying interrupted builds up to three times. The default timeout is 30 minutes; set it with images.build(request, { timeoutSeconds: 600 }). Failed builds raise ImageBuildError; timeouts raise ArchilError with code IMAGE_BUILD_TIMEOUT. Use images.get(imageId) to read the current build state. Pass imageId instead of baseImage when creating a sandbox from a built image. See Sandbox images for reusing builds and updating tags.

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");
const report = { generated: "2026-01", rows: 1234 };

// Write — body is a string, Uint8Array/Buffer, or ArrayBuffer. contentType is
// optional (defaults to application/octet-stream). Returns the etag.
const { etag } = await d.putObject(
  "reports/2026-01/data.json",
  JSON.stringify(report),
  "application/json",
);

// Read — returns 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 resolves successfully)
await d.deleteObject("reports/2026-01/data.json");

putObject handles any size with one call: small bodies go through a single request, and larger bodies 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. Tune the switch point and parallelism with options:

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 very large objects the part size grows automatically so the upload never exceeds S3’s 10,000-part limit. 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 oneLevel = await d.listObjects("reports/");                  // one level
const subtree = 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,
  });
}

deleteObjects removes many keys in one round trip (auto-batched at S3’s 1,000-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

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; prefer putObject, which runs the lifecycle for you.

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]);

Transient failures (HTTP 429 and 5xx, plus network errors) are retried automatically with jittered exponential backoff before surfacing; other 4xx are caller errors and aren’t 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 or duplicate the appended bytes. Object-API failures throw ArchilS3Error (a subclass of ArchilError) with status (HTTP status), code (the S3 error code, e.g. "NoSuchKey"), requestId, and the raw XML body on raw. getObject on a missing key throws a 404 — use headObject / objectExists to probe without catching.

import { ArchilS3Error } from "disk";

try {
  await d.getObject("reports/missing.json");
} catch (e) {
  if (e instanceof ArchilS3Error) {
    console.log(e.status, e.code, e.requestId);
  }
}

share generates a signed, time-limited URL that lets anyone download a file from the disk without credentials:

const share = await d.share("reports/2026-08/summary.csv");
console.log(share.url);       // https://control.…/api/shared/<token>
console.log(share.expiresIn); // 86400 (seconds)

// Custom expiry — any value from 1 to 604800 (7 days)
const hourShare = await d.share("reports/2026-08/summary.csv", { expiresIn: 3600 });

The returned URL supports HTTP Range requests and streams with a sensible Content-Type. After expiry, requests to the URL return 401.

Managing API keys

API keys are account-level, so these helpers live at the top level rather than on a Disk:

await archil.listApiKeys();
const k = await archil.createApiKey({ name: "ci-bot", description: "GitHub Actions" });
// save k.token — it's only returned once
await archil.deleteApiKey("key-abc123");

CLI

disk ships a CLI under the same name. See the disk CLI reference for the full command list.

npx disk create my-disk
npx disk list
npx disk dsk-abc123 exec "ls -la"

Low-level protocol access

For the small number of integrations that need to speak Archil’s filesystem protocol directly from Node — inodes, delegations, byte-level reads, paginated directory enumeration — install @archildata/native alongside disk:

npm install disk @archildata/native

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

import { getDisk } from "disk";

const d = await getDisk("dsk-abc123");
const client = await d.mount({ authToken: process.env.ARCHIL_DISK_TOKEN });

// `client` is an ArchilClient from @archildata/native — see that package's
// README on npm for the full inode-level API.
await client.close();

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

If you’re tempted to reach for @archildata/native to “run a bash command on a disk,” use disk.exec instead — it gives you a real shell with the filesystem mounted in a container, with no native dependencies on the caller side.

Need a bash executor inside Node?

The legacy @archildata/just-bash package implements a JavaScript bash interpreter that talks to a disk through @archildata/native. It’s still published, but for almost every use case disk.exec is the better answer — it runs your command in a real container with the filesystem mounted, returns stdout/stderr/exit code, and has no native dependencies on the caller.

Getting started

Compute

Concepts

Data Sources

Details

Administration

Protocols

Reference

Legal

TypeScript SDK

Configuration

Managing disks

Executing commands

`ExecResult`

Fan-out

Searching files

`GrepResult`

Persistent sandboxes

Mounting existing disks

Private images

Reading and writing objects

Managing API keys

CLI

Low-level protocol access

Need a bash executor inside Node?

​Configuration

​Managing disks

​Executing commands

​ExecResult

​Fan-out

​Searching files

​GrepResult

​Persistent sandboxes

​Mounting existing disks

​Private images

​Reading and writing objects

​Share URLs

​Managing API keys

​CLI

​Low-level protocol access

​Need a bash executor inside Node?

Configuration

Managing disks

Executing commands

`ExecResult`

Fan-out

Searching files

`GrepResult`

Persistent sandboxes

Mounting existing disks

Private images

Reading and writing objects

Share URLs

Managing API keys

CLI

Low-level protocol access

Need a bash executor inside Node?