Configuration

Top-level keys

Key	Type	Description
`version`	`1`	Required. The format version.
`server`	mapping	`url` and `token`. Optional.
`log`	mapping	`level` and `format`. Optional.
`labels`	mapping	Labels this runner declares. Optional.
`capacity`	integer	Most sessions this instance runs at once. Optional.
`agent`	mapping	`driver`, `command` and `args`. Optional.
`setup`	list	The plugs, in order. Optional.
`.<name>`	any	Hidden keys: ignored, used to hold YAML anchors.

Any other top-level key is an error. There are no timing settings: idle detection, pausing, how long a session stays paused and the session timeout are agent settings in Blaise.

`server`

Key	Default	Description
`url`	`https://askblaise.com`	Base URL of the Blaise server. A valid URL.
`token`	the stored credential	Runner token. Overrides the credential stored by `blaise-agent login`. Prefer an expression to a literal.

`log`

Key	Values	Description
`level`	`trace`, `debug`, `info`, `warn`, `error`, `fatal`	Minimum level to emit.
`format`	`pretty`, `json`	Output format. Auto-detected from the TTY.

Key/value pairs that describe this runner. Agents state requirements over labels, and Blaise only offers a session to a runner whose labels include every value the agent requires. A value is a string or a list of strings; a string is the same as a list of one.

blaise.yml

labels:
  os: linux
  pool: [build, gpu]

Keys start with a letter or digit and contain letters, digits, ., _, - and /, up to 63 characters.
Values are trimmed, non-empty, up to 128 characters, with at most 32 per key and 32 keys.
Values may use ${{ env.* }} expressions, evaluated when the runner starts.
Labels belong to each running instance: the file is read again on every start, and a change takes effect when listen reconnects.

An agent without requirements runs on any runner of the workspace.

`capacity`

The most sessions this instance runs at once, a whole number from 1 to 1000. Leave it out for no limit.

capacity: 4

Blaise offers a waiting session first to the matching instance with the most free capacity, and never offers or lets an instance claim one beyond its capacity. Cleanup runs are not counted against the limit.
Capacity belongs to each running instance: the file is read again on every start, and a change takes effect when listen reconnects. Runs already in progress are not interrupted.
The value is a plain number; ${{ }} expressions are not supported here.

`agent`

Key	Description
`driver`	The ACP agent driver to launch, for example `claude`.
`command`	Executable that starts the ACP agent. Overrides the driver's default.
`args`	List of arguments for `command`.

claude is the supported driver. Selecting it explicitly uses claude-agent-acp unless command is supplied. Unsupported driver names fail before the agent starts.

The agent section is layered over the adapter configuration that Blaise sends with the session. It is evaluated when a run starts, so it can use the session and run contexts.

Entries of `setup`

Each entry of setup is a plug.

Key	Required	Description
`use`	yes	The plug: `blaise:<name>`, a path or a package. See Resolving plugs. Cannot contain expressions.
`with`	no	Inputs, validated by the plug's own schema. May contain expressions.
`id`	no	Unique name. Starts with a letter or `_`, then letters, digits, `_` or `-`. Required for plugs that persist state.

An id lets later entries read the plug's outputs as setup.<id>.outputs.<key>, and keys the plug's persisted state.

These are checked when the file loads, and every problem is reported at once:

unknown keys, in the file or in an entry;
duplicate id values;
expressions that do not parse, or use a context that is not available there;
a setup.<id> reference to an id that no earlier entry declares.

Hidden keys

Top-level keys that start with . are dropped before validation. Use them to hold anchors, which you reference with aliases (*name) or merge keys (<<: *name):

.secret-patterns: &secret-patterns
  - "sk-ant-[A-Za-z0-9_-]+"

setup:
  - use: ./plugs/redact-secrets.ts
    with:
      patterns: *secret-patterns

`!include`

!include <path> replaces the node with the contents of another YAML file. The path is relative to the file that contains the tag.

Where the tag is	Result
An item of a sequence	An included sequence is spliced in place (one level). An included mapping is one item.
The value of a merge key (`<<`)	The included mapping is merged. Keys in the including mapping win. It must be a mapping.
Anywhere else	The node is replaced by the included value.

Includes nest, and a cycle is an error that names the chain. Each file is its own YAML document, so anchors do not cross files. A relative use: path in an included file is relative to that file.

Quoting

@ is a reserved character in YAML, so a third-party scoped package must be quoted:

- use: "@acme/blaise-vault"

The loader recognises this error and suggests the quotes.