Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 10 additions & 4 deletions docs/cloud-agents.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,9 +78,12 @@ Preferences live in `~/.railway/agent-prefs.json`.
Agent selectors accept names or IDs. Lifecycle commands without a selector use
this directory's agent or your only agent, otherwise show candidates.

Disconnecting leaves the VM running and compute billing continues.
`railway ca sleep <agent>` stops compute and ends running processes while keeping
the disk. `railway ca delete <agent>` deletes the VM and its disk.
An agent sleeps after 5 idle minutes: no SSH client attached, almost no
network traffic, and no coding agent working or waiting. Sleeping ends its
processes, including commands left running in a detached session, and keeps the
disk; connecting wakes it. Agents created before October 8, 2026 don't sleep on
their own. `railway ca sleep <agent>` sleeps one now.
`railway ca delete <agent>` deletes the VM and its disk.
The older `railway code --rm` deletes this environment's agent and disk.

Use `railway ca ssh <agent>` for a shell, `--session [name]` to attach to or start
Expand Down Expand Up @@ -146,7 +149,10 @@ Desktop setup uses an existing VM when available, creating one if needed.
`--new` requests a fresh VM; `--agent` selects an existing one.
`railway ca desktop --codex` alone is an alias for Codex `desktop-only` setup.
Setup writes configuration without opening the desktop app. Restart the app to
load the connection. The VM remains awake; rerun setup after sleep or restart.
load the connection. An idle VM sleeps after 5 minutes and connecting wakes it;
Claude and Codex just reconnect. Agents created since October 8, 2026 restart
the OpenCode server on wake, so reconnecting usually works; if it can't connect,
rerun `railway ca desktop --opencode`.

Normal `railway code` Codex setup and connect also configure Desktop in the
background. OpenCode setup and connect configure the matching Desktop edition
Expand Down
20 changes: 8 additions & 12 deletions src/commands/cloud_agent/access.rs
Original file line number Diff line number Diff line change
@@ -1,17 +1,13 @@
//! The `CLOUD_AGENTS` preflight.
//!
//! Cloud agents are behind a Priority Boarding flag. Without it the API refuses
//! the create — but only once the launch has already resolved a credential, a
//! target and an agent, so what someone without the flag saw was a one-line
//! rejection at the end of a pipeline that looked like it was working. This
//! asks first, and answers with the two things that line didn't have: that the
//! flag is what is missing, and where to turn it on.
//! Cloud agents are behind a Priority Boarding flag. The CLI and the dashboard
//! enforce it; the API does not check it on create. This asks before a launch
//! resolves a credential, a target and an agent, and answers with what is
//! missing (the flag) and where to turn it on.
//!
//! Advisory, not a gate. Only a query that succeeds and comes back without the
//! flag stops a launch; anything else (a project token, which cannot read `me`,
//! or a transient failure) proceeds and lets the real call decide. A preflight
//! that blocks work the API would have allowed is worse than the error it
//! replaces.
//! Best-effort. Only a query that succeeds and comes back without the flag
//! stops a launch; anything else (a project token, which cannot read `me`, or a
//! transient failure) proceeds and lets the API's own access checks decide.

use anyhow::{Result, bail};
use colored::Colorize;
Expand Down Expand Up @@ -46,7 +42,7 @@ fn has_cloud_agents(flags: &[queries::cloud_agent_access::ActiveFeatureFlag]) ->
.any(|flag| matches!(flag, ActiveFeatureFlag::CLOUD_AGENTS))
}

