@archildata/native

Not recommended for most use cases. This package exposes Archil's low-level filesystem protocol (inodes, delegations, byte-level reads and writes, permission checks) to Node.js via a native addon. It's useful if you're building a custom client runtime on top of Archil, but it's the wrong tool for most people.

• If you want to create, list, inspect, or run commands against an Archil disk from code or a CLI, use disk — disk exec <id> <cmd> is the serverless way to run commands against a disk without talking to any filesystem protocol at all.
• If you want to mount an Archil disk as a local filesystem, install the archil CLI — it uses the OS kernel's FUSE layer so you can read and write files with standard tools.

This package is still published for the small number of integrations that genuinely need raw protocol access from Node.

Low-level Node.js client for Archil — speaks the Archil filesystem protocol directly (no mount, no FUSE, no kernel). Implemented as a napi-rs native addon so the hot path is Rust, surfaced through a JavaScript API.

Install

npm install @archildata/native

Ships prebuilt binaries for Linux (x64, arm64, glibc) and macOS (arm64). Other platforms aren't supported.

Usage

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

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

// Look up a file by name in the root directory (inode 1)
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());

await client.close();

Writing files

Archil uses delegations for writes. Check out before writing, check in when done:

await client.checkout(inodeId);
await client.writeData(inodeId, 0, Buffer.from('new contents'));
await client.sync();
await client.checkin(inodeId);

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 page.nextCursor back into readDirectory. When nextCursor is undefined, you've seen everything.

Creating files and directories

const dir = await client.create(1, 'mydir', {
  inodeType: 'Directory',
  uid: 1000, gid: 1000, mode: 0o755,
});

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

Renaming and deleting

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

Always await client.close() when done — this flushes pending writes and releases delegations.

Support

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