Code Execution Tools

This page covers configuration for the built-in server-side code execution environment.

Use this together with Built-in Tools for request examples and runtime usage.

Supported code execution tools

The code execution subsystem provides:

Standalone endpoints are not provided for code execution tools. Use them through /v1/messages.

How it works

When the model submits a code_execution_v1 tool call, the server expands it into its constituent tools, creates or reuses a per-session sandbox, and executes the requested operations:

1. Tool expansion — code_execution_v1 expands into bash_v1, text_editor_v1, and optionally present_files_v1
2. Session management — each chat session gets an isolated workspace on the host filesystem
3. Path translation — canonical LLM-visible paths (/home/agent/workspace/) are transparently mapped to real host paths
4. Subprocess isolation — bash commands run as child processes with OS-level resource limits (setrlimit)
5. Output scrubbing — real host paths are removed from output before returning to the LLM

Code execution requires no external containers or Docker-in-Docker. The entire sandbox runs in the same process as the PrivateGPT server, using OS-level isolation primitives.

How to install

Code execution is part of the core PrivateGPT package. No additional extras are required:

$
uv sync --extra core

No OS-level libraries or external runtimes are needed for code execution.

Workspace layout

Each code execution session has a defined filesystem layout visible to the LLM:

All canonical paths are translated to host filesystem paths automatically. The LLM only sees and uses canonical paths.

Settings reference

code_execution settings

Code execution does not have a global enabled flag. The server always supports code execution when the tool is present in a request.

1
code_execution:
2
  provider: ${PGPT_CODE_EXECUTION_PROVIDER:local}
3
  workspace_path: ${PGPT_CODE_EXECUTION_WORKSPACE_PATH:}
4
  timeout: ${PGPT_CODE_EXECUTION_TIMEOUT:60}
5
  max_output_bytes: ${PGPT_CODE_EXECUTION_MAX_OUTPUT_BYTES:1048576}
6
  volume_root: ${PGPT_CODE_EXECUTION_VOLUME_ROOT:./local_data/private_gpt/volumes}

bash settings

Resource limits applied to each isolated bash subprocess via OS-level setrlimit:

1
bash:
2
  cpu_limit_seconds: ${PGPT_BASH_CPU_LIMIT_SECONDS:30}
3
  memory_limit_mb: ${PGPT_BASH_MEMORY_LIMIT_MB:512}
4
  fsize_limit_mb: ${PGPT_BASH_FSIZE_LIMIT_MB:10}
5
  nproc_limit: ${PGPT_BASH_NPROC_LIMIT:50}
6
  output_cap_bytes: ${PGPT_BASH_OUTPUT_CAP_BYTES:1048576}

Prompt configuration

Per-request, you can control whether code execution environment instructions are injected into the system prompt:

1
{
2
  "prompt_config": {
3
    "code_execution": true
4
  }
5
}

When true and a code execution tool is present, the prompt includes filesystem layout instructions and available paths. This flag only affects the system prompt — it does not enable or disable the tool itself.

Resource limits and sandboxing

Code execution applies two layers of output size control:

1. Raw subprocess cap (bash.output_cap_bytes, default 1 MiB) — hard truncation at the subprocess level
2. Tool output truncation (code_execution.max_output_bytes, default 1 MiB) — applied before returning results to the LLM

On Unix systems, each bash subprocess is isolated with:

• Process group isolation — os.setsid() prevents orphaned child processes
• CPU limit — RLIMIT_CPU caps CPU time
• Memory limit — RLIMIT_AS caps virtual memory
• File size limit — RLIMIT_FSIZE prevents runaway file creation
• Process count limit — RLIMIT_NPROC limits fork bombs
• Timeout enforcement — SIGKILL sent to the entire process group

On Windows, resource isolation is gracefully skipped.

Output scrubbing

All host filesystem paths are automatically removed from command output before being returned to the LLM. The LLM only sees canonical paths.

Session lifecycle

Code execution sessions are managed automatically:

• Creation — a new sandbox is created on the first code execution tool call in a chat session
• Reuse — subsequent code execution calls in the same chat session reuse the existing sandbox
• File persistence — workspace files survive across bash_v1 restart operations
• Idle expiry — sessions idle for longer than session_ttl_seconds (default 30 minutes) are destroyed by a background reaper
• Stale detection — if the sandbox process dies, it is transparently recreated on the next tool call

Platform compatibility

All platforms support the same canonical path translation, output scrubbing, and session lifecycle management.