> ## 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.

# Sandbox backends

> Public sandbox backends signatures and configuration in @agentium/core 4.0.0.

Import these **3 exports** from `@agentium/core`. Read the [sandbox backends guide](/features/sandbox-agent) for setup and behavior, or return to the [package reference](/api-reference/core).

A `?` marks an optional field. These are declarations for lookup; run the examples in the linked guide. Follow related-type links for Agentium types and source links for imported dependency types.

## CloudSandbox

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/sandbox/types.ts)

```typescript theme={null}
export interface CloudSandbox {
    /** Provider identifier for logs / events. */
    readonly providerId: string;
    /** Initialize / connect to the remote session. Idempotent. */
    start(): Promise<void>;
    /** Run code inside the sandbox and capture stdout/stderr. */
    run(code: string, options?: SandboxRunOptions): Promise<SandboxRunResult>;
    /** Run a shell command inside the sandbox. */
    shell(command: string, options?: SandboxRunOptions): Promise<SandboxRunResult>;
    /** Write a file at `path` (UTF-8 or base64 if `encoding` set). */
    writeFile(path: string, contents: string, encoding?: "utf8" | "base64"): Promise<void>;
    /** Read a file at `path`. Returns the body or null if missing. */
    readFile(path: string, encoding?: "utf8" | "base64"): Promise<string | null>;
    /** Tear down the remote session. */
    close(): Promise<void>;
}
```

Related: [`SandboxRunOptions`](/api-reference/core/sandbox#sandboxrunoptions), [`SandboxRunResult`](/api-reference/core/sandbox#sandboxrunresult).

## SandboxRunOptions

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/sandbox/types.ts)

```typescript theme={null}
/**
 * Common interface for cloud sandbox providers (E2B, Daytona, custom Docker, ...).
 *
 * Adapter implementations live alongside individual toolkits in
 * `packages/core/src/toolkits/` and are exposed to agents as a small set of
 * tools (`sandbox.run`, `sandbox.shell`, `sandbox.writeFile`, `sandbox.readFile`).
 */
export interface SandboxRunOptions {
    /**
     * Language hint for the runtime. Adapters may use this to pick a kernel,
     * file extension, or interpreter. Common values: `"python"`, `"node"`,
     * `"shell"`. Defaults to `"python"`.
     */
    language?: "python" | "node" | "shell";
    /** Maximum wall-clock seconds. Default: 30. */
    timeoutSeconds?: number;
    /** Abort local execution. Remote adapters check before/after calls; see their documented cancellation limits. */
    signal?: AbortSignal;
    /** Optional environment variables. */
    env?: Record<string, string>;
}
```

## SandboxRunResult

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/sandbox/types.ts)

```typescript theme={null}
export interface SandboxRunResult {
    /** Combined stdout + stderr. */
    output: string;
    /** Exit code reported by the runtime; 0 on success. */
    exitCode?: number;
    /** True when the run was terminated due to timeout. */
    timedOut?: boolean;
    /** Local process group was canceled and its output pipes settled. */
    cancelled?: boolean;
    /** Captured output exceeded its configured limit. */
    outputTruncated?: boolean;
}
```


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