Getting Started

Install and configure the Blaise CLI agent to run Claude sessions on your machine.

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, manual prompts from the dashboard, or any webhook.

Prerequisites

Node.js 20+ or Bun 1.0+
Claude Code installed and authenticated (claude --version should work)
A Blaise account with at least one workspace

Installation

Install the CLI globally using your preferred package manager:

# npm
npm install -g @blaise/agent

# bun
bun add -g @blaise/agent

# verify
blaise-agent --version

Configuration file

The agent is configured via a blaise.toml file in your working directory (or pass -C /path/to/blaise.toml). A minimal config looks like:

# blaise.toml

[listen]
command = "blaise-agent start claude"
webhookSecret = "your-webhook-secret"

[listen.tls]           # optional — enable HTTPS
cert = "/etc/ssl/cert.pem"
key  = "/etc/ssl/key.pem"

All fields can also be overridden from environment variables or CLI flags — see the sections below.

Named presets

Presets let you maintain different configurations for different environments (e.g., local vs. CI):

[presets.ci]
logLevel = "warn"
logFormat = "json"

[presets.ci.listen]
command = ["claude", "--model", "claude-sonnet-4-6"]
webhookSecret = "ci-secret"

Activate a preset with -P ci (or --preset ci).

Commands

`blaise-agent start claude`

Reads a task context from stdin and starts a Claude Code session connected to Blaise. This command is normally invoked automatically by blaise-agent listen — you don't need to run it manually unless you're testing.

blaise-agent start claude

If Claude Code is not on your $PATH, specify its location in blaise.toml:

[start.claude]
path = "/usr/local/bin/claude"

`blaise-agent listen`

Starts a local HTTP webhook server. When Blaise wants to dispatch a task, it sends a signed POST request to this endpoint, which in turn spawns blaise-agent start claude.

blaise-agent listen \
  --command "blaise-agent start claude" \
  --webhook-secret "$BLAISE_WEBHOOK_SECRET" \
  --port 3001

Flag	Env var	Default	Description
`--command`, `-c`	—	(required)	Command to run when a task arrives
`--webhook-secret`, `-s`	`BLAISE_WEBHOOK_SECRET`	(required)	HMAC secret for signature verification
`--port`, `-p`	`PORT`	`3001`	TCP port to listen on
`--tls-cert`	`BLAISE_TLS_CERT`	—	Path to TLS certificate (enables HTTPS)
`--tls-key`	`BLAISE_TLS_KEY`	—	Path to TLS private key

Global options

These flags apply to all commands:

Flag	Env var	Default	Description
`--log-level`, `-L`	`LOG_LEVEL`	`info`	`trace` / `debug` / `info` / `warn` / `error` / `fatal`
`--log-format`, `-F`	`LOG_FORMAT`	auto	`pretty` (TTY) or `json` (non-TTY)
`--config`, `-C`	—	`./blaise.toml`	Path to config file
`--preset`, `-P`	—	—	Named preset to activate
`--api-url`, `-A`	`BLAISE_API_URL`	`https://askblaise.com/`	Blaise server URL (only needed for self-hosted)

Typical setup

Generate a webhook secret and save it in your password manager:
```
openssl rand -hex 32
```
Create blaise.toml with the secret and the start command.
Open port 3001 (or your chosen port) in your firewall.
Register the agent's public URL in the Blaise dashboard under Settings → Agents.
Run blaise-agent listen — Blaise will start dispatching tasks.

For running the agent in a container, see the Docker guide.

Getting Started

On this page