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 works on any platform Node.js does. 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" });

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.

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

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.

​Configuration

​Managing disks

​Executing commands

​ExecResult

​Fan-out

​Searching files

​GrepResult

​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`

Reading and writing objects

Managing API keys

CLI

Low-level protocol access

Need a bash executor inside Node?