Team Setup

Deploy a server, create team keys, and onboard your developers.

This guide covers setting up Waypoint for a team from scratch — deploying the server, bootstrapping the admin account, issuing keys, and onboarding developers.

Step 1 — Deploy the server

See Deployment for full options. The quickest path for most teams is Docker Compose on a small VPS or Railway.

Minimum requirements: 1 CPU, 512 MB RAM, Postgres 14+.

Set the required environment variables before starting:

cp .env.example .env
# Fill in:
#   POSTGRES_PASSWORD=<openssl rand -hex 16>
#   WAYPOINT_JWT_SECRET=<openssl rand -hex 32>
#   WAYPOINT_RESET_TOKEN=<openssl rand -hex 24>

docker compose up -d

Warning

Store WAYPOINT_RESET_TOKEN somewhere safe (e.g. your team's password manager). You'll need it to recover if the admin key is ever lost.

Step 2 — Bootstrap the admin

On first boot, the server prints an initial admin key to the logs:

docker compose logs waypoint | grep "wp_"

Copy the key. Navigate to your server's URL in a browser and log in with it. You'll be redirected to /admin/rotate — create your personal admin key here. The bootstrap key is revoked and you'll be asked to log in again with the new key.

Step 3 — Create keys for your team

Go to /admin and create a key for each developer (or one shared key for the team, though per-person keys are easier to revoke):

Name: developer's name or machine
Scopes: sessions:write, sessions:read

Copy each key and share it with the respective developer. Keys are shown once.

Step 4 — Onboard developers

Each developer runs two commands:

# Install the CLI (once per machine)
npm install -g @laserowl/waypoint

Not yet on npm

# Connect to the server
waypoint connect https://waypoint.yourcompany.com
# Paste their API key when prompted

Then in each repo they work in:

waypoint init

When init asks for the server URL and API key, they can skip (since waypoint connect already configured it globally).

Step 5 — Verify

Have a developer run a short agent session, then check the server's session list at /. Sessions should appear within a few seconds of the session ending.

Day-to-day operations

Adding a new developer: Create a new key in /admin, share it, have them run waypoint connect.

Offboarding a developer: Revoke their key from /admin. Their existing sessions remain in the database.

Rotating a compromised key: Revoke the old key, create a new one, have the developer run waypoint connect again with the new key.

Upgrading the server: Pull the new image and restart. The database schema is updated automatically via additive migrations — no manual migration steps needed.

PreviousCLI Commands NextPR Summary