---
title: railway ca
description: Browse and manage cloud agents, configure desktop app connections, and launch persistent coding sessions from the terminal.
---
Browse your projects, launch [cloud agents](/cloud-agents), and connect to their terminal sessions. Set up Claude Desktop, Codex Desktop, or OpenCode with `railway ca desktop`.

<Banner variant="info">Cloud agents require access through <a href="/platform/priority-boarding">Priority Boarding</a>. Update the CLI with <code>railway upgrade</code> for the latest client integrations.</Banner>

## Usage

```bash
railway ca [COMMAND] [OPTIONS]
```

With no arguments, `railway ca` opens the terminal interface. Launch flags open the coding session in Railway CA; `railway ca start` skips the interface. OpenCode flags on `ca` run the coding client on the cloud agent. Use [`railway code --opencode`](/cli/code#opencode-local-clients) for local terminal clients.

## Subcommands

| Subcommand | Description |
|------------|-------------|
| `setup` | Configure the default project, coding agent, skills, and theme |
| `start` | Launch a coding agent without the Railway CA interface |
| `desktop` | Prepare a cloud agent and configure a local desktop app |
| `herdr` | Create and manage cloud agents as Herdr machines |
| `list` | List your agents across projects, or within an explicit scope |
| `create [NAME]` | Create a VM without attaching a coding client |
| `ssh [AGENT] [-- COMMAND...]` | Attach to an existing agent's terminal session or run a command |
| `sleep [AGENT]` | Stop compute and processes while retaining the disk |
| `wake [AGENT]` | Wake an existing agent |
| `delete [AGENT]` | Delete an agent and its disk, after confirmation |
| `task` | Hand work to a cloud agent and read the result. See [Tasks](#tasks). |

`AGENT` accepts a name or ID. When omitted for lifecycle commands, Railway uses the directory's agent or the sole candidate and reports candidates when it cannot choose. `--project` and `--environment` narrow the scope.

## Launch options

`railway ca` and `railway ca start` share the launch options in the [`railway code` reference](/cli/code#options). Choose `--claude`, `--codex`, `--grok`, `--railway`, or `--opencode`. With no flag, the saved default applies, overridden by `RAILWAY_CA_AGENT` when set.

```bash
railway ca --opencode
railway ca start --codex --new
```

Agents remain running after disconnect. Use `railway ca sleep` to stop compute; the legacy `--keep-awake` flag is no longer needed.

## Desktop

Prepare the remote tool and its local app connection:

<CodeBlock>
  <CodeTab label="Claude Desktop" lang="bash">{"railway ca desktop --claude"}</CodeTab>
  <CodeTab label="Codex Desktop" lang="bash">{"railway ca desktop --codex"}</CodeTab>
  <CodeTab label="OpenCode" lang="bash">{"railway ca desktop --opencode"}</CodeTab>
</CodeBlock>

| Option | Description |
|--------|-------------|
| `--claude` | Write SSH configuration and Claude Desktop's named environment |
| `--codex` | Write the SSH alias discovered by Codex Desktop |
| `--opencode` | Start the OpenCode server and save its Desktop connection and project |
| `--agent <NAME_OR_ID>` | Use an existing agent |
| `--new` | Always create a fresh VM; conflicts with `--agent` and `--remove` |
| `--dir <PATH>` | Remote starting directory, default `/app`; choose the remote folder in Codex itself |
| `--alias <NAME>` | Override the generated `railway-agent-<name>` SSH alias |
| `--ssh-config <PATH>` | SSH file to write, default `~/.ssh/config` |
| `--dry-run` | Preview setup without local changes or creating, waking, or changing a VM |
| `--remove` | Remove managed local configuration and stop a managed OpenCode server on an awake VM |
| `--no-verify` | Skip SSH probes; OpenCode HTTPS authentication is still checked |
| `-p`, `--project <PROJECT>` | Project ID |
| `-e`, `--environment <ENVIRONMENT>` | Environment name or ID |

App flags can be combined for the same VM, such as `--claude --codex`. Without `--new`, setup reuses and wakes an agent where possible, creating one if needed.

Claude and Codex connect over SSH. Restart the app after setup and select the remote environment or project. OpenCode starts a server on the agent's HTTPS app endpoint, using port `8080`, and saves its generated username/password and project in OpenCode Desktop. An occupied port fails without stopping the other process.

On macOS, OpenCode setup restarts the running OpenCode app. Quit it before setup on Windows/Linux. Select **Home → Projects → Railway: &lt;agent-name&gt; → /app → New session**. Existing chats retain their server.

`--remove` leaves the VM and disk intact and does not wake a sleeping agent. It removes the shared managed SSH entry, so other apps using that alias are affected. `--remove` conflicts with `--dry-run` and `--dir`.

App walkthroughs: [Claude Desktop](/cloud-agents/claude), [Codex Desktop](/cloud-agents/codex), and [OpenCode](/cloud-agents/opencode).

## Herdr

Use `railway ca herdr` to add cloud agents to Herdr and manage their lifecycle. Requires Railway CLI 5.62.0 or later and Herdr 0.9 or later on macOS or Linux. For setup, see [Herdr](/cloud-agents/herdr).

In Herdr's **Local** terminal, run `railway ca herdr install` once to link the plugin. Then choose one:

```bash
# Create a fresh VM for Codex
railway ca herdr new --codex

# Connect an existing VM, or manage sleep, wake, and deletion
railway ca herdr agents
```

| Subcommand | Description |
|------------|-------------|
| `install` | Link the plugin and add shortcuts. `--print` previews its manifest. `--remove` unlinks it and stops the session's watcher. `--no-keys` leaves keybindings unchanged. |
| `new [NAME]` | Always create a fresh VM, add its Herdr machine, and prepare a coding workspace. Prompts for the target and coding tool. |
| `agents` | Pick an agent to connect, sleep, wake, or delete. `--wake` filters to sleeping agents and wakes directly when only one matches. |
| `sync` | Update saved machines to match agent status and remove entries for deleted agents. Supports `--dry-run` and `--json`. |
| `bootstrap [AGENT]` | Retry workspace setup on an awake VM that already has Herdr. Does not create or wake a VM, or add it to the sidebar. |
| `watch` | Follow agent status for the current Herdr session. `--foreground` prints every event. |

`new` and `agents` handle workspace setup; `bootstrap` and `watch` are not additional setup steps. `new` and `bootstrap` accept `--claude`, `--codex`, `--grok`, or `--railway`. Without a flag, `new` asks you to choose a tool and `bootstrap` uses your saved default.

To select the creation target without project or environment prompts:

```bash
railway ca herdr new code-review --codex \
  --project <project-id> --environment <environment-id>
```

Add `--dry-run` to `new` to preview the selection without creating a VM. To retry setup on an awake agent:

```bash
railway ca herdr bootstrap code-review --codex
```

The plugin starts its watcher automatically with the Herdr session. `sync --spawn-watch` also ensures it is running. Sync updates machines already added to Herdr. Use `agents` to add an existing VM.

Removing the plugin keeps your VMs, disks, and saved Herdr machines. Use the [Local picker for sleep and wake](/cloud-agents/herdr#sleep-and-return).

## Configure cloud agents

`railway ca setup` writes your choices to `~/.railway/agent-prefs.json`.

| Option | Description |
|--------|-------------|
| `-y`, `--yes` | Keep existing preferences or choose defaults without prompts; used when stdout is not a terminal |
| `--show` | Print preferences and exit |
| `--reset` | Remove saved preferences |

Skills sync is off when selecting fresh noninteractive defaults. See [configuration](/cloud-agents/configuration) for sources and import behavior.

## List and create

```bash
railway ca list --json
railway ca create my-agent --project <project-id> --environment production --json
```

`list --all` includes agents belonging to other members and requires an explicit `--environment`. It does not grant access to their credentials or sessions.

`create` supports `--variable`, `--env-file`, `--no-wait`, and `--json`. `--no-wait` returns once creation is requested; it does not mean the agent is ready.

## SSH and lifecycle

```bash
railway ca ssh <agent-name> -- bash
railway ca sleep <agent-name>
railway ca wake <agent-name>
railway ca delete <agent-name>
```

`ssh --session <name>` selects a durable terminal session. `ssh` targets an existing awake VM and does not create one if it cannot find the name.

`sleep --all` sleeps all your running agents, narrowed by an environment filter when supplied. `wake --no-wait` returns before readiness. `delete --yes` skips its confirmation.

Sleep stops processes while retaining files. After waking OpenCode, rerun Desktop setup or a named local-client `connect` command to restart the managed server. See [agent lifecycle](/cloud-agents/manage#sleep-wake-and-delete).

## Tasks

`railway ca task` hands a piece of work to a cloud agent and returns the result, without connecting to the agent. See [Tasks](/cloud-agents/tasks) for how tasks work.

Update the CLI with `railway upgrade` to get `railway ca task`.

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

| Subcommand | Description |
|------------|-------------|
| `run <PROMPT>` | Hand a task to Railway and return its ID. `--watch` follows it to the result. |
| `status <TASK_ID>` | Show a task's state and result. `--watch` follows it until it settles. Alias: `check`. |
| `list` | List tasks in an environment, newest first. Alias: `ls`. |
| `respond <TASK_ID> <ANSWER>` | Answer an approval the task is waiting on |
| `cancel <TASK_ID>` | Cancel a running task |
| `models` | List the models a task can run on |

Every subcommand accepts `--json`. All except `cancel` accept `-p`, `--project` and `-e`, `--environment`, and default to the linked project and environment.

### Run options

These options apply to `railway ca task run`.

| Option | Description |
|--------|-------------|
| `--agent <AGENT>` | Run on an existing agent, by name or ID, in a fresh session |
| `--session <ID>` | Continue a session on `--agent` |
| `--reply-to <TASK_ID>` | Continue the agent and session of an earlier task |
| `--conversation <KEY>` | Continue or start a named conversation |
| `--name <NAME>` | Name for a newly created agent |
| `--repo <OWNER/REPO>` | GitHub repository to clone into a new agent |
| `--branch <BRANCH>` | Branch of `--repo` to check out |
| `--service <SERVICE_ID>` | Service whose source a new agent starts from |
| `--model <MODEL>` | Model to run on. Fixed when a conversation starts. |
| `--effort <EFFORT>` | Reasoning effort, one of the model's supported values |
| `--image <PATH_OR_URL>` | Image the agent sees with the prompt. Repeat for up to four. |
| `--output-schema <FILE>` | JSON Schema file. The result then includes matching structured output. |
| `--idempotency-key <KEY>` | Resending a request with the same key returns the original task |
| `--interactive` | Let the agent ask a question and wait for the answer |
| `-w`, `--watch` | Follow the task to its result instead of returning once it is dispatched. See [Watch a task](#watch-a-task). |
| `-y`, `--accept` | Start a new agent without being asked. Alias: `--yes`. |

`--agent`, `--reply-to`, and `--conversation` are mutually exclusive. On `railway ca task`, `-p` is `--project`. Pass the prompt as an argument.

### Run in the background

`run` hands the task to Railway and returns. It doesn't wait for the task to finish. The task runs in the background, and you come back for the result.

```plaintext
$ railway ca task run "Summarize yesterday's errors" --accept
Task 1098e9ce-fbdb-42ee-a5eb-f9b21cf65cb7 handed to Railway. It runs in the background.
  Pick up the result:  railway ca task status 1098e9ce-fbdb-42ee-a5eb-f9b21cf65cb7
  Follow it live:      railway ca task status 1098e9ce-fbdb-42ee-a5eb-f9b21cf65cb7 --watch
```

With `--json`, `run` prints the task ID, the agent, the session, and the status at dispatch.

`status` shows where the task stands. For a task that is still running, it prints the state and its progress so far. For a finished task, it prints the result.

```bash
railway ca task status <task-id>
```

### Watch a task

`--watch` follows a task live until it settles. Use it on `run` to follow the task you're dispatching, or on `status` to follow one that is already running.

```bash
railway ca task run "Summarize yesterday's errors" --watch
railway ca task status <task-id> --watch
```

| Option | Applies to | Description |
|--------|------------|-------------|
| `-w`, `--watch` | `run` | Follow the task to its result instead of returning once it is dispatched |
| `-w`, `--watch` | `status` | Follow the task until it settles instead of printing its state once. Alias: `--wait`. |

While watching, the CLI prints each tool the agent uses and shows the elapsed time. A watch ends when the task completes, fails, is cancelled, or stops to ask for an answer.

Press Ctrl-C to stop watching. The task keeps running, and the CLI prints the `status` command that returns to it. Closing the terminal has the same effect.

With `--json`, a watch prints no progress and returns the finished task as one JSON object.

### Exit codes

The exit code reflects the task only when the command has its outcome.

| Command | Outcome | Exit code |
|---------|---------|-----------|
| `run` | Task dispatched | `0` |
| `run --watch`, `status`, `status --watch` | Task completed, still running, or waiting on an answer | `0` |
| `run --watch`, `status`, `status --watch` | Task failed or was cancelled | Non-zero |
| `run --watch`, `status --watch` | Watch stopped with Ctrl-C | `130` |

### List and filter

`list` shows the newest tasks you dispatched in the environment.

```bash
railway ca task list --status running
railway ca task list --agent my-agent --limit 50 --json
```

`--status` accepts `pending`, `running`, `awaiting-input`, `completed`, `failed`, and `cancelled`. `--limit` accepts 1 to 100 and defaults to 20.

### Answer and cancel

A task that needs an answer stops in `awaiting-input`, and `status` prints what it asked.

Answer an approval with `respond`, using `allow` or `deny`:

```bash
railway ca task respond <task-id> allow
```

Answer a question by replying to the task:

```bash
railway ca task run "Use the staging database" --reply-to <task-id>
```

`respond` also accepts `accept`, `decline`, and `cancel` for form requests. Pass form values with `--field name=value`, and name the request with `--request <ID>` when a task has more than one pending.

Cancel a running task with `cancel`. Cancelling a finished task changes nothing.

```bash
railway ca task cancel <task-id>
```

### Billing notice

A task with no target starts a new cloud agent, which is billed. `run` tells you and asks before it does.

| Invocation | With a terminal | Without a terminal |
|------------|-----------------|--------------------|
| No target | Asks to continue | Refuses unless `--accept` is passed |
| `--conversation`, first task on the key | Asks to continue | Refuses unless `--accept` is passed |
| `--conversation`, later tasks | Runs | Runs |
| `--agent` or `--reply-to` | Runs | Runs |

The prompt, images, and schema file are checked before anything is asked.

## The interface

The menu offers **New Session**, **New Cloud Agent**, and **Manage Cloud Agents**, with a prompt for a task and a target project. New Session selects an existing agent; New Cloud Agent creates a fresh machine. The tree only adds child rows when actual terminal sessions exist, and loading appears in the agent's status icon.

### Keys

| Key | Action |
|-----|--------|
| `↑` `↓` | Move between rows |
| `→` `←` | Open and close a row |
| `enter` | Open a row or connect to a session |
| `shift+esc` or `^]` | Stop typing in a session |
| `n` | Start a session on an agent or an agent on a project |
| `x` | End the session |
| `s` / `w` / `d` | Sleep, wake, or delete the agent |
| `c` | Copy a session's SSH command |
| `r` | Refresh |
| `t` | Set the prompt's target |
| `^t` | Change the target project |
| `⌥f` | Toggle the full-width session view |
| `shift+enter` | Leave the interface and connect full screen |
| `⌥t` | Cycle theme |
| `⌥s` | Open setup |
| `esc` | Return to the menu |
| `^c` | Quit |

In the coding-agent picker and prompt footer, **Shift+Tab** cycles coding agents. Press `?` for the full key reference in the active view.

### Mouse

Click a row to select it and double-click a session to connect. In a connected session, scroll with the wheel, open links by clicking, and drag to select and copy text. When the coding agent handles mouse input, hold Shift while dragging to select text instead.