code.execute

Schema

Input = {
  language: 'node' | 'python' | 'bash',
  code: string,                    // print to stdout; write files under the working directory to keep them
  files?: Array<{ path: string, content: string, encoding?: 'utf8' | 'base64' }>,
  args?: string[],
  timeoutMs?: number,               // up to MAX_TIMEOUT_MS, default 30s
  memoryMb?: number,                 // 64-4096, default 512
  env?: Record<string, string>,
}

Output = {
  stdout: string,
  stderr: string,
  exitCode: number,
  timedOut: boolean,
  durationMs: number,
  runtime: 'docker' | 'local',
  sandboxed: boolean,
  unsandboxed?: true,               // present only when it ran outside Docker
  files: string[],                   // files created/changed, relative to the workspace
  notes: string[],
}

Sandboxing

The real path runs inside the docker/sandbox image (Node + Python, no network by default, the project’s workspace folder bind-mounted as the working directory) — matching PLAN.md §1’s Docker sandbox spec exactly. If Docker isn’t available on the machine, code.execute fails closed by default: it returns exitCode: 126 and a message explaining that the code was not run, rather than falling back to the host. The host fallback is opt-in, not opt-out — set NOVA_SANDBOX_ALLOW_LOCAL=1 in .env on a machine you’re happy to hand to whoever can log in, and only then does a missing Docker install degrade to running the code unsandboxed, with every result flagged sandboxed: false, unsandboxed: true (packages/skills/src/code/sandbox.ts). Without Docker and without that flag, nothing the being submits ever reaches the host process.

code.execute is also one of the six world-acting skills: an agent calling it itself is refused unless a human approved it, regardless of Docker.

Python execution has numpy, pandas, and matplotlib available in the sandbox image, which is why generators like Data analysis can chart real data with this one skill rather than a separate charting service.

Example

curl -s -X POST http://localhost:4000/api/studio/skills/invoke \
  -H 'content-type: application/json' -b cookies.txt \
  -d '{"name":"code.execute","input":{"language":"python","code":"import pandas as pd\nprint(pd.Series([1,2,3]).mean())"}}'

{
  "ok": true,
  "output": {
    "stdout": "2.0\n", "stderr": "", "exitCode": 0, "timedOut": false,
    "runtime": "docker", "sandboxed": true, "files": [], "notes": []
  }
}