Getting started (beta)

Stations moves a card through a sequence of stations. Each station describes a job, who can do it, and what must be true before the card moves on. People and agents stay assigned to stations; cards visit them.

This guide takes a first card from a human's instructions to an agent's work and back to a human for approval.

1. Get beta access

Today, access is granted. There is no self-serve signup (#871). Ask the person providing beta access for a workspace invitation, its sign-in address, and the Gateway address for the CLI. The Gateway is the public endpoint that accepts requests from tools.

The CLI is not on a public registry yet. It is not published, so npx stations will not install it and npm i -g @stations/cli will not resolve. It does install: one package with two commands, stations and stations-mcp, and no runtime dependencies, built as a tarball from the prepared workspace supplied for beta access. Wire your harness has the three lines that do it, and the rest of this page works the same whether you install the package or run the binary straight out of that workspace.

Publishing the package is what turns those three lines into one, and when it happens this paragraph goes away. Until then, building the tarball is the part that still needs a checkout; nothing else on this page does. If neither the workspace nor the binary is available, ask the person providing access — a browser invitation alone does not supply the CLI.

Open the invitation and follow its registration steps, or sign in at the address provided. Use the workspace's web address for product paths such as /dashboard, /boards, and /projects below. Ask a workspace owner to help if the creation controls used in this guide are unavailable; they require permission, and the shared demo does not allow this setup.

2. Choose the right token

A token identifies the actor making a request. Two kinds look similar:

• A Settings PAT (personal access token), created with Create token at /settings, represents the human actor who created it. This API key is separate from the browser session. It can read boards and cards as that person, but cannot perform the agent claim and completion steps below.
• An agent key, created for an agent at /admin/members, represents that agent actor. A workspace owner can press Create agent, give it a display name such as Practice Agent, and choose its team and role. Then select that agent under Mint agent token, enter a Name such as practice-cli, and press Create token. Leave Expiry (optional) empty unless the token should expire on a particular date.

Both use the stn_ prefix; the prefix alone does not distinguish a human from an agent. Copy the full token when it is shown: that happens only once. Keep it out of card descriptions, comments, and shared files. If it is lost, create another and revoke the unused token.

In the supplied CLI environment, log in with the agent key. Use the Gateway address provided with access; https://stations.dev below is the hosted Gateway. Replace it if a different address was supplied.

stations login --api-url https://stations.dev
stations whoami

The login prompt hides the pasted token. Although it mentions Settings, paste the agent token created at /admin/members for this exercise. If the environment already sets STATIONS_TOKEN or STATIONS_API_URL, those values override the saved login; clear or update them to match the intended agent and Gateway.

Check that kind is agent and the workspace is the intended one before any claim. A human result means the wrong token was supplied. Keep the browser signed in as a human; the CLI login does not change that browser session.

3. Create a first board

1. Open /projects. In an empty workspace, choose Create your first project to open /setup. In the first step, set Project name to Onboarding. The Project key text field shows a suggested prefix such as ONBOAR for card identifiers; keep that suggestion unless a different prefix is needed. Press Create project.
2. At /setup step 2, choose Create board to open /projects/<project-id>/boards/new, the board-creation page for that project. If a suitable project already exists, open it from /projects and choose Create board there instead.
3. Set Board name to Release Practice, choose the Pipeline template, and press Create board. Open Release Practice from /boards if it is not already open. The template's starting requirements are listed below.
4. Enable human sign-off at Implement for this walkthrough. On the newly created board, press Review what this template built. On a later visit, press Board settings. Both open that board's settings page. For Implement, select Require a human sign-off when an agent completes the work and press Save station. Implement has no human sign-off by default; the approval steps later in this guide require this change before the card is created.

Pipeline defaults, before the sign-off edit in step 4:

Station	Required artifact (key and kind)	Human approval for agent completion
Design	None	No
Implement	pull_request (url)	No
Review	spec (text)	Yes
Ship	None	No

A station with no assignments is open to the workspace. If assignments restrict it, have the owner ensure the agent can work at Implement and Review and the human reviewer is assigned to those stations, directly or through a team.

4. Give a card its first instructions

On the board, press New card. Enter a title such as Add a release checklist and a description of the result needed, then press Create card. It starts at Design. Open the card and note its identifier, such as ONBOAR-1.

In the browser, press Claim. Write the checklist's purpose and acceptance criteria in a comment, then press Comment. Press Complete when the design is ready to hand over. The card moves to Implement, where pull_request is still missing. The comment stays with the card for the next actor to read.

Use the actual card identifier in every command below; ONBOAR-1 is an example.

5. Let the agent work the station

These commands act as the agent whose token was saved. They demonstrate the steps an agent harness performs; the CLI does not write the release checklist on its own.

stations boards list
stations card show ONBOAR-1
stations card comments ONBOAR-1
stations claim ONBOAR-1

Read the card's instructions and comments before doing the work. A successful claim reserves this card at its current station for the agent. If claiming is refused, check the token kind, station assignments, and whether someone already holds the card.

Claims expire after five minutes. While working, renew the claim before it expires. For this exercise, keep only one claim active so the command can find it:

stations heartbeat

When the change is ready, attach its real review URL with the exact key the station requires. Replace the example URL below with the change's URL and adjust the comment to describe the actual result.

stations artifact attach ONBOAR-1 --key pull_request --kind url --value https://example.com/pull/42
stations card comment ONBOAR-1 --body="Release checklist added; the linked change is ready for review."
stations complete ONBOAR-1
stations card show ONBOAR-1

Completion at Implement now leaves the card awaiting human approval. Stop agent work on that station and return to the browser.

6. Clear the gate as a human

A gate is a condition that must be satisfied before a card can advance. Attaching the required artifact satisfies the artifact requirement. It does not satisfy human sign-off: the agent cannot approve its own work.

Open /dashboard, find the card awaiting a human decision, and open it. A human assigned to the station, directly or through a team, reviews the result and presses Approve. At an unassigned station, any human in the workspace can approve. Reject asks for a reason and makes the card available for rework at the first station of the nearest earlier phase that has a station. On this Pipeline, rejection at Implement returns the card to Design; rejection at Review returns the card to Implement. Only when no earlier destination exists does the card stay at the same station. Leave enough detail for the next attempt.

The approval gate outlives the claim. A card awaiting approval stays there even if the agent's claim expires. Approval remains a human action in the browser; there is no CLI or MCP approval command.

After approval, the card reaches Review. To finish this practice card, claim it as the agent again, check the change, and attach the review notes as spec:

stations claim ONBOAR-1
stations artifact attach ONBOAR-1 --key spec --kind text --value "Checked the checklist against the acceptance criteria."
stations complete ONBOAR-1

Use notes that describe the review actually performed, then approve in the browser again. At Ship, use Claim, perform the release, and press Complete. Because Ship is the final station, the card is now done. Its comments explain the work; its audit trail records actions such as claims, attachments, and approvals.

Where to go next

• Wire your harness installs the CLI, points Claude Code, Codex or any other harness at the MCP server and its recipes, and starts a dispatcher that claims cards and holds the claim while your agent works.
• CLI documentation introduces the command-line path.
• MCP tool reference lists the tools and inputs for an agent running through an MCP host, using the same agent identity.
• Agent wake webhooks explains how to wake a harness when a card arrives, including signature verification and the polling fallback.