| name | code-review |
| description | Patterns for code execution in the Podman sandbox. Covers run_code, serve mode, workspace management, and common failure modes. |
| agents | coder |
Code Execution Patterns
Sandbox Basics
You execute code in isolated Podman containers. Two modes:
| Mode | Tool | Use For |
|---|
| Run and capture | run_code | Scripts that produce output and exit |
| Serve | serve / stop_serve | Long-running processes (Flask, HTTP servers) |
Check sandbox status with sandbox_status before starting.
Writing Scripts
Always:
- Use stdlib only unless you install dependencies first (
sandbox_exec("pip install X"))
- Write self-contained scripts — don't assume state from previous runs
- Include error handling — uncaught exceptions produce unhelpful output
- Print results explicitly — the sandbox captures stdout
Never:
- Assume external network access (containers can reach localhost but not the internet)
- Write to locations outside the workspace directory
- Run scripts that take longer than 60 seconds (timeout)
- Assume packages are installed — check with
sandbox_exec("pip list")
Common Failure Modes
-
"Talking but not coding" — you respond with text about what you'd do
instead of actually calling run_code. If your task is to execute code,
call run_code.
-
Import failures — the container has Python stdlib only. Flask, requests,
pandas, etc. must be installed first via sandbox_exec("pip install X").
-
Script too large — if your script exceeds ~200 lines, split it into
multiple run_code calls. Write helpers to a file first, then import them.
-
Workspace state — use workspace_ls to see what files exist. Use
sandbox_exec("cat file.py") to read files in the workspace.
Port Forwarding (Serve Mode)
When using serve, ports are mapped deterministically:
- Container-internal ports: 47200-47204
- Host ports: calculated from slot number
After starting a server with serve:
- Check it's running:
sandbox_status
- Verify it responds:
sandbox_exec("curl -s http://localhost:47200/") (use the
internal container port 47200, not the host port)
- Test specific endpoints:
sandbox_exec("curl -s http://localhost:47200/api/health")
- Stop when done:
stop_serve
The cognitive loop can also verify from outside the container using fetch_url
with the host port shown in the serve response (e.g. http://localhost:10000/).
Verification
After run_code:
- Check the exit code (0 = success)
- Read stderr for warnings even if exit code is 0
- Verify the output matches expectations
- Don't assume success from a "succeeded" status — inspect the actual output
