Shipped plugs
The plugs that come with @blaiseagent/runner, and their inputs.
These plugs ship with @blaiseagent/runner: use them as blaise:<name>. They all act on the
agent's host through ctx.host (except ssh, which provides one), they keep no state of their own,
and they are all resumable. Plugs that ship in their own packages are at the end of this page.
blaise:shell
One script per lifecycle event, on the host.
| Input | Type | Default | Description |
|---|---|---|---|
start | string | Runs when the session starts. | |
resume | string | Runs when a paused session resumes. | |
pause | string | Runs whenever a run ends. $BLAISE_MAY_RESUME is true or false. | |
teardown | string | Runs when the session is over. $BLAISE_END_REASON says why. | |
shell | array of strings | ["sh", "-ec"] | The command that runs a script; the script is appended as an argument. |
env | map of strings | {} | Extra environment for the scripts. |
workingDirectory | string | agent's cwd | Where the scripts run. |
start and resume may append KEY=VALUE lines to the files named by $BLAISE_ENV (the agent's
environment) and $BLAISE_OUTPUT (the plug's outputs). Quotes and an export prefix are
understood; blank lines and comments are skipped. A script that exits non-zero fails the run.
blaise:env
Sets environment variables for the agent and the plugs after it.
| Input | Type | Default | Description |
|---|---|---|---|
files | array of strings | [] | Env files on the host, relative to the agent's directory, loaded in order. |
vars | map of strings | {} | Variables to set. They win over the files. |
required | boolean | false | Fail if an env file is missing. Otherwise it is skipped. |
A file that is missing is the only thing required: false forgives. A file that exists but cannot
be read (permissions, a failing host) always fails the run.
blaise:git/worktree
A worktree and a branch of their own for each session, so concurrent sessions never share a checkout. The path and branch are derived from the session id, so a resumed run finds the same worktree.
| Input | Type | Default | Description |
|---|---|---|---|
repository | string | agent's cwd | The repository to branch from. |
base | string | HEAD | What the new branch starts from. |
branchPrefix | string | blaise/ | Prefix of the branch name. |
keep | always, on-failure or never | on-failure | Whether the worktree survives teardown. |
Outputs: path and branch. The worktree becomes the agent's working directory. On teardown it is
removed with git worktree remove --force, unless keep says otherwise.
base must not start with -, so that Git cannot read it as an option.
blaise:git/clone
Clones a repository into the workspace unless it is already there, which is what a fresh host needs.
| Input | Type | Default | Description |
|---|---|---|---|
repository | string | required | The URL or path to clone. |
ref | string | A branch, tag or commit to check out after cloning. | |
directory | string | the repository's name | Where to clone, relative to the agent's directory. |
depth | integer | Clone only this many commits. ref must then be a branch or tag. |
Output: path. The clone becomes the agent's working directory. A directory that already has a
.git is left alone.
repository and ref must not start with -, so that Git cannot read them as options. The clone
runs with Git's ext:: transport disabled, so a repository value cannot run a command. The checkout
is published with mode 755, readable by other users of the host.
blaise:mcp-servers
Adds MCP servers to the agent's session, on session/new and on session/load.
| Input | Type | Description |
|---|---|---|
servers | array | Each is either { name, command, args?, env? } (stdio) or { name, type, url, headers? } with type http or sse. |
blaise:mise
Makes the project's tools available on the host with mise.
| Input | Type | Default | Description |
|---|---|---|---|
tools | map of strings | {} | Extra tools: node: "22", "npm:@agentclientprotocol/claude-agent-acp": latest. |
bootstrap | boolean | true | Install mise (curl https://mise.run | sh) when the host lacks it. |
version | string | latest | The mise version to install when bootstrapping, such as v2025.1.0. |
trust | boolean | true | Trust the project's mise config, which a fresh clone needs. |
It installs the tools of the project's mise config plus tools, and merges the environment mise
would activate (PATH with the tools, and the [env] section) into the agent's. Running it again
changes nothing, so a resumed run is fast.
The installer is not pinned: without version, bootstrapping installs the latest mise. Set
version to install a specific one. A trusted mise config can run commands on the host, so set
trust: false for a repository you do not control.
blaise:ssh
Makes a machine reached over SSH the host for every plug after it, and for the agent. The machine outlives the session: a resume reconnects, and teardown destroys nothing. Nothing connects until the host is used. See Run the agent over SSH.
| Input | Type | Default | Description |
|---|---|---|---|
host | string | required | Host name or address. |
port | integer | 22 | SSH port. |
user | string | required | The user to log in as. |
identityFile | string | required | Path to the private key, on the runner's machine. |
hostKey | string | required | The pinned host key fingerprint (SHA256:…). A different key fails the connection. |
workdir | string | required | Where the agent starts on the machine; an absolute path. |
os | linux, darwin | linux | The machine's operating system; sets the home directory (/home/<user>, /Users/<user> or /root). |
The host is persistent: the agent runs under the watchdog described in
Hosts and where code runs.
Plugs in their own packages
These plugs are published separately. use: blaise:<name> finds them as @blaiseagent/plugs-<name>
once the package is a dependency.
blaise:docker
Package @blaiseagent/plugs-docker. Runs everything after it in a container named
blaise-<session id>. See Run the agent in Docker.
| Input | Type | Default | Description |
|---|---|---|---|
image | string | required | The image to run. It needs sh, setsid, and the common POSIX tools. |
workdir | string | /workspace | Where the agent starts in the container. |
home | string | /root | The container user's home directory. |
volume | string | A directory on the runner, mounted at workdir. | |
network | string | A Docker network to join. | |
pause | stop or commit | stop | stop keeps the container. commit saves it as blaise-snapshot:<session> and removes it, when the session may resume. |
The plug is stateless: names derive from the session id. Teardown removes the container and the
snapshot. The daemon is whatever DOCKER_HOST points at. The plug asks the daemon whether the
container and the snapshot exist, so an unreachable daemon fails the run instead of being taken for
a missing container.
The container runs with --init, so orphaned processes are reaped. The agent's environment
variables do not appear on the docker command line, where other users of the runner's machine
could read them: they travel in the environment of the docker client. Names must be valid shell
identifiers.
blaise:sandbox
Package @blaiseagent/plugs-sandbox, which depends on @anthropic-ai/sandbox-runtime. Runs the
agent and the plugs after it under operating system limits on files and network. It works on the
runner's own machine only. See
Run the agent under the sandbox.
| Input | Type | Default | Description |
|---|---|---|---|
allowedDomains | array of strings | [] | Domains processes may reach; everything else is blocked. |
deniedDomains | array of strings | [] | Blocked even when allowed above. |
denyRead | array of strings | ~/.ssh, ~/.aws, ~/.config/gcloud | Paths that cannot be read. |
allowWrite | array of strings | [] | Writable paths, besides the agent's directory and the temporary directory. |
denyWrite | array of strings | .env | Paths that cannot be written, even inside allowed ones. |
The plug fails at the start of a run on an unsupported platform, with missing dependencies, or when listed below a plug that switches the host.