Skip to content

[docs] Reconcile runtime docs with relay-only pags up #208

Closed
Closed
[docs] Reconcile runtime docs with relay-only pags up#208
Labels
documentationImprovements or additions to documentation

Description

@serge-ivo
serge-ivo
opened on Aug 5, 2026

Problem

Runtime documentation disagrees with the current CLI/runtime implementation.

The implemented path is relay-only from the user perspective: pags up starts one multiplexed runner and runner connect connects via WebSocket relay. The CLI exposes pags up --headless, --instance, and --force; there is no pags up --tunnel option in the code.

Evidence

  • Current CLI options: platform/packages/cli/src/commands/up.ts
  • Relay connect implementation: platform/packages/cli/src/commands/runner/command.ts
  • Current public docs say relay-only: platform/platform-docs/browser-runtime.md
  • Stale/conflicting docs:
    • platform/README.md says cloudflared tunnels remain as --tunnel quick|named
    • platform/packages/browser-runner/README.md says Cloudflare quick tunnel is the shipped bootstrap path and mentions FAGS/outbound polling
    • platform/store/llms.txt and platform/store/llms-full.txt mention Cloudflare Tunnel as a legacy/optional path
    • platform/docs/coder-cloud-vs-local-placement.md still says local placement uses a tunnel

Scope

Update all runtime-related docs to one current story:

  • pags up is the canonical user command.
  • It starts one local runtime for all active runtime-backed instances on the machine.
  • It connects outbound through RelayDO/WebSocket.
  • No inbound tunnel/cloudflared setup is part of the current user path.
  • Document --force, --instance, and --headless only if they still exist.

Acceptance Criteria

  • No docs mention pags up --tunnel, Cloudflare quick tunnels, or FAGS runtime as current behavior.
  • platform/README.md, platform/packages/browser-runner/README.md, platform/platform-docs/browser-runtime.md, platform/store/llms.txt, and platform/store/llms-full.txt agree.
  • pnpm docs:build is run if platform-docs sources change.

Activity

  1. serge-ivo
    added
    documentationImprovements or additions to documentation
    on Aug 5, 2026
  2. serge-ivo
    added 3 commits that reference this issue on Aug 5, 2026

    fix(coding): one driver per engine — a session can only be driven once (

    c08a8c2

    fix(coding): the single-flight claim covered 1 of 3 paths that start …

    b85699c

    fix(coding): a dead workflow permanently locked the session — claims …

    9e68937

  3. serge-ivo commented on Aug 6, 2026

    @serge-ivo
    serge-ivo
    on Aug 6, 2026
    ContributorAuthor

    Closing as implemented on main. Runtime docs now agree on relay-only pags up: README, packages/browser-runner/README.md, platform-docs/browser-runtime.md, store/llms.txt, and store/llms-full.txt all say outbound WebSocket relay, no cloudflared/current tunnel path, and no --tunnel flag.

  4. serge-ivo
    closed this as completedon Aug 6, 2026

  5. serge-ivo commented on Aug 6, 2026

    @serge-ivo
    serge-ivo
    on Aug 6, 2026
    ContributorAuthor

    Implementation links: no associated PR was found for the docs cleanup; the relay-only docs are present on main, with related docs commits 444d4f9, 58e2ab4, and 3d99390.

  6. serge-ivo
    added 2 commits that reference this issue on Aug 6, 2026

    docs(runtime): `pags up` membership is live, not a startup snapshot (#…

    291fbd7

    docs(catalog): say where the catalog lives, and stop listing agents t…

    26e53c0

  7. serge-ivo commented on Aug 6, 2026

    @serge-ivo
    serge-ivo
    on Aug 6, 2026
    ContributorAuthor

    Re-verified rather than assumed, since commit messages in this repo have been citing wrong issue numbers. The relay-only claim held up: no doc mentions cloudflared, a --tunnel flag, or FAGS as current behaviour, and docs/coder-cloud-vs-local-placement.md is clean too.

    One claim was stale though, and it was the operationally misleading kind, so 291fbd7 fixes it. Every runtime doc said pags up serves "the active runtime-capable agents it discovered when it started".

    It no longer does. up.ts passes --watch-instances for any unscoped run, and relay.ts polls /v1/instances/my/instances every 20s to attach newly eligible instances and detach ones that stopped being eligible (CLI ≥ 0.4.30, #229). So the workaround the old wording implied — subscribe to a coding agent, then restart your runner — is now busywork. A scoped pags up --instance <id> deliberately does not watch.

    Two things stated that were not before:

    • Eligibility has a rule: capabilities.runtime non-null. Cloud-only chat/RAG/connector agents are skipped and never need a runner at all. The docs described the behaviour without ever giving the predicate.
    • /v1/relay/:instanceId/connect accepts only the short-lived relay token, never the 30-day account JWT. That is why a leaked relay URL is not account takeover, and it belongs in the doc rather than only in a code comment.

    Also documented --force's real scope (same-hostname takeover; different machines coexist and routing follows the live socket) and pointed packages/browser-runner/README.md at pags up rather than the low-level runner connect.

    Files touched: README.md, platform-docs/browser-runtime.md, platform-docs/index.md, packages/browser-runner/README.md, store/llms.txt, store/llms-full.txt. Leaving this closed.

  8. serge-ivo
    added 2 commits that reference this issue on Aug 7, 2026

    fix(coder): the Coding tab's Loop stops being the loop, and starts on…

    db8a2af

    fix(budget): every autonomous coding entry point opens a pool, and MC…

    f79fb29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions