@archildata/client

Node.js client for Archil — a high-performance distributed filesystem that turns your cloud storage (S3, GCS, Azure Blob, R2) into something you can read, write, and run commands against like a local disk.

Quick Start: Connect an S3 Bucket

This walks you through creating an Archil disk backed by your S3 bucket and running bash commands on it. The whole thing takes about two minutes.

1. Sign up

Go to console.archil.com and create an account.

2. Install

npm install @archildata/client

3. Create a disk

An Archil "disk" is a filesystem that sits in front of your cloud storage. You create one by telling Archil which bucket to use. This doesn't move or copy your data — Archil reads and writes directly to your bucket.

A mount token is automatically generated when you create a disk; it is recommended to save it.

import { Archil } from '@archildata/client/api';

const archil = new Archil({
  apiKey: 'your-api-key',
  region: 'aws-us-east-1',
});

const { disk, token } = await archil.disks.create({
  name: 'my-disk',
  mounts: [{
    type: 's3',
    bucketName: 'my-bucket',
    accessKeyId: 'AKIA...',
    secretAccessKey: '...',
    bucketPrefix: 'data/',  // optional — only expose a subfolder of the bucket
  }],
});

console.log(`Created disk: ${disk.organization}/${disk.name}`);
console.log(`Mount token: ${token}`);  // save this — it won't be shown again

You only do this once. After that, the disk is available by name whenever you want to connect.

4. Run bash commands on it

Install @archildata/just-bash to get a shell that runs against your disk:

npm install @archildata/just-bash

Then connect using the mount token from step 3:

ARCHIL_DISK_TOKEN=<your-mount-token> npx @archildata/just-bash aws-us-east-1 myaccount/my-disk

This drops you into an interactive shell. The files you see are the contents of your S3 bucket:

$ ls
data/  logs/  config.json

$ cat config.json
{"version": 2, "debug": false}

$ echo "hello from archil" > greeting.txt

Everything you do here — reads, writes, renames, deletes — goes through Archil to your bucket.

Using just-bash Programmatically

The interactive shell is great for poking around, but you can also run bash commands from your own code. This is useful for scripts, CI pipelines, or anywhere you want to run shell commands against your disk without mounting it.

import { ArchilClient } from '@archildata/client';
import { ArchilFs, createArchilCommand } from '@archildata/just-bash';
import { Bash } from 'just-bash';

// Connect to your disk
const client = await ArchilClient.connect({
  region: 'aws-us-east-1',
  diskName: 'myaccount/my-disk',
  authToken: '<your-mount-token>',
});

// Create a filesystem adapter and a bash executor
const fs = await ArchilFs.create(client);
const bash = new Bash({
  fs,
  customCommands: [createArchilCommand(client, fs)],
});

// Run commands just like you would in a terminal
const result = await bash.exec('ls -la /');
console.log(result.stdout);

// Write a file
await bash.exec('echo "hello world" > /greeting.txt');

// Read it back
const cat = await bash.exec('cat /greeting.txt');
console.log(cat.stdout); // "hello world"

// Clean up
await client.close();

You can also use the filesystem adapter directly without bash, if you just need standard file operations:

const fs = await ArchilFs.create(client);

// These work like their Node.js fs equivalents
await fs.writeFile('/notes.txt', 'some content');
const content = await fs.readFile('/notes.txt');
const entries = await fs.readdir('/');
const stats = await fs.stat('/notes.txt');
await fs.mkdir('/mydir', { recursive: true });
await fs.cp('/notes.txt', '/mydir/notes-copy.txt');
await fs.rm('/notes.txt');

Using the Native Client Directly

For more control, you can use the ArchilClient directly. This gives you access to the full filesystem protocol — inodes, delegations, paginated directory reads, etc.

Connecting

import { ArchilClient } from '@archildata/client';

const client = await ArchilClient.connect({
  region: 'aws-us-east-1',
  diskName: 'myaccount/my-disk',
  authToken: '<your-mount-token>',
});

Reading files

Every file and directory on an Archil disk has an inode ID. The root directory is always inode 1. You navigate by looking up names inside directories, then reading the inodes you find.

// Look up a file by name in the root directory
const entry = await client.lookupInode(1, 'config.json');

// Read its contents
const data = await client.readInode(entry.inodeId, 0, entry.attributes.size);
console.log(data.toString());

Listing directories

const handle = await client.openDirectory(1);
const page = await client.readDirectory(1, handle, 100);

for (const entry of page.entries) {
  console.log(`${entry.name} (${entry.inodeType})`);
}

client.closeDirectory(1, handle);

For large directories, pass the returned page.nextCursor back into readDirectory to get the next page. When nextCursor is undefined, you've seen everything.

Writing files

Archil uses a delegation model for writes. Before you can write to a file, you "check out" a delegation on it — this tells the server you intend to modify it and gives you exclusive access. When you're done, you "check in" to release it so other clients can write.

// Check out the file to acquire a write delegation
await client.checkout(inodeId);

// Write data
await client.writeData(inodeId, 0, Buffer.from('new contents'));

// Make sure the write is durable on the server
await client.sync();

// Release the delegation so other clients can write
await client.checkin(inodeId);

Creating files and directories

// Create a directory in root (inode 1)
const dir = await client.create(1, 'mydir', {
  inodeType: 'Directory',
  uid: 1000,
  gid: 1000,
  mode: 0o755,
});

// Create a file inside it
const file = await client.create(dir.inodeId, 'data.txt', {
  inodeType: 'File',
  uid: 1000,
  gid: 1000,
  mode: 0o644,
});

// Write to the new file
await client.checkout(file.inodeId);
await client.writeData(file.inodeId, 0, Buffer.from('file contents'));
await client.checkin(file.inodeId);

Renaming and deleting

await client.rename(parentInodeId, 'old.txt', parentInodeId, 'new.txt');
await client.unlink(parentInodeId, 'new.txt');

Cleaning up

Always close the client when you're done. This flushes pending writes and releases any delegations you're still holding.

await client.close();

Managing Disks

The control plane API lets you manage disks and access control after initial setup.

import { Archil } from '@archildata/client/api';

const archil = new Archil({
  apiKey: 'your-api-key',
  region: 'aws-us-east-1',
});

// List your disks
const disks = await archil.disks.list();

// Get a specific disk by ID
const disk = await archil.disks.get('dsk-xxx');

// Add an additional mount token to an existing disk
const { token, identifier } = await disk.createToken('ci-token');
// save `token` — it's only returned once
// use `identifier` to manage or remove the token later

// Remove access
await disk.removeTokenUser(identifier);

// Delete a disk (this does not delete your bucket data)
await disk.delete();

Going from a disk to a client

If you have a Disk object from the API, you can connect directly without specifying the region and name again:

const disk = await archil.disks.get('dsk-xxx');
const client = await disk.mount({ authToken: '<your-token>' });

// client is an ArchilClient — use it for reads, writes, etc.
await client.close();

Supported Regions

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

Supported Storage Backends

• Amazon S3 (type: 's3')
• Google Cloud Storage (type: 'gcs')
• Azure Blob Storage (type: 'azure-blob')
• Cloudflare R2 (type: 'r2')
• S3-compatible services (type: 's3-compatible')

Platform Support

The control plane API (@archildata/client/api) works on any platform — macOS, Windows, Linux.

The native filesystem client (connecting to disks, reading/writing files) supports Linux (x64 or arm64, glibc) and macOS (Apple Silicon / arm64). On other platforms, the API-only imports still work.

Support

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