---
title: Cloud agents
description: Run coding agents in Railway or connect your local app to a persistent development environment. Launch terminal sessions, connect Desktop, and return to your work.
---
Your coding agents, running on Railway. Give them a persistent development environment with your tools, credentials, and project files. Start sessions through the Railway CLI, or connect an app on your computer.

Railway prepares the environment and carries available coding-agent credentials from your machine. Your files stay on the agent's disk. The machine sleeps after five minutes idle, or when you sleep it, and wakes when you connect again.

## Run agents in Railway

Launch a coding agent directly on the Railway machine and work with it through your terminal. Browse your agents, start sessions, and return to running work in Railway CA.

<CloudAgentTools />

```bash
railway code --claude
```

Use `railway ca` to choose an agent interactively or return to a session. OpenCode uses `railway code --opencode remote` to run both client and server on the machine.

[Start a terminal session →](/cloud-agents/terminal)

## Connect your local app

Keep using an app on your computer, with Railway as its remote environment. Connect through Claude Desktop, Codex Desktop, OpenCode, or Herdr.

<CloudAgentClients />

OpenCode supports both Desktop and local terminal clients.

[Choose your connection →](/cloud-agents/quickstart#choose-your-connection)

## Hand off work with tasks

Give a cloud agent a piece of work and read the result when it finishes, without connecting to it. Dispatch tasks from the CLI, an AI assistant, or the API.

```bash
railway ca task run "Fix the failing test in api/ and open a pull request"
```

The task runs in the background. Add `--watch` to follow it live.

[Run a task →](/cloud-agents/tasks)

## How cloud agents work

Each cloud agent is a personal virtual machine in a Railway project environment. In both workflows, coding tools execute and edit files on that machine. You choose whether to use a session in Railway CA or a connected local app.

<CloudAgentConnection app="Your terminal or desktop app" transport="SSH or HTTPS" />

Railway CA terminal sessions, Herdr, and Claude and Codex Desktop connections use SSH. OpenCode Desktop and local terminal clients connect to an authenticated HTTPS server on the agent.

The disk lasts for the life of the agent. Closing a connection doesn't stop the VM right away. An agent sleeps after five minutes with:

- no SSH client attached
- almost no network traffic sent (under 8 KiB per 15 seconds)
- no coding agent working or waiting on you (Railway Agent doesn't keep it awake while it waits)

A command left running in a detached session doesn't keep the agent awake. A sleeping agent wakes on SSH, HTTP, or API access. Agents created before October 8, 2026 don't sleep on their own. Sleeping stops the agent's processes and compute billing while retaining files. Deleting the agent removes its disk. See [manage agents and sessions](/cloud-agents/manage).

Agents hold your credentials and are owned by you. Normal CLI discovery and connection pickers show your own agents. Administrative listing of other members' agents is separate from connecting to their sessions.

## What's on the machine

Agents use an Ubuntu development image with coding tools, an authenticated Railway CLI and GitHub CLI, and a full development toolchain:

- Claude Code, Codex, Grok CLI, Railway Agent, and OpenCode 2.
- Git and GitHub CLI access using the GitHub credential available to the agent.
- Node.js with pnpm and yarn, Python with uv, and `mise` for additional toolchains.
- Utilities including ripgrep, jq, SQLite, build tools, Caddy, and Chromium.
- Docker, for running services such as PostgreSQL or Redis in containers. `dockerd` starts on first use. `docker compose` isn't installed.
- The Playwright MCP server, configured for each coding agent, and Railway's use-railway skill.

Sessions start in `/app`. Clone a repository there or choose another remote directory in your connection setup. Launching from a local repository selects context and eligible configuration to carry; it does not upload your repository files.

### Additional installed tools

The image also includes pi and Cursor CLI. Run them from a shell and complete their own sign-in flows. These tools are separate from the Railway CLI's integrated launch choices; see [additional installed tools](/cloud-agents/terminal#additional-installed-tools).

## Quick start

Follow the [interactive quickstart](/cloud-agents/quickstart) to install the CLI, choose how you want to work, and get the right launch command. `railway code` creates a fresh VM unless you select an existing agent. Desktop setup and `railway ca` reuse an agent where they can, and wake it if needed. See [reuse and create agents](/cloud-agents/manage#reuse-and-create-agents).

## Keep working across connections

Use a cloud agent for a refactor, a long test run, or a workspace you want to return to from a desktop app. Sessions started in Railway CA survive a terminal disconnect while the agent is awake. OpenCode's managed server continues running after its client disconnects. Desktop apps manage their own chat and reconnection behavior.

A command left running in a detached session doesn't keep the agent awake, so a long test run can stop when the agent sleeps. To keep a long job running, keep an SSH session attached, or have a coding agent run it as part of its turn.

When you're finished, stop compute with the agent name printed during setup:

```bash
railway ca sleep <agent-name>
```

Sleeping ends running processes and terminal sessions. Files and saved conversation history remain on disk. On agents created since October 8, 2026, most servers that were listening on a port, including OpenCode's, start again when the agent wakes. Start other processes again when you return. If OpenCode can't connect after a wake, or the agent was created before that date, rerun `railway ca desktop --opencode`.

## Serve traffic from an agent

Each agent has a public HTTPS domain serving port `8080`, available inside the VM as `RAILWAY_PUBLIC_DOMAIN`. The domain remains the same across sleep and wake. A request to it, including one from a bot or crawler, wakes an agent that went to sleep on its own, and compute billing resumes. An agent you slept, for example with `railway ca sleep`, stays asleep until you wake it or connect over SSH.

Agents created for an OpenCode or Codex client also get a separate `code-` domain, serving port `4096` by default. OpenCode and Codex servers use that domain, which leaves port `8080` for your app. Agents without a code domain, including those created before code domains existed, serve OpenCode and Codex on port `8080`. Setup refuses to replace an unrelated process on the server's port.

Deploy a [Railway service](/services) for production traffic.

## Pricing

An agent bills for compute while it is awake, until you sleep it or it sleeps after five idle minutes. Sleeping stops compute billing and keeps the disk. Coding-provider usage follows your provider's account or API billing separately.

See [VM pricing](/pricing/plans#vm-pricing) for current rates, and [manage agents](/cloud-agents/manage#sleep-wake-and-delete) for lifecycle commands.

## Specs and limits

An agent's size is set from your workspace plan when the agent is created:

| Plan | vCPU | Memory |
|------|------|--------|
| Trial | 2 | 2 GB |
| Free | 2 | 2 GB |
| Hobby | 8 | 8 GB |
| Pro | 24 | 24 GB |

Pro workspaces on older plan limits get 32 vCPU and 32 GB. Enterprise workspaces use Pro sizing. Railway can raise the size for a workspace.

Each workspace can create a limited number of agents in a rolling 24-hour window. All members share the limit, and forks count toward it. A task that starts a new agent uses the same allowance, as does the first [`railway agent`](/cli/agent) thread in an environment.

| Plan | Agents per 24 hours |
|------|---------------------|
| Trial | 50 |
| Free | 20 |
| Hobby | 50 |
| Pro | 100 |

To raise the limit, contact Railway on <a href="https://station.railway.com" target="_blank">Central Station</a>.

## Explore cloud agents

- [Quickstart](/cloud-agents/quickstart): choose your workflow, connect, and do your first task.
- [Terminal sessions](/cloud-agents/terminal): launch coding agents in Railway CA and return to running work.
- [Herdr](/cloud-agents/herdr): create and connect to cloud agents from Herdr's sidebar.
- [Manage agents and sessions](/cloud-agents/manage): select projects, create agents, reconnect, sleep, and delete.
- [Credentials and configuration](/cloud-agents/configuration): carry sign-ins, skills, MCP configuration, and variables.
- [Troubleshooting](/cloud-agents/troubleshooting): diagnose connection, startup, and provider sign-in issues.
- CLI references: [`railway ca`](/cli/ca) and [`railway code`](/cli/code).