Railway.Cloud Agent reference

CloudAgent

Source: src/Railway/CloudAgent.ts

A Railway.CloudAgent is a persistent coding-agent VM in an environment. Sleep keeps the disk; wake re-runs the entrypoint. Cloud agents are Priority Boarding and bill at VM rates while running.

CloudAgent: Create a CloudAgent

Pass the Project (or an Environment). Alchemy generates a unique name unless you pass one. domain is the public URL for port 8080.

const site = yield* Railway.Project("Site");
const agent = yield* Railway.CloudAgent("Coder", {
  environment: site,
});

Changing environment or name replaces the agent

Railway has no cloud-agent update API. A new VM is created, then the old one is deleted — the disk is not copied.

CloudAgent: A stable name

Pass name when you need a stable agent name. Changing it later replaces the agent.

const agent = yield* Railway.CloudAgent("Coder", {
  environment: site,
  name: "reviews",
});

CloudAgent: Variables

variables are create-only. Pair them with a new agent — Railway does not update variables on an existing VM. Values may reference other services via Railway.ref.

const agent = yield* Railway.CloudAgent("Coder", {
  environment: site,
  variables: {
    DATABASE_URL: Railway.ref(db, "DATABASE_URL"),
  },
});

CloudAgent: Sleep and wake

Sleep stops compute billing and keeps the disk. Wake re-runs the entrypoint with files in place. These are not reconciler steps — call sleepCloudAgent / wakeCloudAgent.

yield* Railway.sleepCloudAgent(agent);
yield* Railway.wakeCloudAgent(agent);

CloudAgent: Module-scope declarations

Resource-valued props accept the resource or an Effect producing it.

src/agent.ts

import * as Railway from "alchemy/Railway";

export const Site = Railway.Project("Site");
export const Coder = Railway.CloudAgent("Coder", {
  environment: Site,
});