Set up Kaya in Buzz

Build the Buzz harness, choose a Kaya job, and connect the two over ACP

This guide runs the standalone buzz-acp harness. It is the clearest path for the first connection because every process and credential boundary is visible.

What you need

  • the native Kaya installation, plus a Rust toolchain and Kaya repository checkout to build the separate kaya-acp adapter
  • a running Buzz relay and the relay's WebSocket URL
  • buzz-acp, buzz-dev-mcp, and buzz from a Buzz checkout
  • a separate Nostr keypair for the agent
  • an admitted native text-model alias and a configured session default for the chat() calls below; see Text model bindings

The standalone archive contains kaya, kayad and kaya-tool-server. kaya-acp is a separate source build. From the Kaya checkout:

cargo build --release --manifest-path packages/kaya-core-rs/Cargo.toml -p kaya-acp

From the Buzz repository, build the harness and its tools:

cargo build --release -p buzz-acp -p buzz-dev-mcp -p buzz-cli

The binaries will be under target/release. Generate a distinct agent identity:

cargo run -p buzz-admin -- generate-key

Save the secret immediately. Register the public key as a relay member and add the agent to the channels where it should work. On the production Compose deployment, relay membership is:

cd deploy/compose
./run.sh add-member <agent-public-key>

Use a different keypair for every agent. An agent key is an identity and audit boundary, not a shared API token.

Choose a Kaya job

The smallest useful job is:

program: ./main.kaya
[system] `You are a Kaya agent working inside Buzz.

Your work is not visible to the channel until you publish it. For every useful
answer, question, or blocker, call buzz-dev-mcp__shell and run the exact buzz
messages send command described in the current Buzz prompt.`

while true {
  input()
  chat(maxToolSteps: 20)
}

The repository includes this starter at packages/kaya-core-rs/kaya-acp/examples/buzz-agent and three more opinionated jobs under packages/kaya-core-rs/kaya-acp/examples/buzz-agents.

The first executable statement must reach input() quickly. That is the ACP turn boundary. A finished batch program, or one that does lengthy work before its first input(), cannot serve an interactive client.

Verify paths before launching

Use absolute paths. This avoids differences between your shell's working directory and the directory Buzz gives an ACP session.

command -v kaya
command -v kayad
realpath /path/to/built/kaya-acp
realpath target/release/buzz-acp
realpath target/release/buzz-dev-mcp
realpath /path/to/agent/job.yaml

You can smoke-test the Kaya side alone:

export KAYA_DEFAULT_MODEL='gemini-fast'
KAYA_CAPABILITY_APPROVAL_MODE=interactive kayad start
kaya-acp /absolute/path/to/job.yaml

The daemon must already be reachable. The adapter reserves standard output for ACP and waits for a client; diagnostics go to standard error. Press Control-C to stop it. Replace gemini-fast with your admitted alias, and restart an existing daemon after changing its model or approval configuration.

Launch the harness

export BUZZ_PRIVATE_KEY='nsec1...'
export BUZZ_RELAY_URL='wss://buzz.example.com'

export BUZZ_ACP_AGENT_COMMAND='/absolute/path/to/kaya-acp'
export BUZZ_ACP_AGENT_ARGS='/absolute/path/to/job.yaml'
export BUZZ_ACP_MCP_COMMAND='/absolute/path/to/buzz-dev-mcp'

# Good for an initial wiring test. Tighten this after the agent responds.
export BUZZ_ACP_RESPOND_TO='anyone'

/absolute/path/to/buzz-acp

BUZZ_ACP_AGENT_ARGS is comma-separated, so avoid commas in the job path. Buzz passes the relay URL and agent private key directly to buzz-dev-mcp for that session. Do not copy them into job.yaml or the Kaya program.

Once the round trip works, use Buzz's owner-only or allowlist author gate instead of anyone. Add the agent only to channels it needs.

Prove the round trip

  1. Start buzz-acp and leave it running.
  2. In Buzz, mention the agent in a channel it can access.
  3. Watch the harness create an ACP session and Kaya reach input().
  4. Confirm the model calls buzz-dev-mcp__shell.
  5. Confirm the reply is a signed message from the agent's Nostr identity.

ACP assistant text is visible as agent activity, but it is not automatically a Buzz channel message. The agent must run the buzz messages send command from the current prompt. That explicit write is why every example repeats the publishing rule in its system message.

Troubleshooting

The session never starts. The Kaya program must reach its first input() within 30 seconds. Put setup work after that boundary.

The channel stays quiet. Check for an MCP tool call. If the model only returned prose, strengthen the publishing instruction in main.kaya.

buzz-dev-mcp__shell is missing. Verify BUZZ_ACP_MCP_COMMAND is an absolute, executable path. Do not set KAYA_DISABLE_CLIENT_MCP=true on the local daemon.

The agent ignores everyone. Buzz defaults to an owner gate. For the first test, set BUZZ_ACP_RESPOND_TO=anyone; then configure the intended owner or allowlist before leaving the harness running.

A long research turn is cancelled. Increase BUZZ_ACP_IDLE_TIMEOUT. The Buzz default is intended for ordinary agent turns; deep research may be quiet for several minutes.

Kaya reports an incompatible model. Inspect the structured diagnostic and the selected native model binding. This loop needs a model route compatible with the session's client-provided MCP tools; a provider key or installed coding-agent CLI alone does not configure that route. See Supported Models and ACP tools.

Authentication fails. Check BUZZ_PRIVATE_KEY, BUZZ_RELAY_URL, relay membership, and channel membership. Kaya deliberately does not persist the MCP credential environment.