Managed Connection roadmap and agent handoff
Proposed — not implemented. This roadmap plans future work on the optional managed connection. To connect today, see Access from your phone.
Status: planning, 2026-10-20. No service exists yet. Milestones are acceptance gates, not calendar promises. See design for trust boundaries and contracts. Epic: #22. Issue links below are the implementation queue; existing #19 and #20 are reused.
#Delivery order
| Milestone | Exit evidence | Work |
|---|---|---|
| M0: contract and feasibility | Approved auth/provisioning ADR, mocked schemas, staging Cloudflare/API/identity proof and measured revocation bound | MC-0 |
| M1: one connected host | An enrolled Linux host has a stable authenticated hostname; origin rejects wrong identities; restart is repeatable | MC-1 + MC-2 + MC-3 |
| M2: usable from a phone | Account sign-in, pair/open host, project selection, approval, interactive answer, follow-up and stop/resume succeed | MC-4 + MC-6 |
| M3: failure-safe private pilot | Expired/revoked sessions and retry/outage tests pass; no lost/duplicate actions; real EC2/mobile evidence, cleanup and operator runbooks | MC-5 + MC-7 |
| M4: expansion after evidence | Native-host Codex session parity; room UI uses the same connection contract | Existing #19, then #20; not prerequisites for Claude pilot |
Do not enable an externally usable tunnel before origin authentication and the edge gate are in place. Billing/paid entitlement activation waits for M3; a manually entitled invitation pilot avoids building payment plumbing prematurely.
#Work packages and ownership boundaries
| Package | Scope / suggested files | Depends on | Parallel lane |
|---|---|---|---|
| MC-0 | Identity/security ADR, schemas/fixtures, vendor feasibility; docs/managed-connection, proposed src/managed/protocol.ts | None | Integration owner first |
| MC-1 | Account/host registry, pairing state machine, idempotent Cloudflare provisioning and cleanup; proposed services/connection/ | MC-0 | Managed-service backend |
| MC-2 | Origin auth adapter, managed listener, session/CSRF/revocation; proposed src/server/managed-* | MC-0; MC-1 mocks | Host API/security |
| MC-3 | Connect/status/disconnect CLI, connector and reboot/reconnect lifecycle; proposed src/cli/connect.ts, src/managed/ | MC-0; MC-1/2 mocks | Host onboarding |
| MC-4 | Hosted console, host-aware links/status, device revoke and PWA access; proposed console plus bounded web/, src/server/public/ changes | MC-0; MC-1/2/3 mocks | Browser UX |
| MC-5 | Browser mutation dedupe, cursor/re-auth recovery and chaos tests; src/server/app.ts, store.ts, browser clients | MC-0; integration after MC-1–4 | Reliability |
| MC-6 | Agent interaction gap: answer AskUserQuestion or clearly block unsupported requests; repo/agent context in UI; no model rerouting | Independent spike; coordinate protocol with #12/#19 | Agent UX |
| MC-7 | End-to-end staging, threat/abuse tests, resource/retention/revoke runbooks, launch checklist | MC-1–6 | Integration/release |
Suggested paths are interfaces to negotiate in MC-0, not instructions to create a service implementation before its contract is agreed. The hosted code may move to a separate repository; keep public protocol/client code independently usable.
The user will allocate tasks between Claude on EC2, Codex and CCR sessions. No assignment in this document delegates work or authorizes agents to message one another automatically. Each implementation issue should have one human-selected integration owner and one active branch. Start with MC-0 and MC-6 in parallel; after MC-0, MC-1/2/3/4 can use shared mocks rather than wait for deployed services.
#Existing issue relationships
- #1: amend “software, not a service” to allow an optional managed-connection offering while preserving a fully independent self-hosted core.
- #6: reuse per-device identity/revocation concepts. Managed cloud pairing and self-hosted QR/passkeys are different deployment flows; do not force an account or Cloudflare onto self-hosters.
- #12 and #19: preserve agent-neutral contracts; Codex needs its own adapter and native host authentication, not an unconditional CCR gateway requirement.
- #20: implement local Rooms separately. Managed access transports room APIs; do not build cloud room storage, Matrix infrastructure or federation here.
- #8: usage meters from a gateway do not describe official Claude/Codex accounts. Connection health/billing must work without inference usage telemetry.
- #13: hosted compute is excluded from this roadmap.
- #16: chat integrations remain optional; they do not establish browser identity.
#First EC2 demonstration
- Use a staging account/domain and a disposable or explicitly approved dev host.
- Confirm existing Claude/Codex/Git configuration and record hashes of config files without recording secret values. Do not copy model credentials to CI.
- Pair through the new CLI and open the permanent HTTPS URL on a physical phone over cellular, with no SSH forwarding, VPN or Cloudflare account on the phone.
- Check that Claude is installed; explicitly run a scratch model-access task. Select a repo under
~/src; task uses its own worktree. UI names host/repo/agent. - Trigger approval and an interactive question, answer from the phone, then send a follow-up. Close/reopen the app and confirm the same session/history.
- Restart connector/service and reboot the staging host using the supported installation mode. Record what survives; do not infer runner reboot recovery from tmux behavior. No repeated task, message or approval is allowed.
- Drop the browser response after an accepted mutation. Retry with the same action ID. Show the original result and exactly one side effect.
- Revoke the phone and then host. Measure existing-stream closure and rejection of fresh requests. Old links, cookies, codes and tunnel tokens must not restore authority. Local break-glass access and agent work remain available.
- Disconnect/uninstall; confirm no orphan DNS/tunnel/policy remains and all pre-existing agent/Git configurations are unchanged.
- Repeat session parity for Codex only after #19 is implemented and tested.
#Cross-agent implementation contract
- Read AGENTS.md, RFC #1, this design and the selected issue. Use current
main, an isolated worktree per task, and branchcodex/<topic>unless explicitly allocated another branch convention. Never share one checkout concurrently. - Claim an issue/branch with the user before editing overlapping surfaces. MC-2 and MC-5 both touch API auth/store; MC-4 and MC-6 both touch PWA files. Their integration owner decides merge order. Avoid unrelated cleanup.
- Freeze shared types and fixture examples in MC-0. Changes require a short ADR and coordinated updates to tests, rather than silent interface drift.
- Handoff contains base/head SHA, issue/PR URL, changed contracts, tests actually run, manual steps still needed, and unresolved risks. Do not report mocked Cloudflare/model tests as live integration evidence.
- No production DNS/account changes, model spending, installing new dependencies, secret uploads, deploys or merges merely because an implementation task exists; follow the user's actual authorization and repo rules for those actions.
- AskUserQuestion must not silently disappear in CCR sessions used for this work. Until MC-6 lands, use explicit text questions and wait for a human answer; never invent approval or proceed on an ambiguous repository choice.
- Human assigns branches and approves release. Documentation/task creation does not start the implementation work or contact the EC2 agent.
#Definition of done for pilot
- Required artifacts: security ADR, signed/validated auth contract, migration and rollback notes, deterministic fixtures, tests, user guide, operator runbooks and dated staging evidence. All seven implementation packages pass their gates.
- Desktop/phone login and normal task control work without a gateway subscription. Self-hosting stays account-free; existing owner-token tools keep working locally.
- Wrong-tenant, wrong-host, replay, expired grant, CSRF, hostile hostname/upstream, spoofed header, exposed runner port and stale approval tests fail safely.
- Every reachable tenant page is edge-gated; no alternate hostname/path bypass. Support/analytics/logs contain no transcript or credential data by default.
- Revocation bounds, API-rate/byte/concurrency limits and cleanup are measured. Vendor plan suitability and estimated per-active-host costs are documented; actual pricing, payment integration and optional gateway bundles are later decisions.