Agent infrastructure · Field guide · 9 min read

A coding agent needs a computer, not another tool wrapper.

A capable coding agent reads a repository, starts language servers, installs dependencies, runs tests, and edits many files. Giving it a disposable Linux workspace keeps that work useful without making the laptop, CI runner, or control plane part of its trust boundary.

01 · The boundary

Give the agent one complete workspace.

The useful unit is not one tool call. It is a machine whose files and processes survive between tool calls. BoltzLabs sandboxes run as gVisor containers with a read-only base image and a writable workspace. The agent can mutate its own world without receiving access to the host that schedules it.

Environment	Executable	Included
opencode	opencode	OpenCode
claude-code	claude	Claude Code
codex	codex	OpenAI Codex CLI
deepagents	dcode	Deep Agents Code
aider	aider	Aider

Every image shares Git, ripgrep, jq, tmux, Python, Node, and the /workspace convention. Each image installs exactly one agent. This keeps versions and failure reports attributable instead of producing one oversized image with five independent release cycles.

02 · Start one

Create, connect, authenticate.

The CLI recognizes agent environments and enables outbound internet by default because their login and model calls need it. Pass --no-internet when the task is deliberately offline. The Python SDK follows the platform default instead, so its call must say internet=True explicitly.

terminal shell

# The agent image includes the executable, not your account or provider keys.
bzlabs create   --environment opencode   --machine medium   --name fix-142

bzlabs connect fix-142

sandbox terminal shell

# Inside the sandbox. /workspace is the persistent working directory.
git clone https://github.com/psf/requests.git .

# Authenticate the agent using its normal login flow, then start it.
opencode

# Ctrl-D leaves the shell. It does not destroy the sandbox.

The image contains no credentials.

BoltzLabs installs the executable, not a provider account, API key, Git credential, or agent configuration. Use the agent's normal authentication flow after connecting. Treat secrets in the sandbox as task-scoped and destroy them with the workspace.

03 · Drive it from Python

Use the PTY for interactive agents.

Agent CLIs own terminal echo, colors, prompts, Ctrl-C, and sometimes full-screen interfaces. terminal() connects a real PTY; exec() is for finite non-interactive setup and verification commands.

agent_workspace.py

from boltzlabs import Sandbox

# Python does not infer agent networking, so opt in explicitly.
sb = Sandbox(
    environment="opencode",
    machine="medium",
    name="fix-142",
    internet=True,
)

try:
    sb.exec("git clone https://github.com/psf/requests.git /workspace/requests").check()
    sb.terminal()  # authenticate and drive the agent through a real PTY
finally:
    sb.delete()

A context manager is convenient for fully automated work. For an interactive review loop, keep the sandbox, reconnect by its name, inspect the diff, and destroy it only after the result is accepted.

04 · Inspect and destroy

The lifecycle is part of correctness.

Leaving a terminal does not delete the machine. That is useful: tests and agent processes can keep running, and a reviewer can reconnect. It also means disconnect is not cleanup. The sandbox bills and retains task credentials until an explicit delete.

terminal shell

bzlabs exec fix-142 "cd /workspace/requests && git status --short"
bzlabs exec fix-142 "cd /workspace/requests && pytest -q"

# Review first. Destroying the sandbox is irreversible.
bzlabs rm fix-142

sandbox terminal shell

root@sandbox:/workspace# boltz-harness
BoltzLabs agent harness
workspace: /workspace

tool           status
opencode       installed
claude         not installed in this image
codex          not installed in this image
dcode          not installed in this image
aider          not installed in this image

05 · Current boundary

Do not design around features that are not there.

Repository transfer

Clone from the network or create files through commands. There is no dedicated upload or snapshot API.

Agent state

The writable workspace survives commands and reconnects, but it is not a reusable image template.

Output

Finite exec calls return captured output. They do not stream a running agent session. Use the PTY for interactive output.

Lifetime

Destroy explicitly. Do not use disconnect, idle timeout fields, or max-lifetime fields as a cleanup guarantee today.

Read the sandbox API Create an API key