sandboxes

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

Overview

Name	sandboxes
Type	Resource
Id	railway.agents.sandboxes

Fields

The following fields are returned by SELECT queries:

get

One Sandbox row.

Name	Datatype	Description
id	string
environment_id	string
created_at	string (date-time)
domains	array	Railway-provided public HTTP domains whose routes have been published.
idle_timeout_minutes	integer	Minutes of inactivity before the sandbox is destroyed. 0 means it never idles out; null means unknown, including for a destroyed sandbox.
network_isolation	string	(ISOLATED, PRIVATE)
region	string
status	string	(CREATING, DESTROYED, DESTROYING, FAILED, RUNNING)

list

One row per Sandbox.

Name	Datatype	Description
id	string
environment_id	string
created_at	string (date-time)
domains	array	Railway-provided public HTTP domains whose routes have been published.
idle_timeout_minutes	integer	Minutes of inactivity before the sandbox is destroyed. 0 means it never idles out; null means unknown, including for a destroyed sandbox.
network_isolation	string	(ISOLATED, PRIVATE)
region	string
status	string	(CREATING, DESTROYED, DESTROYING, FAILED, RUNNING)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	environment_id, id		Get a sandbox by id. Backed by the Railway GraphQL query sandbox.
list	select	environment_id	active	List sandboxes in an environment, newest first. Passing first/after paginates; omitting them returns the full list. Backed by the Railway GraphQL query sandboxes.
create	insert	environment_id		Create a sandbox in an environment. Backed by the Railway GraphQL mutation sandboxCreate.
destroy	delete	environment_id, id		Destroy a sandbox. Backed by the Railway GraphQL mutation sandboxDestroy.
exec	exec	command, environment_id, id	timeout_sec	Execute a command inside a running sandbox. Backed by the Railway GraphQL mutation sandboxExec.
heartbeat	exec	environment_id, id		Extend a sandbox's lifetime. Backed by the Railway GraphQL mutation sandboxHeartbeat.

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
active	boolean	true = live sandboxes only (excludes destroyed; FAILED and transitional states are still included), false = destroyed only, omitted = all.
command	string
timeout_sec	string	Integer passed as a string, for example '1'.

SELECT examples

get

Get a sandbox by id. Backed by the Railway GraphQL query sandbox.

SELECT
id,
environment_id,
created_at,
domains,
idle_timeout_minutes,
network_isolation,
region,
status
FROM railway.agents.sandboxes
WHERE environment_id = '{{ environment_id }}' -- required
AND id = '{{ id }}' -- required
;

list

List sandboxes in an environment, newest first. Passing first/after paginates; omitting them returns the full list. Backed by the Railway GraphQL query sandboxes.

SELECT
id,
environment_id,
created_at,
domains,
idle_timeout_minutes,
network_isolation,
region,
status
FROM railway.agents.sandboxes
WHERE environment_id = '{{ environment_id }}' -- required
AND active = '{{ active }}'
;

INSERT examples

create

Create a sandbox in an environment. Backed by the Railway GraphQL mutation sandboxCreate.

INSERT INTO railway.agents.sandboxes (
environment_id,
idle_timeout_minutes,
network_isolation,
public_domains,
region,
resources,
source_sandbox_id,
template,
variables
)
SELECT 
'{{ environment_id }}' /* required */,
{{ idle_timeout_minutes }},
'{{ network_isolation }}',
'{{ public_domains }}',
'{{ region }}',
'{{ resources }}',
'{{ source_sandbox_id }}',
'{{ template }}',
'{{ variables }}'
RETURNING
id,
environment_id,
created_at,
domains,
idle_timeout_minutes,
network_isolation,
region,
status
;

Manifest

# Description fields are for documentation purposes
- name: sandboxes
props:
  - name: environment_id
    value: "{{ environment_id }}"
  - name: idle_timeout_minutes
    value: {{ idle_timeout_minutes }}
    description: |
      Minutes of inactivity before the sandbox is destroyed. Any value <= 0 means never idle out (plan-gated). Defaults to the plan's default idle timeout.
  - name: network_isolation
    value: "{{ network_isolation }}"
    description: |
      Network access for the sandbox. Defaults to ISOLATED (no private network access). Public domains require PRIVATE to be selected explicitly.
    valid_values: ['ISOLATED', 'PRIVATE']
  - name: public_domains
    value: "{{ public_domains }}"
    description: |
      Railway-provided HTTP domains to publish, one per unique prefix and port. Supports up to 10 and requires explicitly selecting PRIVATE networking. Domain prefixes are generated when omitted. JSON array of objects of GraphQL type SandboxDomainInput; keys keep the API's camelCase names.
  - name: region
    value: "{{ region }}"
    description: |
      Region to place the sandbox in (e.g. us-west2, us-east4-eqdc4a). Defaults to the platform default region when omitted.
  - name: resources
    value: "{{ resources }}"
    description: |
      Creation-time CPU and memory, including for forks and checkpoint restores. Each omitted or null field uses the workspace's sandbox default; explicit values must not exceed its independent VM maximum. JSON object of GraphQL type SandboxResourcesInput; keys keep the API's camelCase names.
  - name: source_sandbox_id
    value: "{{ source_sandbox_id }}"
    description: |
      Fork an existing running sandbox in this environment. Mutually exclusive with template.
  - name: template
    value: "{{ template }}"
    description: |
      JSON object of GraphQL type SandboxTemplateInput; keys keep the API's camelCase names.
  - name: variables
    value: "{{ variables }}"
    description: |
      Environment variables baked into the sandbox, available to every command. Values may contain Railway variable references (e.g. ${{shared.FOO}}, ${{ServiceName.BAR}}), resolved at create time.

DELETE examples

destroy

Destroy a sandbox. Backed by the Railway GraphQL mutation sandboxDestroy.

DELETE FROM railway.agents.sandboxes
WHERE 
environment_id = '{{ environment_id }}' --required
AND id = '{{ id }}' --required
;

Lifecycle Methods

exec

Execute a command inside a running sandbox. Backed by the Railway GraphQL mutation sandboxExec.

EXEC railway.agents.sandboxes.exec 
@command='{{ command }}', --required
@environment_id='{{ environment_id }}', --required
@id='{{ id }}', --required
@timeout_sec='{{ timeout_sec }}'
;

heartbeat

Extend a sandbox's lifetime. Backed by the Railway GraphQL mutation sandboxHeartbeat.

EXEC railway.agents.sandboxes.heartbeat 
@environment_id='{{ environment_id }}', --required
@id='{{ id }}' --required
;