disk

Node.js client 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.

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.

Library

The recommended pattern is a module-namespace import:

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

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

Named imports

If you prefer named imports over the namespace style, they work the same way:

import { createDisk, getDisk, listDisks, configure } from "disk";

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

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