cloud_agents

Creates, updates, deletes, gets or lists a cloud_agents resource.

Overview

Name	cloud_agents
Type	Resource
Id	railway.agents.cloud_agents

Fields

The following fields are returned by SELECT queries:

get

One CloudAgent row. A persistent cloud agent for running coding harnesses.

Name	Datatype	Description
id	string
name	string
console_target_id	string	Target ID for console or command execution. Null while unavailable.
environment_id	string
project_id	string
agent_ws_url	string	WebSocket endpoint of the in-VM harness gate, for the dashboard chat. Survives sleep: the domain is stable across sleep and wake. Prefers the machine observation; when that carries no gate domain it falls back to the domain network-cp actively serves, so an agent whose observation lagged still offers chat. Null on agents created before the gate existed, or asleep/absent machines.
created_at	string (date-time)
domain	string	The agent machine's public HTTP domain (port 8080) — the live preview. Prefers the observation (falling back to the first declared domain when 8080 was never requested); when the observation carries no domains it falls back to the domain network-cp actively serves on 8080, so a preview shows even when the observation lagged. Returns null while the machine sleeps.
domains	array	Every public domain on the agent's machine, one per port, in the order the machine declared them.
project	object	Project object
region	string	Region the agent's machine runs in. Null briefly after creation, before the machine has been placed.
sessions	array	Live coding-agent sessions, one entry per session. Retained for 24h after the last report, so a sleeping agent still shows what it was last doing.
source	object	Repo this agent's workspace was created from. Null for agents created without a source.
status	string	(CRASHED, DELETING, FAILED, RUNNING, SLEEPING, STARTING)

list

One row per CloudAgent. A persistent cloud agent for running coding harnesses.

Name	Datatype	Description
id	string
name	string
console_target_id	string	Target ID for console or command execution. Null while unavailable.
environment_id	string
project_id	string
agent_ws_url	string	WebSocket endpoint of the in-VM harness gate, for the dashboard chat. Survives sleep: the domain is stable across sleep and wake. Prefers the machine observation; when that carries no gate domain it falls back to the domain network-cp actively serves, so an agent whose observation lagged still offers chat. Null on agents created before the gate existed, or asleep/absent machines.
created_at	string (date-time)
domain	string	The agent machine's public HTTP domain (port 8080) — the live preview. Prefers the observation (falling back to the first declared domain when 8080 was never requested); when the observation carries no domains it falls back to the domain network-cp actively serves on 8080, so a preview shows even when the observation lagged. Returns null while the machine sleeps.
domains	array	Every public domain on the agent's machine, one per port, in the order the machine declared them.
project	object	Project object
region	string	Region the agent's machine runs in. Null briefly after creation, before the machine has been placed.
sessions	array	Live coding-agent sessions, one entry per session. Retained for 24h after the last report, so a sleeping agent still shows what it was last doing.
source	object	Repo this agent's workspace was created from. Null for agents created without a source.
status	string	(CRASHED, DELETING, FAILED, RUNNING, SLEEPING, STARTING)

list_mine

One row per CloudAgent. A persistent cloud agent for running coding harnesses.

Name	Datatype	Description
id	string
name	string
console_target_id	string	Target ID for console or command execution. Null while unavailable.
environment_id	string
project_id	string
agent_ws_url	string	WebSocket endpoint of the in-VM harness gate, for the dashboard chat. Survives sleep: the domain is stable across sleep and wake. Prefers the machine observation; when that carries no gate domain it falls back to the domain network-cp actively serves, so an agent whose observation lagged still offers chat. Null on agents created before the gate existed, or asleep/absent machines.
created_at	string (date-time)
domain	string	The agent machine's public HTTP domain (port 8080) — the live preview. Prefers the observation (falling back to the first declared domain when 8080 was never requested); when the observation carries no domains it falls back to the domain network-cp actively serves on 8080, so a preview shows even when the observation lagged. Returns null while the machine sleeps.
domains	array	Every public domain on the agent's machine, one per port, in the order the machine declared them.
project	object	Project object
region	string	Region the agent's machine runs in. Null briefly after creation, before the machine has been placed.
sessions	array	Live coding-agent sessions, one entry per session. Retained for 24h after the last report, so a sleeping agent still shows what it was last doing.
source	object	Repo this agent's workspace was created from. Null for agents created without a source.
status	string	(CRASHED, DELETING, FAILED, RUNNING, SLEEPING, STARTING)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	environment_id, id		A cloud agent by ID, within an environment. Null when the agent belongs to another one, so a caller cannot render an agent it has switched away from. Backed by the Railway GraphQL query cloudAgent.
list	select	environment_id	mine	Cloud agents in an environment. Backed by the Railway GraphQL query cloudAgents.
list_mine	select			Cloud agents you own, across every project and environment you can reach. Answers "where are my agents" in one request; cloudAgents needs one call per environment. Machine fields (status, domain, domains) read the last observed state in batched queries, so selecting them across many environments is fine. Backed by the Railway GraphQL query myCloudAgents.
create	insert	environment_id		Create a cloud agent. Backed by the Railway GraphQL mutation cloudAgentCreate.
delete	delete	id		Delete a cloud agent. Backed by the Railway GraphQL mutation cloudAgentDelete.
deploy	exec	id	path, regions, service_name	Build the agent's code inside its own VM and deploy it. Creates the named service (default: the agent's name) or reuses it. Needs an agent booted with the builder. Backed by the Railway GraphQL mutation cloudAgentDeploy.
fork	exec	id	name, variables	Duplicate a running cloud agent. Backed by the Railway GraphQL mutation cloudAgentFork.
harness_token	exec	environment_id, id		Mint a short-lived (5m) JWT for the agent's harness WebSocket (see agentWsUrl). The in-VM gate verifies signature/exp/aud and pins it to this agent. Mint one per dial; the token only has to survive the upgrade. Backed by the Railway GraphQL mutation cloudAgentHarnessToken.
sleep	exec	id		Sleep a running cloud agent, keeping its volume. Processes on the machine are terminated; waking re-runs its entrypoint. Backed by the Railway GraphQL mutation cloudAgentSleep.
wake	exec	id		Wake a sleeping cloud agent. Backed by the Railway GraphQL mutation cloudAgentWake.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
environment_id	string
id	string
mine	boolean	Return only the agents that belong to you. By default every agent in the environment is returned, including your teammates'.
name	string
path	string
regions	object	Replicas per region, e.g. { "us-west2": 3 }. Saved on the service; omit to keep its current regions.
service_name	string
variables	object

