Run your first plugged session

Configure a runner with blaise.yml, start it, and watch two plugs act on a real session.

In this tutorial you give a runner a blaise.yml with one plug, start a session, and see the plug prepare the agent's environment and clean up after it. It takes about ten minutes.

You need a Blaise account with a local agent, and Claude Code installed on this machine (claude --version should work).

1. Install the CLI and authorize the machine

Install the CLI and authorize this machine as a runner of your workspace, as described in the CLI setup guide (or follow Connect your first runner):

bun add -g @blaiseagent/cli
blaise-agent login

2. Write a `blaise.yml`

Make an empty directory and create blaise.yml in it:

blaise.yml

version: 1
setup:
  - id: greeting
    use: blaise:shell
    with:
      start: |
        echo "GREETING=hello from a plug" >> "$BLAISE_ENV"
      teardown: |
        echo "session over: $BLAISE_END_REASON" >> teardown.log

setup is a list of plugs. This one, blaise:shell, runs a script when the session starts and another when it is torn down. Whatever the start script appends to $BLAISE_ENV becomes an environment variable of the agent.

3. Start the runner

From the same directory:

blaise-agent listen

The runner uses the plugs of the blaise.yml. Before it waits for sessions it resolves them, and logs:

Plugs loaded  plugs: ["plug 1 \"greeting\" (blaise:shell)"]
Connected to Blaise; waiting for sessions

4. Start a session

Open your agent in the Blaise dashboard and start a session. Ask:

What is the value of the GREETING environment variable?

The agent answers hello from a plug. The start script ran before the agent started, and its output reached the agent's environment.

5. End the session

Close the session in the dashboard: open it and choose End session in the Environment panel. The runner is told to stop, it pauses the plug and then tears it down, and the teardown script runs. Check the file it wrote:

cat teardown.log

session over: closed

What you did

You gave the runner a list of plugs, and the runner ran each session through them: the plug prepared the agent before it started and cleaned up after it ended. Where to go next: