railway

@computesdk/railway

Railway provider for ComputeSDK - run commands in Railway Sandboxes, ephemeral compute environments backed by the Railway platform.

Installation

npm install @computesdk/railway

Requires Node.js >= 22 — the underlying railway SDK depends on Node 22 APIs (e.g. global WebSocket).

Setup

1. Create a Railway API token at railway.com/account/tokens.
2. Find the environment ID you want sandboxes to run in (Railway project → environment settings).
3. Set the environment variables:

export RAILWAY_API_TOKEN=your_token_here
export RAILWAY_ENVIRONMENT_ID=your_environment_id_here

Quick Start

Configure compute with the Railway provider and create a sandbox:

import { compute } from 'computesdk';
import { railway } from '@computesdk/railway';

compute.setConfig({
  provider: railway({
    token: process.env.RAILWAY_API_TOKEN,
    environmentId: process.env.RAILWAY_ENVIRONMENT_ID,
  }),
});

const sandbox = await compute.sandbox.create();

const result = await sandbox.runCommand('echo "hello from Railway"');
console.log(result.stdout);

await sandbox.destroy();

Alternatively, call the provider factory directly when you only need one provider:

import { railway } from '@computesdk/railway';

const sdk = railway({ token: process.env.RAILWAY_API_TOKEN });
const sandbox = await sdk.sandbox.create();

Configuration

Environment Variables

Variable	Required	Description
RAILWAY_API_TOKEN	Yes	Railway API token used to authenticate.
RAILWAY_ENVIRONMENT_ID	Recommended	Railway environment the sandbox runs in.

Config options

railway({
  token: '...',          // defaults to RAILWAY_API_TOKEN
  environmentId: '...',  // defaults to RAILWAY_ENVIRONMENT_ID
});

Per-command execution timeouts are supported via runCommand's options ({ timeout: ms }), which maps to Railway's timeoutSec.

Supported Features

Feature	Supported	Notes
Command execution (runCommand)	✅	Backed by sandbox.exec. timeout is mapped to Railway's timeoutSec.
Filesystem (filesystem.*)	✅	Implemented over the shell (cat/base64/mkdir/ls/rm) since Railway has no dedicated filesystem API.
List sandboxes (list)	✅	Enumerates sandboxes in the configured environment.
Get / destroy by ID	✅	Via Sandbox.connect / sandbox.destroy.
Port exposure (getUrl)	❌	Railway sandboxes do not expose public per-port URLs.
Templates / snapshots	❌	Railway templates are a build-time builder (Sandbox.template()), not an ID-addressable resource, so they are not mapped to ComputeSDK templates/snapshots.

Limitations

• No port exposure. getUrl throws — Railway sandboxes don't publish public URLs per port.
• Filesystem is shell-based. File operations run shell commands inside the sandbox, so they require a POSIX shell with base64, ls, and the usual coreutils (present on Railway's default image).
• Templates/snapshots are not exposed. Use the underlying railway SDK's Sandbox.template() builder directly if you need custom base images.

License

MIT