Sandbox - PraisonAI

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

Quick Start

Give the agent a sandbox

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.

Name a place per call

import { Agent } from 'praisonai';

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

`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>`	`{}`

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:

interface SandboxResult {
  success: boolean;
  stdout: string;
  stderr: string;
  exitCode: number;
  metadata?: Record<string, unknown>; // includes securityWarnings when any fired
}

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

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.

When it throws

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

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:

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 };
  },
}));

Agent

executeCode & options

Placement

Where tools run

​Quick Start

​SandboxConfig

​executeCode(code, options?)

​When it throws

​Registering a remote runner

​Related

Agent

Placement

Quick Start

`SandboxConfig`

`executeCode(code, options?)`

When it throws

Registering a remote runner

Related