Inside DevBox: How a Full-Agent-in-Sandbox Architecture Generates PRs Automatically

In AI agent architecture design, "sandbox-as-tool" and "full-agent-in-sandbox" are two common patterns. In a Reddit discussion thread, a developer shared the reasoning and implementation details behind choosing the latter for the DevBox project. DevBox is an autonomous engineering test harness built on Deep Agents, aiming to automatically turn tasks into draft PRs. This article breaks down its architecture, key trade-offs, and lessons that can be borrowed.

Why choose the full-agent sandbox pattern?

After reading a comparative analysis of "sandbox-as-tool vs. full-agent-in-sandbox," the original author decided to adopt the full-agent sandbox pattern. In this mode, each task runs in an isolated sandbox where the agent has a complete operating environment rather than merely calling tool interfaces exposed by the sandbox. The core motivation for this choice is isolation and the flexibility of state management—within the sandbox, the agent can freely execute commands and modify files without affecting the host machine or other tasks.

DevBox is positioned as an "autonomous engineering test harness." It receives a task description and ultimately produces a draft PR. Each task corresponds to an independent sandbox instance, within which the agent handles code modification, testing, and submission preparation. This design naturally isolates tasks from one another, avoiding race conditions caused by shared state.

Sandbox-as-tool: In this mode, the agent runs in a controlled main environment, and the sandbox is exposed only as a callable tool with limited interfaces (executing commands, reading and writing files, etc.), returning a result on each call. Its advantages are fast startup, high resource reuse, and centralized agent orchestration logic; its drawbacks are the interface boundary between the agent and the sandbox, which requires multiple round trips for complex operations, and that multiple sub-agents sharing the same sandbox can see each other's state, easily causing races and contamination. In contrast, full-agent-in-sandbox places the entire agent loop inside an isolated environment, trading cold-start time for task-level isolation and a more natural file/command operation experience.

Architecture core: credentials, state, and handoff

Credential security: the iron proxy swaps in real keys

The sandbox holds only dummy secrets. When traffic inside the sandbox needs to access GitHub or the LLM API, it passes through a proxy layer called iron-proxy, which replaces the dummy secrets with real keys. This way, even if the sandbox is compromised, an attacker cannot directly obtain real credentials. This "outbound proxy swapping" pattern strikes a balance between security and convenience.

Outbound proxy secret swapping: This is a credential isolation pattern in which applications inside the sandbox hold only placeholder keys with no privileges, and all outbound requests are forcibly routed to a controlled proxy; the proxy replaces the placeholder keys with real keys before forwarding, based on the target domain and preset policies, and performs necessary filtering on responses. Compared with injecting real keys directly into environment variables, its advantage is that real keys never enter the sandbox's file system or process environment, greatly reducing the exposure surface; the cost is the need to ensure that sandbox traffic cannot bypass the proxy (such as via DNS or direct IP connections), which usually requires network policies and egress rules.

State persistence: disposable sandbox with persistent disk

The sandbox itself is disposable, but the disk is not. LangGraph checkpoints are stored on persistent volumes partitioned by task. If the Pod terminates unexpectedly, a newly launched sandbox mounts the same volume and resumes execution from the last checkpoint. This design decouples the lifecycle of the compute instance from state storage, ensuring both isolation and preventing tasks from losing progress due to instance failures.

Handoff mechanism: passing Pydantic-validated results

Agents do not pass files directly to one another. Instead, the test harness launches a worker for each repository. Each worker returns a Pydantic-validated result object, which the harness validates and passes on to the next stage. This structured-data-based handoff reduces implicit coupling and makes it easier for the harness to validate and record intermediate results.

LangGraph checkpoints: LangGraph is a framework for building stateful, multi-step agent workflows, and its checkpoint mechanism takes a snapshot of the graph state after each node executes and persists it. In DevBox, checkpoints are not stored in memory or a temporary directory but written to persistent volumes partitioned by task, so after a Pod is rebuilt, it only needs to load state from the latest checkpoint to continue execution rather than rerunning from scratch. Understanding this helps judge the granularity of recovery: checkpoints are usually measured in "steps," and recovery may replay the most recent incomplete step, so node logic must remain idempotent to avoid duplicate side effects (such as repeatedly creating branches or repeatedly posting comments).

Key trade-offs: cold starts and fresh code

A notable cost of the full-agent sandbox pattern is that every task requires a cold start. Each task gets a brand-new Pod and a volume restored from periodic repository snapshots. Before planning, the agent pulls the latest code from all repositories to ensure it does not work from outdated code.

Restoring the volume is slow, so the original author raised the sandbox creation timeout from 30 seconds to 5 minutes. This is a noteworthy engineering trade-off: startup speed is sacrificed for state consistency and isolation. For tasks that require rapid iteration, this delay can become a bottleneck; but for automated PR generation scenarios that demand reliable output, ensuring code freshness may be more important than startup speed.

Doubts about the "sandbox-as-tool + multiple sub-agents" pattern

At the end of the post, the original author raised an open question: has anyone tried the "sandbox-as-tool" pattern with more than 3 sub-agents? Is this pattern still reliable under shared state? This suggests that the two patterns may perform differently at different scales. The full-agent sandbox pattern simplifies state management through task-level isolation, while the sandbox-as-tool pattern may face more complex state synchronization challenges when multiple sub-agents collaborate.

DevBox's code is open-sourced on GitHub under the MIT license, so interested developers can directly inspect the implementation details. For teams designing agent architectures, this case provides a practical reference on isolation granularity, state persistence, and credential security.

Practical takeaways

Several reusable lessons can be drawn from DevBox's design: credentials are swapped through an outbound proxy rather than injected directly, reducing leak risk; disposable compute instances paired with persistent volumes balance isolation and fault tolerance; structured result objects are used for handoffs between agents, improving verifiability; and accepting the cold-start cost in exchange for code freshness is a deliberate trade-off. These decisions are not the only correct answers, but they provide a discussable starting point for similar scenarios.