SELECT examples

get

A cloud agent by ID, within an environment. Null when the agent belongs to another one, so a caller cannot render an agent it has switched away from. Backed by the Railway GraphQL query cloudAgent.

SELECT
id,
name,
console_target_id,
environment_id,
project_id,
agent_ws_url,
created_at,
domain,
domains,
project,
region,
sessions,
source,
status
FROM railway.agents.cloud_agents
WHERE environment_id = '{{ environment_id }}' -- required
AND id = '{{ id }}' -- required
;

list

Cloud agents in an environment. Backed by the Railway GraphQL query cloudAgents.

SELECT
id,
name,
console_target_id,
environment_id,
project_id,
agent_ws_url,
created_at,
domain,
domains,
project,
region,
sessions,
source,
status
FROM railway.agents.cloud_agents
WHERE environment_id = '{{ environment_id }}' -- required
AND mine = '{{ mine }}'
;

list_mine

Cloud agents you own, across every project and environment you can reach. Answers "where are my agents" in one request; cloudAgents needs one call per environment. Machine fields (status, domain, domains) read the last observed state in batched queries, so selecting them across many environments is fine. Backed by the Railway GraphQL query myCloudAgents.

SELECT
id,
name,
console_target_id,
environment_id,
project_id,
agent_ws_url,
created_at,
domain,
domains,
project,
region,
sessions,
source,
status
FROM railway.agents.cloud_agents
;

INSERT examples

create

Create a cloud agent. Backed by the Railway GraphQL mutation cloudAgentCreate.

INSERT INTO railway.agents.cloud_agents (
cloud_agent_checkpoint_id,
code_endpoint,
environment_id,
name,
region,
source,
variables
)
SELECT 
'{{ cloud_agent_checkpoint_id }}',
'{{ code_endpoint }}',
'{{ environment_id }}' /* required */,
'{{ name }}',
'{{ region }}',
'{{ source }}',
'{{ variables }}'
RETURNING
id,
name,
console_target_id,
environment_id,
project_id,
agent_ws_url,
created_at,
domain,
domains,
project,
region,
sessions,
source,
status
;

Manifest

# Description fields are for documentation purposes
- name: cloud_agents
props:
  - name: cloud_agent_checkpoint_id
    value: "{{ cloud_agent_checkpoint_id }}"
    description: |
      Create the cloud agent from an existing checkpoint.
  - name: code_endpoint
    value: "{{ code_endpoint }}"
    description: |
      Provision a code-* domain. Omit to disable, including when restoring a checkpoint or bootstrap. JSON object of GraphQL type CloudAgentCodeEndpointInput; keys keep the API's camelCase names.
  - name: environment_id
    value: "{{ environment_id }}"
  - name: name
    value: "{{ name }}"
  - name: region
    value: "{{ region }}"
    description: |
      Region to run the agent in, e.g. us-west2. Defaults to the checkpoint's region when booting from one, else the workspace's preferred region.
  - name: source
    value: "{{ source }}"
    description: |
      JSON object of GraphQL type CloudAgentSourceInput; keys keep the API's camelCase names.
  - name: variables
    value: "{{ variables }}"

DELETE examples

delete

Delete a cloud agent. Backed by the Railway GraphQL mutation cloudAgentDelete.

DELETE FROM railway.agents.cloud_agents
WHERE 
id = '{{ id }}' --required
;

Lifecycle Methods

deploy

Build the agent's code inside its own VM and deploy it. Creates the named service (default: the agent's name) or reuses it. Needs an agent booted with the builder. Backed by the Railway GraphQL mutation cloudAgentDeploy.

EXEC railway.agents.cloud_agents.deploy 
@id='{{ id }}', --required
@path='{{ path }}',
@regions='{{ regions }}',
@service_name='{{ service_name }}'
;

fork

Duplicate a running cloud agent. Backed by the Railway GraphQL mutation cloudAgentFork.

EXEC railway.agents.cloud_agents.fork 
@id='{{ id }}', --required
@name='{{ name }}',
@variables='{{ variables }}'
;

harness_token

Mint a short-lived (5m) JWT for the agent's harness WebSocket (see agentWsUrl). The in-VM gate verifies signature/exp/aud and pins it to this agent. Mint one per dial; the token only has to survive the upgrade. Backed by the Railway GraphQL mutation cloudAgentHarnessToken.

EXEC railway.agents.cloud_agents.harness_token 
@environment_id='{{ environment_id }}', --required
@id='{{ id }}' --required
;

sleep

Sleep a running cloud agent, keeping its volume. Processes on the machine are terminated; waking re-runs its entrypoint. Backed by the Railway GraphQL mutation cloudAgentSleep.

EXEC railway.agents.cloud_agents.sleep 
@id='{{ id }}' --required
;

wake

Wake a sleeping cloud agent. Backed by the Railway GraphQL mutation cloudAgentWake.

EXEC railway.agents.cloud_agents.wake 
@id='{{ id }}' --required
;