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.

Quick Start

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

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

import { Agent } from 'praisonai';

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

executeCode(code, options?)

ExecuteCodeOptions:

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

When it throws

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

Related