Quickstart

From a cold machine to a live lane without inventing a platform first.

Start the agent, install the CLI, initialize a repo, and deploy. Relay is built so the first dev, staging, or preview lane can be running in minutes instead of after a long platform setup.

Browse the docs map See runtime coverage

What you need

Docker running on the target machine.

Node 18+ for the CLI.

Go 1.22+ only if you build the agent from source.

Path

Three steps, no detours.

The quickstart covers the shortest path from a blank machine to a running lane.

Start the agent

Run `relayd`, let it create `data/token.txt` and `data/relay.sock`, and keep the data directory somewhere persistent if you want deploy history to survive restarts.

Command

cd relayd
go build .
./relayd
# agent listens on :8080 and writes data/relay.sock

Install the CLI

Link the local CLI or install it globally. Supports deploy workflows plus doctor checks, version reporting, and in-place agent updates.

Command

cd relay-client
npm install
npm link
relay version
relay agent status
relay doctor --socket ../relayd/data/relay.sock

Initialize a repo and deploy

On the same machine as the agent, use the Unix socket with no token. On a remote machine, use the HTTP URL and the token from data/token.txt. With no flags, the wizard writes .relay.json for the project. After init, relay doctor confirms transport and server setup before the first deploy.

Command

# Same machine - socket transport (no token)
relay init --socket ./data/relay.sock --app my-app --env dev

# Remote machine - HTTP transport
relay init --url http://host:8080 --token YOUR_TOKEN \
  --app my-app --env staging --branch main

# Or just run a command - wizard starts if config is missing
relay deploy

relay deploy --host-port 3005 --stream

After the first deploy

What to look at next

Once the first lane is up, the right next move depends on whether you are integrating a single app, operating a shared agent, or extending runtime support.

Docs

Use the docs map to align config files, APIs, and operational behavior.

Architecture

Understand where the CLI ends and the Go agent starts.

relayd

Tune server behavior, auth, CORS, and plugin policy before opening it up.

Operator notes

Use .relay.json for CLI defaults: socket path or URL, app, env, branch.

Use relay.config.json for buildpack overrides: install_cmd, build_cmd, start_cmd.

Use relay.json when the app needs companion services (Postgres, Redis, etc.).

Use .relayignore to exclude generated or irrelevant paths from sync uploads without changing Relay's built-in ignores.

Use relay secrets add for environment variables that should not live in a config file.

Production hint

If you run the agent beyond localhost, set explicit `RELAY_CORS_ORIGINS`, keep Docker as the default engine, and remember that dev and staging lanes default to Relay Login unless you change the access policy.