Cloud agents quickstart

Choose how you want to work: run a coding session through the Railway CLI, or connect an app on your computer. Railway prepares the cloud agent so you can choose a project on that machine and start a task.

Prepare your computer

Enable Cloud Agents in Priority Boarding, and install the Railway CLI. This installer also offers Railway tooling for your coding agents:

curl -fsSL agents.railway.com | sh

If you already have Railway installed, update it for the latest client integrations:

railway upgrade

Sign in and choose your defaults:

railway login
railway ca setup

Setup saves your default project, coding agent, skills preferences, and theme. A directory's linked project takes precedence over the default project. Use --project and --environment when you want to select the target explicitly.

Available local provider credentials can be carried to the agent; if there is no local sign-in to copy, sign in on the cloud agent when prompted. Railway Agent uses the Railway credentials already on the VM.

For a Desktop connection, install and open the app at least once before configuring it. For an OpenCode local terminal connection, Railway offers to install a missing client after you choose to connect.

Choose your connection

First choose Run agents in Railway or Connect your local app, then select the coding agent or app. Both workflows execute coding tools and work with files on the cloud agent. Run the generated command on your computer:

railway code --claude

For terminal controls and reconnecting, see terminal sessions. For local app setup, use Claude Desktop, Codex Desktop, OpenCode, or OpenCode2 Beta.

Give it a project

A new agent starts with a development environment and /app as its workspace. Your local source files are not automatically uploaded.

Open a shell on the agent, using the name printed by setup:

railway ca ssh <agent-name> -- bash

Clone your repository into its workspace. Replace OWNER/REPOSITORY with your repository:

cd /app
gh repo clone OWNER/REPOSITORY

Open /app/REPOSITORY in the connected desktop app, or change to it in your terminal session. You can also ask the coding agent to clone the repository for you.

For OpenCode2, the server uses the directory selected at startup. You can begin at /app and ask it to work in the cloned repository; see Beta project directories before changing the server's directory.

Start a task

Give the agent a bounded first task, for example:

Read this repository, explain how to run it, and run its existing tests.
Summarize any failures before changing code.

You are working on the Railway machine's filesystem. To confirm the connection, ask the agent to run hostname and pwd in its terminal and report the output. Check the selected remote environment or project in your desktop app as well.

Return to your work

Closing a client keeps the cloud agent running. Reopen the remote project in your desktop app, use railway ca to reconnect to a running terminal session, or reconnect an OpenCode terminal client:

railway code --opencode connect <agent-name>

Stop compute when you're finished

railway ca sleep <agent-name>

Sleep retains files and stops running processes, including terminal sessions. For a Railway CA session, wake the agent with railway ca wake <agent-name>, then start a new session through railway ca. For Claude or Codex Desktop, wake the agent before reconnecting. For an OpenCode local app, rerun its Desktop setup or named connect command to wake the agent and restart its server.

Manage agents and sessions →