Getting Started

The blaise-agent CLI bridges your machine and the Blaise platform. Once running, Blaise can dispatch Claude Code sessions to your environment — triggered by Linear issues or prompts from the dashboard. The CLI only makes outbound HTTPS connections, so it works from laptops, servers, containers and CI runners without a public address, open port, TLS certificate or tunnel.

How a runner prepares the environment, and what it does between messages, is configured with a blaise.yml and plugs. This page gets a runner started; the runner documentation covers the rest.

Prerequisites

• Bun 1.0+ (the CLI uses Bun APIs and does not run on Node.js)
• Claude Code installed and authenticated (claude --version should work)
• A Blaise account with at least one workspace, and admin rights to register runners

Installation

Install the CLI globally with Bun:

bun add -g @blaiseagent/cli

# verify
blaise-agent --version

Typical setup

1. In the dashboard, create a Local agent under Settings → Agents.

2. On the machine that should run sessions, sign in once:

   blaise-agent login

   The command asks nothing: the browser opens, you choose the workspace there if you belong to several, and approve.

3. Create a blaise.yml in the directory the agent should work in. The smallest one has no plugs:

   version: 1

4. Start listening:

   blaise-agent listen

That's it — Blaise will start dispatching sessions to the machine. To prepare a checkout, install tools, or run the agent somewhere else, add plugs: follow the first tutorial.

Signing in (blaise-agent login)

login uses the OAuth device flow, so it works over SSH and on headless machines:

1. The CLI prints a URL and a short code, and opens your browser when it can.
2. You sign in to Blaise (if needed), check that the code matches, and click Approve.
3. If you administer several workspaces, you pick the one this machine belongs to on the same page.
4. The CLI registers this machine as a runner of that workspace and prints the workspace name. Which agents a runner serves is decided by labels, not by login: see labels.

Where the runner token is stored

Registration returns a runner token that lets this machine receive sessions for the workspace's agents whose requirements its labels satisfy. It is stored per server URL:

• in the system keychain — macOS Keychain, Windows Credential Manager, or the Linux Secret Service (GNOME Keyring, KWallet);
• otherwise (headless servers, containers) in credentials.json under your configuration directory ($XDG_CONFIG_HOME/blaise, ~/Library/Application Support/blaise or %APPDATA%\blaise), readable only by your user.

Use blaise-agent status to see which runner and workspace the machine is authorized as and the labels it declares, and blaise-agent logout to remove the stored token. To invalidate a token, revoke the runner in the dashboard.

Supplying a token without logging in

For CI, containers and secret managers, pass a runner token directly instead of running login on the machine. The first available source wins:

1. --token <token>
2. the BLAISE_RUNNER_TOKEN environment variable
3. server.token in blaise.yml (use an expression such as ${{ env.CI_RUNNER_TOKEN }} rather than a literal value)
4. the token stored by blaise-agent login

To obtain one, run blaise-agent login --name ci --print-token on any machine: it registers a runner and prints its token once, without storing it, so you can save it as a CI or container secret. Revoke the runner in the dashboard when the secret is no longer needed.

Configuration file

The runner is configured with a blaise.yml in your working directory (or pass -C /path/to/blaise.yml). Besides the server and log sections, whose options also have flags and environment variables, its setup list names the plugs that run each session:

version: 1
log:
  level: ${{ env.LOG_LEVEL || 'info' }}
setup:
  - use: blaise:git/worktree

Configuration for different environments is shared with !include rather than named presets: see Share configuration between files. Every key is in the configuration reference.

Commands

blaise-agent listen

Connects to Blaise and waits for sessions. When a session is dispatched, every connected runner instance of the workspace whose labels satisfy the agent's requirements is offered it; exactly one claims it. The runner then runs the session through the plugs of your blaise.yml: each plug prepares the environment, the agent starts, and the plugs clean up afterwards. If the connection drops, the CLI reconnects automatically and picks up anything still waiting. A session that no connected instance can serve waits in a queue until one can: see How sessions find a runner.

blaise-agent listen

At startup, listen loads every plug and checks its inputs, and works out whether the plug chain can resume a paused session. Problems are reported together and the runner does not start. See the command line reference and the error messages.

listen takes no options of its own, and needs a blaise.yml.

If the runner accepts a session but cannot start the process for it, it tells Blaise straight away and the session is recovered on another run. A run that cannot reach Blaise for about 30 minutes stops with "Lost contact with Blaise", and Blaise recovers the session in the same way.

Run several listen processes (on one or more machines) with the same runner token to add capacity or redundancy; the dashboard counts them as instances of one runner. A paused session is resumed by an instance of the runner that ran it before, so instances that share a token should be able to find the same environment: see How sessions find a runner.

blaise-agent status and blaise-agent logout

status shows the server, runner, workspace, the labels declared in the configuration, and the token source in effect. logout removes the stored token for the server URL; the runner stays registered until you revoke it in the dashboard.

Global options

These flags apply to all commands:

To run the runner itself in a container, see the Docker guide. To run the agent in a container or on another machine, with the runner token kept outside it, see Run the agent in Docker and Run the agent over SSH.