Relaypreview
Quickstart

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

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

Browse the docs mapSee 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 preview.

01

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
02

Install the CLI

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

Command
cd relay-client
npm install
npm link
relay version
relay agent status
03

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.

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

# Remote machine - HTTP transport
relay init --url http://host:8080 --token YOUR_TOKEN \
  --app my-app --env preview --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 preview 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 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` and leave plugin mutations disabled unless you are actively managing them.