@detail-dev/sahara

Typed TypeScript client for Sahara's public control-plane API and proxy data plane. Node >= 20 (developed against Node 22), zero runtime dependencies, dual ESM builds. Publication and deployed version must be established from release receipts. This package exposes the supported consumer SDK, not an operator CLI.

Install a public release with npm install @detail-dev/sahara; prereleases use @detail-dev/sahara@next. For local development, use a packed archive or workspace path. Maintainers release reviewed SDK versions through SDK publishing, independently of service/runtime releases.

Sandbox handles are opaque strings (sb_ followed by 16 lowercase hex digits), permanently nonreused even after Forget. Other 64-bit identities (executions, incarnations, stream positions, preemption attempts) are bigint; the wire carries canonical decimal strings and the boundary converts them. Response documents are decoded strictly: unknown fields are rejected, matching the server's deny_unknown_fields contracts.

import { SaharaClient } from "@detail-dev/sahara";

const client = new SaharaClient({
    apiBase: "http://control-plane.internal/", // private local example only
    proxyBase: "http://proxy.internal/", // required for files, tunnels and SSH material
    token: process.env.SAHARA_TOKEN!,
    // proxyToken: process.env.SAHARA_PROXY_TOKEN, // when the proxy token differs
});

Use TLS or an encrypted tunnel for public or otherwise untrusted traffic. Restricted trusted cluster/VPC links may use plaintext. Private runtime/helper traffic has separate authentication and fencing requirements; this client does not grant internal ownership through a public bearer token. Every valid public token has full service access.

Idempotency and errors

An acknowledgement is a confirmed durable commit. A timeout, a dropped connection, or a 5xx is ambiguous — the request may have committed. Durable mutations return a durable Ack without a follow-up read (createSandbox, exec, closeSandbox, cancelExecution, ackPreemption) retry or reconcile under the identical caller-chosen identity within a bounded budget (default <= 30 s, configurable via retry). They never re-issue under a new identity. heartbeatSandbox repeats cache-only renewal for the same logical sandbox on transient failures within that budget; it does not extend the absolute expiry or provide a durable ACK. File writes perform one bounded attempt; mayHaveApplied records an ambiguous publication response without replay or inspection.

• 409 surfaces as SaharaConflictError with the server's kind — including the discovered case where the identity is already bound to a different intent.
• 401 is fatal (SaharaAuthenticationError, never retried).
• 404 is SaharaNotFoundError.
• Malformed wire documents are SaharaContractError (kind "contract", never retried).
• Caller cancellation is supported through CallOptions or the operation's query/binding signal; an aborted attempt is never retried.

Create, Ready, execute, and close

The sandbox shape is fixed at 8 vCPU (8000 mCPU), 32 GiB RAM (34359738368 bytes), and a 128 GiB sparse disk (137438953472 bytes). No resource selector belongs in CreateSandbox; aggregate host overcommit is a separate admission policy, not a per-sandbox ceiling.

const id = "sb_0000000000000001"; // choose an unused service identity
await client.createSandbox(id, {
    image: 1n, // published image identity available to this service
    expires_at_ms: BigInt(Date.now()) + 3_600_000n,
    metadata: { cohort: "detail-five" },
});

let sandbox = await client.getSandbox(id);
while (sandbox.phase === "Pending" || sandbox.phase === "Booting") {
    await new Promise((resolve) => setTimeout(resolve, 500));
    sandbox = await client.getSandbox(id);
}
if (sandbox.phase !== "Ready") throw new Error(`sandbox phase: ${sandbox.phase}`);

const executionId = 100n;
await client.exec(id, executionId, {
    command: "/work/run.sh",
    env: { MODE: "eval" },
});
let poll = await client.getExecution(executionId);
while (poll.status === "Accepted") {
    await new Promise((resolve) => setTimeout(resolve, 500));
    poll = await client.getExecution(executionId);
}
if (typeof poll.status !== "object" || !("Completed" in poll.status)) {
    throw new Error("execution did not complete");
}
const exitCode = poll.status.Completed;
const output = await client.readExecutionOutput(id, executionId, {
    stream: "stdout",
    offset: 0n,
    limit: 1_048_576n,
});
// output.bytes is bounded; output.complete means the process domain is quiescent.

For large output, consume one proxy stream instead of requesting successive slices:

