Sandbox Agent

SandboxAgent keeps a workspace across explicit code and shell calls. Choose unix-local for trusted code or supply an explicit CloudSandbox with backend: "remote".

unix-local executes with the host user’s privileges. A temporary directory and file-helper path checks are not OS isolation. The unimplemented docker selector is rejected before files are created or processes are spawned.

Run trusted local code

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

const workspace = new SandboxAgent({
  backend: "unix-local",
  workspace: { files: [{ path: "input.txt", contents: "hello" }] },
  maxOutputBytes: 64 * 1024,
});
try {
  await workspace.start();
  const result = await workspace.run('console.log(process.cwd())', {
    language: "node",
    timeoutSeconds: 5,
  });
  console.log(result);
} finally {
  await workspace.close();
}

Node and Python source run as interpreter arguments. shell() and language: "shell" explicitly interpret shell syntax. Windows is not supported by this local backend.

Environment and lifecycle

Only PATH and explicitly selected inheritEnv, workspace environment, and per-run environment reach child processes. Starts are serialized. Close rejects new work, kills active process groups, waits for inherited output pipes, and removes the owned workspace. Detached descendants that escape the process group remain outside this contract. Local timeouts return timedOut: true and exit code 124; cancellation returns cancelled: true and exit code 130. Output overflow terminates the group and marks outputTruncated: true.

Files and snapshots

File helpers and manifests use canonical ancestor checks. Missing files return null; denied paths, dangling/external links, and read failures reject. Arbitrary programs and hostile concurrent filesystem mutation are outside helper confinement. Snapshots copy regular files up to 1,000 files / 16 MiB and omit symlinks. Resume closes the previous workspace before restoring snapshot files; initial git clones are not replayed. A snapshot is file data, not a checkpoint of running processes or external effects. Remote snapshots reject.

Remote execution

Supply an owned CloudSandbox port. The E2B and Daytona implementations are available from @agentium/core/toolkits; see cloud sandbox toolkits. Remote cancellation or request timeout is not proof that code stopped at the provider. Close waits for bounded adapter work and deletes owned resources. Reconcile uncertain external effects before retrying.

Build

Agent applications

Harness runtime

Teams and workflows

Data and capabilities

Interfaces and jobs

Voice and telephony

Verify and manage

Run trusted local code

Environment and lifecycle

Files and snapshots

Remote execution

​Run trusted local code

​Environment and lifecycle

​Files and snapshots

​Remote execution

Run trusted local code

Environment and lifecycle

Files and snapshots

Remote execution