/// What to say instead of the API's rejection. Names the flag, says where it
/// What to say when the flag is off. Names the flag, says where it
/// lives, and gives the URL — a flag nobody can find is the same as no flag.
fn not_enabled_message(host: &str) -> String {
format!(
Expand Down
29 changes: 20 additions & 9 deletions src/commands/cloud_agent/desktop.rs
Original file line number Diff line number Diff line change
Expand Up @@ -50,8 +50,11 @@ pub(crate) use opencode_config::configure_installed as configure_installed_openc

Sets up the selected app's connection and credentials without opening the app.
Uses an existing VM when available; --new creates one, --agent selects one.
Restart the app after setup to load its connection. The VM stays running;
railway ca sleep <agent> stops compute. Rerun setup after sleep or restart.
Restart the app after setup to load its connection. An idle VM sleeps
after 5 minutes and connecting wakes it; Claude and Codex just reconnect.
Agents created since Oct 8, 2026 restart the OpenCode server on wake, so
reconnecting usually works. If it can't connect, rerun
railway ca desktop --opencode.

--dry-run previews changes without modifying the VM or local configuration.
--remove removes local configuration and stops the managed OpenCode server.
Expand Down Expand Up @@ -351,7 +354,12 @@ pub async fn command(args: Args) -> Result<()> {
opencode::show_connection(&connection, &prepared.agent_name, desktop.is_ok())?;
desktop.context("OpenCode is running, but Desktop configuration failed. Rerun this command to finish setup.")?;
println!(
"You can close this terminal. Rerun this command after sleeping or restarting the agent."
"{}",
if ca::sleeps_when_idle(prepared.agent_created_at) {
"You can close this terminal. The agent sleeps after 5 idle minutes and restarts OpenCode when it wakes. If Desktop can't connect, rerun this command."
} else {
"You can close this terminal. Rerun this command after sleeping or restarting the agent."
}
);
} else {
code::save_desktop_configuration(&prepared, None, &Ok(true));
Expand Down Expand Up @@ -1071,15 +1079,18 @@ fn summarize(
}
if !apps.iter().any(|app| app.is_opencode()) {
println!(
"\n{} The agent must be awake when the app connects — the relay refuses a\nsleeping one, and a desktop app can't wake it. {} does.",
"!".yellow().bold(),
"\nConnecting over SSH wakes a sleeping agent, so the app wakes it when it\nconnects. If the app times out before the agent is ready, run {} and retry.",
format!("railway ca wake {}", prepared.agent_name).cyan()
);
}
println!(
"{} stops the compute bill when you're done.",
format!("railway ca sleep {}", prepared.agent_name).cyan()
);
let sleep = format!("railway ca sleep {}", prepared.agent_name).cyan();
if ca::sleeps_when_idle(prepared.agent_created_at) {
println!(
"The agent sleeps after 5 idle minutes, which ends its processes; {sleep} sleeps it now."
);
} else {
println!("{sleep} stops the compute bill when you're done.");
}
}

#[cfg(test)]
Expand Down
22 changes: 13 additions & 9 deletions src/commands/cloud_agent/lifecycle.rs
Original file line number Diff line number Diff line change
Expand Up @@ -172,7 +172,8 @@ pub struct SleepArgs {
railway ca ssh my-box --resume # resume the latest Claude conversation
railway ca ssh my-box -- ls -la /app # run a command

Disconnecting leaves the VM running. Sleep ends its processes and keeps its disk."#)]
An idle VM sleeps after 5 minutes and wakes when you connect.
Sleeping ends its processes and keeps its disk."#)]
pub struct SshArgs {
/// Agent name or ID (defaults to this directory's, or your only one)
#[clap(value_name = "AGENT")]
Expand All @@ -186,8 +187,7 @@ pub struct SshArgs {
#[clap(long, conflicts_with_all = ["session", "command"])]
resume: bool,

/// Accepted for compatibility; agents now always stay running on
/// disconnect. `railway ca sleep` stops the compute bill
/// Accepted for compatibility and ignored; it has no effect on sleep
#[clap(long, hide = true)]
keep_awake: bool,

Expand Down Expand Up @@ -475,7 +475,7 @@ pub async fn create(args: CreateArgs) -> Result<()> {
println!(
"{}",
format!(
"Agents have no idle timeout: `railway ca sleep {}` stops the compute bill, `railway ca delete {}` takes the disk with it.",
"An idle agent sleeps after 5 minutes, which ends its processes, and wakes when you connect. `railway ca sleep {}` sleeps it now, `railway ca delete {}` takes the disk with it.",
agent.name, agent.name
)
.dimmed()
Expand Down Expand Up @@ -799,8 +799,9 @@ async fn ssh_connect(args: SshArgs) -> Result<i32> {
// process exits (bounded — see drain_detached).
crate::commands::ssh::tel::drain_detached(Duration::from_secs(2)).await;

// A connection that never happened still woke a machine with no idle
// timeout, so put back what this run changed — but only that. An agent
// A connection that never happened still woke the machine, which then bills
// until it idles out (or indefinitely, for an agent created before idle
// sleep), so put back what this run changed — but only that. An agent
// found already running was someone's deliberate state (possibly a session
// open in another terminal), and a failed connect here is no reason to
// suspend it.
Expand All @@ -819,9 +820,12 @@ async fn ssh_connect(args: SshArgs) -> Result<i32> {
// platform keeps listing those sessions as running, so the next reattach
// landed on a dead name and a blank screen. Sleeping is deliberate now.
println!(
"\nDisconnected — agent {} is still running. `railway ca sleep {}` stops the compute bill.",
agent.name.cyan(),
agent.name
"\nDisconnected — {}",
ca::leave_note(
&agent.name.cyan().to_string(),
&agent.name,
Some(agent.created_at)
)
);

Ok(exit_code)
Expand Down
5 changes: 3 additions & 2 deletions src/commands/cloud_agent/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,8 @@ pub(crate) fn harness_label(slug: &str) -> &str {
Use railway code for a local Codex/OpenCode client connected to a VM.
Agent flags here launch on the VM. Use --new to create a fresh VM.
Flags override preferences; the linked project overrides the saved project.
Disconnecting leaves the VM running. Sleep stops processes and keeps the disk.
An idle VM sleeps after 5 minutes and wakes when you connect.
Sleeping ends its processes and keeps the disk.
Requires Cloud Agents access.
Guide: https://github.com/railwayapp/cli/blob/master/docs/cloud-agents.md"#
)]
Expand Down Expand Up @@ -99,7 +100,7 @@ enum Command {
Launches on the VM directly, without the management interface.
Uses your configured agent and project defaults; --new creates a fresh VM.
Available local credentials are copied to the VM; Claude can mint a setup token.
Disconnecting leaves the VM running. Use railway ca sleep <agent> to stop compute.
An idle VM sleeps after 5 minutes; railway ca sleep <agent> sleeps it now.
Requires Cloud Agents access.
Guide: https://github.com/railwayapp/cli/blob/master/docs/cloud-agents.md"#)]
Start(LaunchArgs),
Expand Down
16 changes: 12 additions & 4 deletions src/commands/cloud_agent/tui/app.rs
Original file line number Diff line number Diff line change
Expand Up @@ -120,6 +120,9 @@ pub struct Agent {
/// with every agents fetch; the VM is never asked.
pub threads: Vec<ThreadSnapshot>,
pub archived: bool,
/// When the agent was created, which decides whether it sleeps when idle
/// (see `ca::sleeps_when_idle`). `None` when the read didn't say.
pub created_at: Option<chrono::DateTime<chrono::Utc>>,
}

/// One reattachable session on an agent's VM.
Expand Down Expand Up @@ -6220,17 +6223,19 @@ impl App {
{
respawn = Some((session.agent_id.clone(), session.harness.clone()));
}
closed = Some(session.agent_name.clone());
closed = Some((session.agent_name.clone(), session.agent_id.clone()));
}
} else {
i += 1;
}
}
self.notice_dropped_panes();
let agent_name = closed?;
let (agent_name, closed_id) = closed?;
if self.quit_when_done && self.sessions.is_empty() {
let created_at = self.agent_by_id(&closed_id).and_then(|a| a.created_at);
self.exit_note = Some(format!(
"Session ended — agent {agent_name} is still running. `railway ca sleep {agent_name}` stops the compute bill."
"Session ended — {}",
crate::controllers::cloud_agent::leave_note(&agent_name, &agent_name, created_at)
));
return Some(Effect::Quit);
}
Expand Down Expand Up @@ -11283,7 +11288,10 @@ pub(crate) mod tests {
a.sessions[0].end_for_test();
assert_eq!(a.reap_ended_sessions(), Some(Effect::Quit));
assert!(a.sessions.is_empty());
let note = a.exit_note.as_deref().expect("says the agent still runs");
let note = a
.exit_note
.as_deref()
.expect("says what happens to the agent");
assert!(note.contains("nimble-otter"), "{note}");
}

Expand Down
2 changes: 2 additions & 0 deletions src/commands/cloud_agent/tui/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -942,6 +942,7 @@ async fn fetch_agents(
work_status: Some(work_status::work_status_from!(a.work_status)),
threads: agent_threads!(a.sessions),
archived: a.archived_at.is_some(),
created_at: Some(a.created_at),
})
.collect())
}
Expand Down Expand Up @@ -977,6 +978,7 @@ async fn fetch_my_agents(
work_status: Some(work_status::work_status_from!(a.work_status)),
threads: agent_threads!(a.sessions),
archived: a.archived_at.is_some(),
created_at: Some(a.created_at),
},
)
})
Expand Down
45 changes: 33 additions & 12 deletions src/commands/code.rs
Original file line number Diff line number Diff line change
Expand Up @@ -73,8 +73,12 @@ use crate::util::shell::shell_join;
// survives sleep. `--refresh-auth` forces a re-mint; `railway logout` drops the
// cache.
//
// Lifecycle: agents are durable and have no idle timeout, so unlike a sandbox
// nothing eventually reaps one. Disconnecting leaves the agent RUNNING —
// Lifecycle: agents are durable; unlike a sandbox, nothing eventually deletes
// one. An idle agent (no SSH client attached, almost no network traffic, and no
// coding agent working or waiting) sleeps after 5 minutes, which ends its
// processes, and wakes on SSH, HTTP or API; agents created before the
// 2026-10-08 deploy never do (see `ca::sleeps_when_idle`). Disconnecting leaves
// the agent RUNNING — the CLI never sleeps it as a side effect, because
// sleeping kills every process on the VM (including durable sessions the
// platform keeps listing as reattachable), so it is a deliberate act:
// `railway ca sleep`, or `s` on the TUI tree.
Expand Down Expand Up @@ -136,7 +140,7 @@ arguments to the agent. Available local credentials are copied to the VM;
Claude can mint a setup token. Codex saves Desktop setup; OpenCode configures
detected Desktop installs.

Disconnecting leaves the VM running. Use railway ca sleep <agent> to stop compute.
An idle VM sleeps after 5 minutes; railway ca sleep <agent> sleeps it now.
Requires Cloud Agents access.
Guide: https://github.com/railwayapp/cli/blob/master/docs/cloud-agents.md"#
)]
Expand Down Expand Up @@ -288,8 +292,7 @@ pub struct LaunchArgs {
#[clap(long, conflicts_with_all = ["remote_agent", "rm"], help_heading = "VM creation")]
no_bootstrap: bool,

/// Accepted for compatibility; agents now always stay running on
/// disconnect. `railway ca sleep` stops the compute bill
/// Accepted for compatibility and ignored; it has no effect on sleep
#[clap(long, hide = true)]
keep_awake: bool,

Expand Down Expand Up @@ -544,7 +547,9 @@ impl LaunchArgs {
}

/// No flags, no arguments — the invocation that means "just open the
/// front door" rather than "launch this exact thing".
/// front door" rather than "launch this exact thing". `--keep-awake` is
/// ignored here as everywhere: a flag that does nothing must not change
/// what runs.
pub fn is_bare(&self) -> bool {
!self.codex
&& !self.opencode
Expand All @@ -555,7 +560,6 @@ impl LaunchArgs {
&& !self.new
&& self.bootstrap.is_none()
&& !self.no_bootstrap
&& !self.keep_awake
&& !self.rm
&& !self.refresh_auth
&& self.name.is_none()
Expand Down Expand Up @@ -2984,6 +2988,9 @@ pub struct Prepared {
pub relay_opts: Vec<String>,
pub agent_id: String,
pub agent_name: String,
/// When the agent was created, which decides whether it sleeps when idle
/// (see [`ca::sleeps_when_idle`]).
pub agent_created_at: chrono::DateTime<chrono::Utc>,
pub environment_id: String,
pub harness: &'static str,
/// True when this run created the agent, which only affects messaging.
Expand Down Expand Up @@ -3103,9 +3110,12 @@ pub async fn launch(args: LaunchArgs) -> Result<()> {
// platform keeps listing those sessions as running, so the next reattach
// landed on a dead name and a blank screen. Sleeping is deliberate now.
println!(
"\nDisconnected — agent {} is still running. `railway ca sleep {}` stops the compute bill.",
prepared.agent_name.cyan(),
prepared.agent_name
"\nDisconnected — {}",
ca::leave_note(
&prepared.agent_name.cyan().to_string(),
&prepared.agent_name,
Some(prepared.agent_created_at)
)
);

if prepared.created {
Expand Down Expand Up @@ -3673,6 +3683,7 @@ async fn prepare_inner(
},
agent_id: cloud_agent.id,
agent_name: cloud_agent.name,
agent_created_at: cloud_agent.created_at,
environment_id,
harness: agent.slug(),
created,
Expand Down Expand Up @@ -3722,8 +3733,9 @@ const FLUSH_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(5);
/// session was writing without reaching into it.
///
/// Best-effort by design. Failing to reach the agent must not stop us sleeping
/// it — agents have no idle timeout, so the alternative to an imperfect sleep is
/// a machine that bills until someone remembers it.
/// it — the alternative to an imperfect sleep is a machine that bills until it
/// idles out, or, for an agent created before idle sleep, until someone
/// remembers it.
pub async fn flush_disk(environment_id: &str, agent_id: &str) {
// Deliberately not `ssh_plumbing`: its ~20s retry budget exists to cross the
// gap while a woken agent becomes attachable. Spending it here would make
Expand Down Expand Up @@ -5654,6 +5666,15 @@ cat
fn launch_args_bareness_and_targeting() {
assert!(LaunchArgs::default().is_bare());

let keep_awake = LaunchArgs {
keep_awake: true,
..Default::default()
};
assert!(
keep_awake.is_bare(),
"--keep-awake is ignored, so it must not turn the TUI into a launch"
);

let mut flagged = LaunchArgs::default();
flagged.set_harness("codex");
assert!(
Expand Down
Loading
Loading