AI Coding Agent Architecture: Runtime Requirements and Deployment Checklist

A production AI coding agent needs more than repository access and a strong model. It needs a bounded workspace, executable validation, browser observation, scoped credentials, consequence-based approvals, a durable action ledger, and a recoverable handoff. If one of those is missing, the runtime can produce plausible code without producing a trustworthy change.

We tested that claim on a deliberately small repair: one JavaScript function charged tax twice, while one mobile panel was 390 pixels wider than its viewport. The local runtime began with a failing unit test and visible horizontal overflow. After two approved file edits, the test passed and overflow fell to zero. An unrelated operator note kept the same SHA-256 hash, a dummy credential marker appeared zero times in the audit ledger, and a deploy command stayed behind its approval gate.

The code change was trivial. The evidence boundary was the product.

Requirements the repair exposed

The initial function returned subtotal + tax + tax. Replacing it with subtotal + tax made the unit assertion pass. The layout fix added border-box sizing and a maximum width. Neither edit says much about an agent's intelligence. Both could be typed in seconds.

What mattered was everything around them. The runtime recorded the requested file boundary before editing. It hashed the unrelated note. It ran the failing test before the patch and the same test afterward. It opened the page at a 390×844 viewport, measured the document width, repeated that check after the CSS change, and classified deploy as an external action that required a human decision.

Validation: the eight-event ledger

The probe wrote a sequence-numbered ledger instead of a prose success claim. Eight events were enough to reconstruct the run: task receipt, workspace snapshot, failing unit test, failing mobile check, bounded edit, passing unit test, passing mobile check, and a held approval. The sequence was complete and contained no dummy secret value.

Green was not green yet.

The unit test passed before the browser result did. That ordering is the reason a production runtime should bind validation to the task, not to a universal command such as npm test. A backend patch may need a contract test. A migration may need a rollback rehearsal. A frontend change needs rendered evidence at the affected viewports. The model cannot infer success from a green command whose scope excludes the defect.

Workspace state is part of the input

A coding agent does not receive a pristine abstract repository. It receives a branch, staged and unstaged changes, ignored files, generated artifacts, submodules, and sometimes another person's unfinished work. A production runtime should capture that state before planning, then refuse to flatten it for convenience.

Git's porcelain status format exists for machine parsing and distinguishes index changes, worktree changes, untracked paths, ignored paths, and conflicts. Use it as one input to a workspace manifest, not as permission to reset anything. Record the starting revision, branch, dirty paths, task-owned paths, and file hashes that must remain stable. At handoff, compare the actual write set with the declared one.

Isolation helps, but it does not eliminate this contract. A fresh container can still check out the wrong revision, mount too much of the host, inherit a broad credential, or push from an unexpected branch. The workspace manifest makes those assumptions visible before the first edit.

Terminal green is not browser green

Command execution is the minimum useful tool for an AI coding agent. It can reproduce failures, run tests, compile code, inspect a diff, and invoke project-specific checks. Terminal access alone still leaves a blind spot whenever correctness depends on rendering, focus order, browser APIs, cookies, network behavior, or responsive layout.

In the fixture, the calculation test knew nothing about CSS. The page could have shipped with a perfect total and a broken mobile layout. A headless Chromium check at the named viewport found the 390-pixel overflow, and the rerun proved it disappeared. Playwright's configuration supports explicit projects, local web servers, retries, traces, and artifact directories; those knobs belong in the repository so the agent and CI execute the same browser contract.

Browser evidence should remain selective. A screenshot is useful for visual review, but assertions should carry the binary contract: no horizontal overflow, expected controls visible, images decoded, console clean, and the changed flow usable with its intended input. A wall of screenshots without assertions only moves the debugging work to the reviewer.

Permission follows consequence, not convenience

Most permission systems become either irritating or dangerous because they classify tools too broadly. “Allow shell” is not a useful production policy. Reading a package manifest, running a unit test, deleting a database, and publishing a release may all pass through a shell, but they do not carry the same consequence.

OpenAI's Codex documentation separates sandbox mode—what the agent can technically touch—from approval policy—when it must stop and ask. Anthropic describes a similar permission architecture, with read-only defaults, workspace boundaries, sandboxed commands, network controls, and explicit approval for additional actions. The implementation details differ; the durable idea is two independent layers.

• Autonomous inside the task: read named repositories, edit task-owned files, run deterministic local checks, and write evidence artifacts.
• Conditionally autonomous: install pinned dependencies, access an allowlisted documentation host, or start an approved local service.
• Always deliberate: deploy, publish, message a third party, alter production data, broaden a secret, remove durable data, or cross a workspace boundary.

The fixture contained an executable deploy stub. The runtime did not run it, even after validation passed. It logged the exact command as held_for_human and left the sentinel absent. That is a small but important distinction: successful implementation authorized evidence collection, not a new external consequence.

A production contract has named evidence

Teams often start with a list of capabilities: browser, terminal, memory, secrets, schedules. A stricter runtime contract names what must be true at the end of a class of work. The following shape is intentionally boring enough to review:

task:
  repository: storefront-ui
  base_revision: 8b41f2a
  owned_paths:
    - src/pricing/calculator.mjs
    - src/pricing/styles.css
  preserve_dirty_paths:
    - operator-notes.txt

validation:
  commands:
    - node test/pricing-total.test.mjs
  browser:
    viewport: 390x844
    assertions:
      - horizontal_overflow_px == 0

permissions:
  network: deny
  secrets:
    - name: test_token
      scope: local-fixture
  external_actions: approval_required

handoff:
  require:
    - diff
    - before_after_results
    - browser_evidence
    - approval_ledger
    - unresolved_risks

This contract can live beside project instructions and CI configuration. It also gives an orchestrator a fail-closed path: if the repository revision changed, a preserved file moved, the browser check cannot start, or the requested deploy has no approval, the run stops with a specific missing condition.

Secrets deserve their own ledger policy. OWASP recommends centralized lifecycle management, fine-grained access, and least privilege. Inject a credential only for the tool and time window that needs it; do not copy its value into prompts, command summaries, screenshots, or chat history. Log the credential identity, scope, version, and access outcome—not the secret itself.

Managed versus local is an ownership decision

A local agent can be the right choice for a single developer who already owns the machine, repository, credentials, and review loop. It keeps latency low and can fit existing tools closely. The hidden work appears when the agent must continue after the laptop closes, serve several people, maintain isolated workspaces, rotate credentials, schedule checks, or preserve an auditable history.

Neither option removes engineering responsibility. NIST's Secure Software Development Framework is outcome-based and explicitly warns against treating secure development as a blind checklist. The runtime should help the team demonstrate outcomes—protected software, reviewable changes, secure environments, and response evidence—without pretending that hosting location alone provides them.

GolemWorkers is one managed-runtime option: a dedicated worker can combine files, terminal execution, browser automation, scoped secrets, persistent project context, scheduling, and messaging. Evaluate it with the same contract as any local stack. Ask which paths are writable, which network destinations are reachable, where credentials enter the process, which actions require approval, what evidence survives, and how a failed run is recovered.

Failure modes this probe cannot test

The local fixture established six narrow facts: the test moved from exit 1 to exit 0; mobile overflow moved from 390 pixels to zero; only the two declared files changed; the unrelated note's hash stayed stable; the deploy sentinel remained absent; and the credential canary never entered the eight-event ledger.

It did not establish that one model plans better than another. It did not attack the sandbox, rotate a real secret, interrupt and resume a long job, exercise multiple users, constrain live network traffic, or measure cost. Those require separate adversarial and operational tests. A serious evaluation should add them in the order suggested by the team's failure cost, not because a vendor checklist has seven convenient boxes.

The practical first trial is a bug with a known failing check and one validation surface the test suite does not cover. Declare the write set, preserve existing work, bind the relevant command and browser checks, inject no broader credential than the fixture needs, and keep publication behind a separate decision. If the handoff cannot show the starting failure, bounded diff, passing evidence, and held consequences, the runtime is still a demo.

Primary material used

• OpenAI Codex: agent approvals and security — sandbox modes, approval policy, network isolation, workspace-write defaults, and dangerous boundary-expanding settings.
• Anthropic Claude Code security — permission defaults, workspace boundaries, command sandboxing, network approval, cloud isolation, credential protection, and audit logging.
• Git status documentation — stable porcelain formats for machine-readable index, worktree, untracked, ignored, and conflict state.
• Playwright test configuration — browser projects, local web servers, retries, traces, timeouts, and artifact directories.
• OWASP Secrets Management Cheat Sheet — centralized lifecycle management, fine-grained access, automation, and least privilege.
• OWASP Logging Cheat Sheet — application audit events, attributable sequences, log purpose, and sensitive-data handling.
• NIST Secure Software Development Framework — outcome-based secure-development practices and risk-based adoption rather than checklist compliance.