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

# Sandbox

> Run Agent code in an isolated sandbox with agent.executeCode().

`sandbox` gives an Agent an isolated place to run code, and `agent.executeCode()` runs a one-shot snippet there.

<Note>
  This is the generic-Agent sandbox. For the dedicated code-writing / executing / reviewing agent, see [CodeAgent](/docs/js/code-agent) and its `execute()` method.
</Note>

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    C[💻 code] --> S[🔎 static safety scan]
    S --> R[📦 sandbox runner]
    R --> O([SandboxResult])

    classDef in fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef step fill:#189AB4,stroke:#7C90A0,color:#fff

    class C in
    class S,R step
    class O step
```

## Quick Start

<Steps>
  <Step title="Give the agent a sandbox">
    ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    import { Agent } from 'praisonai';

    const agent = new Agent({ instructions: 'Run code', sandbox: true });
    const result = await agent.executeCode('print(2 + 2)', { language: 'python' });
    console.log(result.stdout);   // "4\n"
    console.log(result.success);  // true
    ```

    `sandbox: true` selects the built-in `subprocess` sandbox.
  </Step>

  <Step title="Name a place per call">
    ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    import { Agent } from 'praisonai';

    const agent = new Agent({ instructions: 'Assist' });
    await agent.executeCode('echo hi', { language: 'bash', runIn: 'subprocess' });
    ```
  </Step>
</Steps>

***

## `SandboxConfig`

Pass `true`, a sandbox type string, or a config object.

| Field          | Type                      | Default              |
| -------------- | ------------------------- | -------------------- |
| `sandboxType`  | `string`                  | `'subprocess'`       |
| `image`        | `string`                  | `'python:3.12-slim'` |
| `workingDir`   | `string`                  | `'/workspace'`       |
| `env`          | `Record<string, string>`  | `{}`                 |
| `autoCleanup`  | `boolean`                 | `true`               |
| `persistFiles` | `boolean`                 | `false`              |
| `timeout`      | `number`                  | `30` (seconds)       |
| `metadata`     | `Record<string, unknown>` | `{}`                 |

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent } from 'praisonai';

const agent = new Agent({
  instructions: 'Run code',
  sandbox: { sandboxType: 'subprocess', timeout: 10, persistFiles: true },
});
```

## `executeCode(code, options?)`

`ExecuteCodeOptions`:

| Field           | Type                                 | Notes                                                    |
| --------------- | ------------------------------------ | -------------------------------------------------------- |
| `language`      | `string`                             | `'python'` (default), `'bash'`, `'javascript'`, ...      |
| `checkSecurity` | `boolean`                            | Run the static pre-check (default `true`).               |
| `runIn`         | `boolean \| string \| SandboxConfig` | Where to run THIS call; overrides the agent's `sandbox`. |

The method returns a `SandboxResult`:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
interface SandboxResult {
  success: boolean;
  stdout: string;
  stderr: string;
  exitCode: number;
  metadata?: Record<string, unknown>; // includes securityWarnings when any fired
}
```

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent } from 'praisonai';

const agent = new Agent({ instructions: 'Run code', sandbox: true });
const result = await agent.executeCode('import os\nos.system("ls")', { language: 'python' });
console.log(result.metadata?.securityWarnings); // static analysis warnings
```

<Note>
  The static scan is best-effort pattern matching for the operator's awareness. The sandbox is what actually isolates — a warning does not stop execution.
</Note>

## When it throws

<Warning>
  ```text theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  # a config field that is not recognised
  Error: Unknown sandbox field(s): foo. Valid fields: sandboxType, image, workingDir, env, autoCleanup, persistFiles, timeout, metadata

  # a sandbox type with no registered runner
  Error: No sandbox runner is registered for "docker" (available: subprocess).
    A remote sandbox is a provider integration: register one with registerSandboxRunner('docker', ...).

  # executeCode() with no sandbox configured and no runIn
  Error: Agent NAME: no sandbox configured. Either name a place on the call --
      agent.executeCode(code, { runIn: 'subprocess' })
    or set a default for every call with new Agent({ sandbox: true }).
  ```
</Warning>

`executeCode()` with an unknown `runIn` type throws the same "no runner registered" error.

## Registering a remote runner

`docker`, `e2b` and friends are provider integrations a host supplies:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { registerSandboxRunner } from 'praisonai';

registerSandboxRunner('docker', (config) => ({
  sandboxType: 'docker',
  async execute(code, { language }) {
    // run `code` in a container built from config.image ...
    return { success: true, stdout: '', stderr: '', exitCode: 0 };
  },
}));
```

## Related

<CardGroup cols={2}>
  <Card title="Agent" icon="robot" href="/docs/js/agent">
    executeCode & options
  </Card>

  <Card title="Placement" icon="server" href="/docs/js/placement">
    Where tools run
  </Card>
</CardGroup>