const output = await client.streamExecutionOutput(id, executionId, { stream: "stdout" });
for await (const bytes of output.chunks) await sink.write(bytes);
const receipt = output.receipt(); // exact length + SHA-256, only after verified trailers

Output remains on the guest disk. The proxy authenticates the request locally, resolves one runtime, and relays bounded chunks from one retained descriptor. An active execution can provide a verified snapshot with complete === false; finishing that snapshot does not prove the process domain is quiescent. Each requested pull has the configured request timeout; caller processing time between pulls is not idle time. Neither output method automatically retries or falls back to the control-plane byte route. readExecutionOutput still collects at most 1 MiB under the configured per-attempt request deadline. Use cancel() for an unconsumed stream; abandoning an active iterator cancels its response.

Matching guest/runtime binaries must use the current retained-output format, which includes boot, sandbox, creation, incarnation and execution. Older output names do not acquire a creation identity from a new reader. Deployment and persisted-output adoption require separate qualification.

Sandbox handles remain stable across recovery. The service durably binds accepted execution IDs to their first runtime; retries never retarget them. File calls resolve one runtime per request. creation and incarnation are diagnostic fields; heartbeat and SSH take only the logical sandbox handle.

Ready census pages

For a fixed-prefix census, request up to 500 rows per page and follow next_cursor through the terminal page, including when that page is empty:

let cursor: string | undefined;
let through: bigint | undefined;
let position: bigint | undefined;
const readyIds = new Set<string>();
do {
    const page = await client.listSandboxesPage({ phase: "Ready", limit: 500, cursor });
    if (through !== undefined && page.through !== through) throw new Error("cutoff moved");
    if (position !== undefined && page.position !== position) throw new Error("prefix moved");
    through = page.through;
    position = page.position;
    for (const row of page.sandboxes) readyIds.add(row.id);
    cursor = page.next_cursor ?? undefined;
} while (cursor !== undefined);

This is a historical committed-prefix observation, not proof that all guests remain Ready or that provider capacity and Detail work have passed. Check exact IDs, creation, incarnation, fixed resources, and run metadata as well as the count, then retain separate runtime and teardown evidence.

Events and preemption acknowledgement

const controller = new AbortController();
const signal = controller.signal;
for await (const frame of client.events(sandbox.id, { signal })) {
    if (frame.type === "overflow") {
        // cursor fell outside the retained window — reconcile by reading
        continue;
    }
    const event = frame.event;
    if (event.kind === "preemption") {
        await client.ackPreemption(sandbox.id, event.attempt);
    }
    // frame.id is the durable cursor; persist it to resume with
    // client.events(id, { lastEventId: frame.id })
}

The iterator reconnects transport failures with Last-Event-ID, tolerates keepalive frames, detects stalls, and ends on clean close.

TCP tunnel

const stream = await client.connectTcp(sandbox.id, 8080);
stream.write(payload);
stream.on("data", (chunk) => {
    /* ... */
});

Or forward a loopback port — every accepted local socket gets its own tunnel stream:

const forward = await client.forwardLocalPort(sandbox.id, 8080);
console.log(`localhost:${forward.port}`);
await forward.stop();

SSH material for a logical sandbox

const ssh = await client.sshMaterial(sandbox.id);
// { user, host_public_key, port, private_key_pem }
// present only while the resolved runtime is live

Consumer images

for await (const entry of client.listImages()) {
    const image = await client.getImage(entry.id);
    console.log(image.id, image.phase);
    // await client.deleteImage(image.id); // tombstones this shared catalog entry
}
// Public list/get include captured images and operator-imported base images.
// Every accepted public token sees the same catalog; there is no per-token owner.
// Public deletion uses the same catalog operation as operator deletion.
// Image import remains an operator API, not a public client operation.

Guest files: bounded streaming and final receipts

import { createHash } from "node:crypto";
import { createReadStream, createWriteStream } from "node:fs";
import { stat } from "node:fs/promises";
import { pipeline } from "node:stream/promises";

const local = "/tmp/report.json";
const { size } = await stat(local, { bigint: true });
const hash = createHash("sha256");
for await (const chunk of createReadStream(local, { highWaterMark: 1 << 20 })) {
    hash.update(chunk);
}
const sha256 = hash.digest("hex");
const binding = {
    path: "/home/user/report.json", // inside the default confined guest roots
    length: size,
    sha256,
    mode: "0640",
};
const written = await client.writeFile(id, binding, () =>
    createReadStream(local, { highWaterMark: 1 << 20 }),
);
if (written.size !== size || written.sha256 !== sha256) throw new Error("receipt mismatch");

