n8n/.devcontainer/codespaces

Cloud agent sessions (Codespaces)

Run long-lived, human-steered agent sessions (Claude Code / OpenCode) on a GitHub Codespace instead of your laptop: start a task, close the lid, steer it from anywhere with a terminal, resume tomorrow.

This is a separate devcontainer config from the laptop one in .devcontainer/ — it ships both agent CLIs, tmux for session persistence, Playwright system deps, and Docker-in-Docker (for testcontainers and pnpm --filter n8n-containers services), on the same Postgres sidecar setup.

One-time setup (~5 min)

1. Add your key at github.com/settings/codespaces → New secret → name ANTHROPIC_API_KEY, repository access n8n-io/n8n. (Alternative for Max subscriptions: CLAUDE_CODE_OAUTH_TOKEN from claude setup-token.)

2. Give the GitHub CLI the codespace scope:

   gh auth refresh -h github.com -s codespace
   

Daily flow

pnpm session              # attach the default agent session (creates everything on first run)
pnpm session fix-flaky    # a second, parallel agent in its own git worktree
pnpm session ls           # what's running
pnpm session tunnel       # forward n8n ports (default 5678, 8080) to localhost; Ctrl-C to stop
pnpm session stop         # end of day: billing stops, disk survives
pnpm session rm           # delete the codespace

• Detach with Ctrl-b d — the agent keeps working without you.
• Scroll with the mouse wheel (tmux mouse mode is on). To use the terminal's own text selection, hold Shift and drag.
• Reattach by running the same pnpm session <name> from any machine.
• Each named session gets its own worktree (/workspaces/wt-<name>, branch session/<name>), so parallel agents never touch each other's tree. Builds in fresh worktrees are cache-hits via a shared turbo cache.
• First codespace creation takes ~20 min uncached (image + full build). After that, sessions attach instantly; new worktrees cost a pnpm install (~1–2 min).

Agent broker (call the codespace over HTTP)

agent-broker.mjs runs one Claude turn per HTTP request, so an external caller (an n8n workflow, a script) can drive a session on the codespace. Each turn is a headless claude -p. State persists on disk, so --resume continues a conversation across turns and across a stop/start.

The broker starts on every container start (postStartCommand). It needs the AGENT_BROKER_TOKEN secret and refuses to start without it. Add the token at github.com/settings/codespaces the same way as ANTHROPIC_API_KEY. Logs are at /tmp/agent-broker.log; the tmux session is broker.

The port is private by default. Make it reachable, then health-check it:

gh codespace ports visibility 8787:public -c <codespace-name>
curl https://<codespace-name>-8787.app.github.dev/healthz     # {"ok":true}

A public port has no auth in front of it, so the bearer token is the only guard. Keep it secret.

Send a turn (omit sessionId to start one; pass it back to continue):

curl -s https://<codespace-name>-8787.app.github.dev/turns \
  -H "Authorization: Bearer $AGENT_BROKER_TOKEN" -H 'content-type: application/json' \
  -d '{"message":"what branch is this?"}'
# reply carries .result.session_id — send it back as "sessionId" next turn

Turns take minutes. Pass a callbackUrl to get 202 {turnId} at once and the result by POST when the turn ends. See the file header for the full contract.

Flaky tools (MCP)

Claude sessions get the flaky MCP server automatically: Currents flaky/quarantine data, the qa_* BigQuery dataset, Sentry RCA, live Linear, and repo investigation. Login registers it from the repo-level FLAKY_MCP_TOKEN / FLAKY_MCP_URL secrets. Forks have no secrets and skip it. Tell the agent to call get_flaky_context first — it returns the rules the tools assume.

Viewing the dev UI locally

Two terminal windows:

pnpm session          # window 1: attach the agent session
pnpm session tunnel   # window 2: forward 5678 + 8080 to localhost

Attaching lands you in the agent (Claude), not a shell — open a shell in a new tmux window with Ctrl-b c (or ask the agent) and run pnpm dev there. Then open http://localhost:8080.

The tunnel prints nothing while forwarding — that's normal. Connection refused means nothing is listening on that port in the codespace yet; it starts serving as soon as pnpm dev is up, no restart needed. Pass ports to override the defaults (pnpm session tunnel 5678 8080 5679), but always forward the pair together with matching numbers: the Vite dev UI points its API base at localhost:5678 (the N8N_PORT default), so an asymmetric or partial mapping breaks it.

What survives what

Event	Running processes	Disk (checkout, worktrees, chat history)
Detach / close laptop / network drop	✅ keep running	✅
Stop, or idle timeout (default 30 min, max 4 h)	❌ killed	✅
Delete (pnpm session rm)	❌	❌ (push your branches first)

After a stop, pnpm session <name> restarts the codespace (~30–60 s); run claude --resume (or --continue) inside to restore the conversation from disk.

Gotchas (learned the hard way)

• Codespaces clones the repo to /workspaces/n8n, not /workspaces — workspaceFolder here differs from the laptop config on purpose.
• A failing onCreateCommand is fatal: Codespaces discards the container and drops you into a minimal recovery container (no node, no CLIs). If your codespace has nothing installed, check /workspaces/.codespaces/.persistedshare/creation.log.
• gh codespace ssh needs sshd inside the container — provided by the sshd devcontainer feature, don't remove it.
• User secrets aren't visible in ssh shells by default: the codespace agent injects them into VS Code sessions only; they're delivered base64-encoded to /workspaces/.codespaces/shared/.env-secrets. The image sources /usr/local/lib/codespaces-env.sh in login shells (profile.d), in interactive shells (bashrc), and in the pnpm session prelude. If Claude Code shows Missing environment variables: FLAKY_MCP_TOKEN, the shell that started Claude did not source the file. Run . /usr/local/lib/codespaces-env.sh and start Claude again.
• You cannot paste images into a remote Claude session. Image paste reads the clipboard of the machine where claude runs — the codespace, not your laptop. Drag the file into the VS Code explorer (or gh codespace cp shot.png remote:/workspaces/n8n/) and give Claude the path. The file stays on disk and survives detach and --resume.
• git push / gh return 401 in tmux and long sessions — same root cause as the secrets gotcha, plus rotation: Codespaces refreshes the on-disk GITHUB_TOKEN every few minutes, so a login-time snapshot goes stale. The image fixes both: a credential helper reads the current token on each git push (gitcredential-refresh.sh), and a shim at /usr/local/bin/gh does the same for gh. The token is scoped to n8n-io/n8n: fork-based flows do not work, push branches directly. Do not add SSH keys as a workaround — they have no per-repo granularity.
• Codespaces created by org members on this repo are org-owned and org-billed (organization ownership + a monthly Codespaces budget are enabled for n8n-io). Codespaces created before that change, or by non-members, bill to the personal account (free tier: 120 core-hours/month). If creation unexpectedly falls back to personal billing, the org budget is exhausted for the period.

Costs

Compute bills only while the codespace runs: ~$0.36/hr (4-core) / ~$0.72/hr (8-core), ~nothing stopped. Usage draws from a shared monthly org budget, so pnpm session stop when you leave; the idle timeout is the backstop, not the plan.