> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentium.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Local sandbox backend

> Run trusted Node or Python code in an owned Unix workspace with bounded output.

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

```bash theme={null}
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:

```typescript local-workspace.ts theme={null}
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](/sandbox/e2b), [Daytona](/sandbox/daytona), or an appropriately isolated host service for untrusted programs. See [snapshots and ownership](/features/sandbox-agent) before attempting recovery.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.