const download = await client.readFile(id, {
    path: binding.path,
});
await pipeline(download.chunks, createWriteStream("/tmp/roundtrip.json"));
const receipt = download.receipt(); // only available after final HTTP trailers verify
if (receipt.length !== size || receipt.sha256 !== sha256) {
    throw new Error("file changed between upload and download");
}
await client.closeSandbox(id); // logical close; verify physical teardown separately

An upload source is consumed once per explicit call. The client hashes its bounded pulls and accepts only a matching size/digest publication receipt. A lost reply may hide a published file: inspect mayHaveApplied, and decide whether another independent write is appropriate. There is no public transfer ID or inspection endpoint. writeFileBytes/writeFileText handle small caller-owned buffers; readFileBytes requires maxBytes and verifies terminal integrity before return. Stream large files and stage downloaded bytes until receipt() succeeds.

Origins must be HTTP(S) root origins, with no userinfo, path prefix, query or fragment. Redirects are disabled. Files use proxy credentials. Ordinary JSON calls share configurable 30 second total/15 second attempt budgets,250 ms exponential backoff capped at 5 seconds before jitter. SSE reconnects connection EOF and partial frames from the last fully decoded cursor; only delivered application events reset its consecutive-failure window. Empty successful opens cannot reset it. A closed event or cancellation ends the subscription. Stream setup includes refusal bodies; healthy subscriptions have no total lifetime cap.

Uploads have a separate 30 minute complete-attempt deadline, including bytes and the publication response. Override attemptTimeoutMs on streaming or byte/text uploads; this never enables replay. Ordinary JSON calls retain their shorter retry budgets.

File downloads use retry.requestTimeoutMs (15 seconds by default) for the single GET setup, including any refusal body, then a 45 second idle read bound with no total healthy-stream deadline. The idle deadline runs only while the iterator requests bytes or terminal trailers, so downstream backpressure does not expire a healthy stream. Call cancel() or abort the signal to stop it; partial files are never replayed.

Authentication and binding checks

• Invalid public tokens fail with SaharaAuthenticationError; all valid tokens share service access.
• Reusing an operation ID with different immutable intent conflicts. Accepted work never silently follows recovery.
• A stale expected_sha256_before precondition cannot overwrite a changed destination.
• Paths remain confined to the server's permitted guest roots.
• Source tests cover single-attempt publication, sticky ambiguity, malformed receipts and trailer failures.

Pressure observations arrive on the sandbox event stream as event.kind === "pressure" frames (resource, level, cleared, value, threshold, since_ms).

Consuming from the Detail monorepo

Build the tarball and install the retained, source-hashed artifact as a file dependency:

cd clients/typescript
pnpm install --frozen-lockfile && pnpm check:generated && pnpm build
pnpm pack && pnpm smoke:installed

In apps/backend/package.json:

{
    "dependencies": {
        "@detail-dev/sahara": "file:../../vendor/detail-dev-sahara-<VERSION>.tgz"
    }
}

Or vendor the whole package directory and use a pnpm workspace link: / file: path to it. The package ships dist/esm with .d.ts declarations. CommonJS consumers must use dynamic import().

Regenerating contracts

pnpm generate runs cargo xtask contracts at the repo root and re-emits src/generated/* (types + codecs + operation manifest). pnpm check:generated fails on drift; run it in CI after any server-side API change.

Testing

pnpm test    # unit tests + contract suite against owned postgres + valkey
             # containers plus sahara-sim-runtime + sahara-control-plane
             # (binaries built at the repo root; requires Docker)

To point the suite at a real deployment instead — for example a cargo xtask physical-e2e --hold assembly, which prints every one of these — set:

SSE resume IDs are exact strings: the service emits a 20-digit zero-padded u64 position, a hyphen, and a u64 ordinal padded to at least four digits. Larger committed batches can emit wider ordinals such as 10000. Both fields are bounded to 20 decimal digits and the u64 maximum (18446744073709551615). Clients also accept bounded unpadded decimal pairs, but callers should pass the received cursor unchanged rather than construct or normalize one. Clients preserve its exact bytes when sending Last-Event-ID; padding is distinct from the canonical decimal strings used in JSON DTOs.