Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.archil.com/llms.txt

Use this file to discover all available pages before exploring further.

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.
PackageWhen to use
diskManage disks, run commands with disk.exec, manage API keys. The default.
@archildata/nativeSpeak 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(
  "grep -r ERROR 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(`grep -c ERROR logs/${f}`)),
);
See the bash tool for agents guide for an end-to-end example wiring disk.exec into an AI agent loop.

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