Document cloud agents - #1285
Merged
Merged
Conversation
Adds documentation for cloud agents: persistent VMs that run Claude Code, Codex, or Grok CLI with the reader's own credentials. New pages: - `/cloud-agents` — what a cloud agent is, how targets resolve, reuse and lifecycle, credential delivery per agent, skills sync, variables, and the preferences file - `/cloud-agents/getting-started` — setup with `railway ca setup`, the first launch, and managing agents and sessions from there - `/cli/ca` — the terminal interface, its subcommands, options, keys, and mouse behavior - `/cli/code` — the launcher, its options, target resolution, and credentials Every page carries the beta banner used for Priority Boarding features, since the commands and flags may still change. Also links cloud agents from the AI landing page and the Railway for Agents card grid, and adds the sidebar entries. Verified against the CLI source: command and subcommand names, every flag, `RAILWAY_CA_AGENT`, the preferences path and fields, the skills source directories and size limits, and the key bindings.
|
🚅 Deployed to the docs-pr-1285 environment in 🪄 *.railway.com
7 services not affected by this PR
|
Pressure tested every technical claim against the shipping implementation. Six were wrong: - The setup flow's options came from the interface's wizard, not from `railway ca setup`. The real prompts are "Create a default project", "Use an existing project", and "Skip"; skills is a yes/no question followed by a directory pick when several hold skills, and it's skipped when there's nothing of yours to send; the theme picker has no live preview. - Setup doesn't always ask four questions, since the skills step can be skipped. - `--project` takes an ID, not a name. The example passed a name. - Codex and Grok need a completed local sign-in, but Claude Code mints in a browser, so the prerequisite was overstated for it. - The claim that a coding agent "may prompt" before touching files outside `/app` isn't verifiable from the CLI. Removed. - Skills link into the three harness directories by name, not into "every coding agent's skills directory". Also adds what verification turned up as worth stating: the token cache path, that minting runs the local `claude` binary, that `-y` picks the first detected agent with skills off, that Railway skips the interface when stdout isn't a terminal, that clicks reach the agent only once the pane has the keyboard, and that turning skills sync off leaves what's already on an agent.
Four places a reader would stumble: - "machine specification" is internal vocabulary. The credential sections now say what a reader can check instead: the credential never becomes a Railway variable, part of an image, or a command line argument. - The image name `cloud-agent-base` said nothing a reader can act on, and "the VM configures them" left the actor vague. - Step 4 of target resolution called `railway ca setup` "the setup flow", which reads as a concept rather than the command it is. - `railway code`'s description promised a local sign-in, which isn't how Claude Code works.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Docs for cloud agents: persistent VMs running Claude Code, Codex, or Grok CLI with the reader's own credentials.
Depends on railwayapp/cli#1013 for the commands.
New pages
/cloud-agents/cloud-agents/getting-startedrailway ca setupwalkthrough, first launch, managing agents and sessions/cli/ca/cli/codeEdited
ai.md— cloud agents entry in the integration listagents.md— card in the integration grid, entry in "When to use each"sidebar.ts— cloud agents under AI with its child page,caandcodein the CLI listBeta treatment
Matches the Priority Boarding precedent in
sandboxes.md,feature-flags.md, andcli/sandbox.md:<Banner variant="primary">with "Breaking changes may occur"<Banner variant="info">noting commands and flags may change in breaking ways<Banner variant="warning">because--keep-awakebills compute with nothing attachedCorrections from pressure testing
Second commit fixes six claims that didn't match the code:
railway ca setupuses "Create a default project", a yes/no skills question plus a directory pick, and a plain theme select--project my-project--projecttakes an ID;--environmenttakes a name or ID/app~/.claude/skills,~/.codex/skills,~/.grok/skillsVerified and added: token cache path, minting runs the local
claudebinary,-ybehavior, interface skipped when stdout isn't a terminal, clicks reach the agent only once the pane has the keyboard, sleep-on-quit covers open sessions, skills sync off leaves what's on the agent.Verification
Claim-by-claim against
railwayapp/clion the shipping branch: command and subcommand names, every flag and its help text, prompt strings,RAILWAY_CA_AGENT, preferences path and fields, skills sources and the 2 MB / 10 MB limits, key bindings, no aliases onrailway ca.--idle-timeoutdoesn't exist on these commands and isn't documented.Links and anchors checked programmatically. CI
Buildpasses and all four pages render on the preview deploy.