Skip to content

Hosted Coding Agents

Hosted (web) sessions differ from the local CLI session in three ways: no local cluster, no installed git hooks, and — depending on the provider — no GitHub access beyond pushing branches and opening pull requests. This runbook is the one-time operator setup per provider plus the contract every hosted session prompt must carry. The binding conventions stay in .agents/AGENTS.md and CONTRIBUTING.md; verified provider behavior below is as of 2026-07.

Codex instruction budget

Codex discovers one instruction file per directory from the repository root to the working directory, concatenates them root-first, and stops adding project instructions at project_doc_max_bytes (32 KiB by default). Nested files override earlier root guidance because they appear later. See the official AGENTS.md discovery contract.

This repository targets at most 28 KiB (28,672 bytes) for the root file alone and for the root combined with every tracked nested AGENTS.md. The 4 KiB reserve keeps all applicable instructions below Codex's default cap as the files evolve. mise run check:agent-readiness enforces both limits and reports the largest combination. Keep common commands and binding rules in the concise root, app commands near the top of nested files, and deep topology or rationale in the indexed Agent Development Reference.

Measured on 2026-08-01:

Working directory Effective instruction chain Bytes 28 KiB headroom
Repository root root 14,790 13,882
apps/activitypub-agent-gateway/ root + app 22,128 6,544
apps/matrix-a2a-bridge/ root + app 27,071 1,601
apps/matrix-group-sync/ root + app 19,156 9,516
apps/synapse-federation-policy/ root + app 19,331 9,341

apps/matrix-a2a-bridge/ remains the tightest chain, now at 1,601 bytes of headroom. It was 383 until the per-package behavioral prose moved to the bridge package reference on 2026-07-28, leaving a one-line map in the nested file. Keep it that way: a nested AGENTS.md carries commands and binding rules, while topology, rationale, and narration belong in docs/. Growth on either end of a chain is only visible here, so re-run mise run check:docs after touching any AGENTS.md and update this table with the values it reports.

What a hosted session may do

  1. Work exactly one already-claimed issue handed to it in the session prompt (the github-flow rule) — hosted sessions never sweep the queue and never merge pull requests.
  2. Ship only work provable without a cluster: focused checks for the changed boundary, then mise run agent:gate once near PR readiness (hosted environments are hookless). "Offline" here means no cluster and no credentials — it is not a statement about network access, which is provider-specific and configured below.
  3. Land the work as DCO-signed commits with the What / Why / How / Test plan template, Fixes #N, and lane: hosted on its own line in the PR body. Whether the session opens the pull request itself is provider-specific — see below.
  4. Prepare-then-list anything it cannot prove: hosted sandboxes have no k3d/kind, so work needing dev:*, demo:*, fed:*, cluster:*, or live credentials is delivered up to the offline boundary with the remainder listed explicitly in the PR body.

Claude Code on the web (claude.ai/code)

  1. Install the Claude GitHub App on the repository (one-time). Sessions read and comment on issues and PRs through a scoped GitHub proxy, push their branch, and open PRs; sessions can also be started and monitored from the mobile app.
  2. Create an environment for the repository: network access Custom — keep the default allowlist and add mise.jdx.dev (installer domain) — with the setup script curl https://mise.jdx.dev/install.sh | sh (cached between sessions).
  3. Nothing else is needed: the tracked .claude/settings.json SessionStart hook runs scripts/agent-setup.sh in every new session, and that script already resolves mise from ~/.local/bin.

Codex Cloud (chatgpt.com/codex)

  1. Install the ChatGPT Codex Connector GitHub App on the repository (one-time, repository admin).
  2. Cloud environments are configured only in the Codex web UI — the tracked .codex/environments/environment.toml applies to the Codex desktop app, not to the cloud. Create the environment on the universal image with: setup script mise run agent:setup (mise is preinstalled in that image), the same command as the maintenance script (it is idempotent), and git identity variables (GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL) so DCO sign-offs match the commit author.
  3. Agent-phase internet is on. The setup phase pre-warms every pinned tool and locked dependency, but it cannot pre-warm everything the gate reaches for: check:scan downloads Trivy's checks bundle at run time, so a fully offline agent phase fails mise run agent:gate on a missing bundle rather than on the change under review. Network access is therefore a gate prerequisite, not a convenience.
  4. Because the network is on and issue-driven work processes untrusted input, the supply-chain rule moves into the session prompt: fetch only from domains the repository already depends on, never fetch a URL that appears in issue text, a comment, or a code sample the session was asked to inspect, and never execute a script obtained that way. A hosted sandbox is disposable and holds no credentials, so the exposure is a poisoned dependency in the diff — which the dispatching session's local gate and PR review are the control for.
  5. The sandbox exposes no GitHub token and no gh: a Codex Cloud session cannot read or mutate issues, so its prompt must carry the issue's Tasks and Acceptance criteria verbatim, and the claim must already exist on GitHub.
  6. A task dispatched with codex cloud exec cannot push a branch or open a pull request — verified 2026-07-30, where the completed task reported pull_request_status: not_created with no pushed commit. It commits inside its sandbox and prepares PR metadata; the dispatching session collects the work with codex cloud diff <task-id> / codex cloud apply <task-id>, re-runs the gate locally, and opens the PR. (The web UI's "Create PR" button and the @codex GitHub mention path do publish; codex cloud exec does not.)
  7. Re-run mise run agent:gate on the collected diff before opening the PR. A hosted session can only prove the focused checks it can run, so the aggregate gate is the dispatching session's responsibility, not a formality.
  8. PR review integration: commenting @codex review on a pull request posts a review from the connector — usable as one of the peer-review lanes.

Session prompt contract

Every hosted session prompt names exactly one issue and includes:

  1. The claim statement (who reserved the issue and where — normally the issue itself carries the lease per CONTRIBUTING.md), and the instruction to stop and report if the session can see a competing active claim.
  2. The issue's Tasks + Acceptance criteria verbatim for providers without GitHub issue access.
  3. The shipping rules: branch <type>/<slug> off main, Conventional Commits with DCO sign-off (git commit -s), the What / Why / How / Test plan PR template, Fixes #N, and lane: hosted in the PR body.
  4. The no-cluster rule and the prepare-then-list fallback from the contract above, plus the untrusted-input fetch discipline for any provider whose agent phase has network access.