Local sandbox backend

Use unix-local for code you trust to run with the host user’s permissions. No container, VM, or OS sandbox is created.

npm install @agentium/core@4.0.0
npm install --save-dev tsx

Save as local-workspace.ts and run npx tsx local-workspace.ts on a supported Unix host:

local-workspace.ts

import { SandboxAgent } from "@agentium/core";

const sandbox = new SandboxAgent({
  backend: "unix-local",
  workspace: { files: [{ path: "message.txt", contents: "Hello from Agentium" }] },
  maxOutputBytes: 64 * 1024,
});
try {
  await sandbox.start();
  const result = await sandbox.run(
    'console.log(require("node:fs").readFileSync("message.txt", "utf8"))',
    { language: "node", timeoutSeconds: 5 },
  );
  if (result.exitCode !== 0) throw new Error(`Local run failed: ${JSON.stringify(result)}`);
  console.log(result.output);
} finally {
  await sandbox.close();
}

Expected output includes Hello from Agentium. Close removes the owned workspace and rejects new work.

Environment and cancellation

Only PATH and explicitly configured inheritEnv, workspace environment, and per-run environment reach the child. Node/Python source is passed as interpreter input; shell() and language: "shell" explicitly invoke shell semantics. Timeout returns timedOut: true and exit code 124. Cancellation returns cancelled: true and exit code 130. Output overflow terminates the process group and marks truncation. Descendants that escape that group remain outside the cleanup contract. File helpers check canonical paths, but arbitrary code is not confined to the workspace. Use E2B, Daytona, or an appropriately isolated host service for untrusted programs. See snapshots and ownership before attempting recovery.

Find an integration

Voice and call adapters

Sandbox and telemetry

Providers and services

Protocols and devices

Local sandbox backend

Environment and cancellation

​Environment and cancellation

Environment and cancellation