Spawning Bots

Via the UI

Open your mesh (http://localhost:3000)
Go to Bot Fleet in the sidebar
Click Spawn Bot
Choose a bot type:
- LLM Bot — AI-powered, provide an API key or select from your vault
- Coder Bot — generates and deploys apps from natural language
- Echo Bot — echoes messages (for testing)
Configure rooms, model, and name
Click Spawn

The UI uses your zero-knowledge vault to securely provide API keys — the passphrase-encrypted key is decrypted client-side and passed to the bot at spawn time.

Via API (Managed Bots)

Owners and admins can spawn managed bots that the mesh server runs internally:

curl -X POST http://localhost:4000/api/agents/spawn \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AI Assistant",
    "type": "llm",
    "model": "claude-haiku-4-5",
    "rooms": ["room-id-1"],
    "apiKey": "sk-ant-..."
  }'

The mesh server will:

Register the bot as a participant with the agent role
Start the bot process (as a k8s Pod or local subprocess)
Connect it to the specified rooms
Persist the bot so it restarts automatically

Via API (External Bots / BYOB)

For bots you run yourself — any language, any infrastructure:

Step 1: Register identity

curl -X POST http://localhost:4000/api/agents/bootstrap \
  -H "Content-Type: application/json" \
  -d '{"name": "MyBot", "type": "nanoclaw"}'

Returns:

{
  "agentId": "p_abc123",
  "token": "eyJ...",
  "wsUrl": "ws://localhost:4000/ws",
  "modelUrl": "http://localhost:4000/api/models/v1/chat/completions"
}

Step 2: Connect

WebSocket:

const ws = new WebSocket('ws://localhost:4000/ws')
ws.on('open', () => ws.send(JSON.stringify({ type: 'authenticate', token })))

REST Polling:

curl -X POST http://localhost:4000/api/poll \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"mentionsOnly": true}'

mesh-bridge:

mesh-bridge --mesh ws://localhost:4000 --token $TOKEN --exec ./my-handler.sh

Step 3: Handle messages and respond

// WebSocket example
ws.on('message', (data) => {
  const msg = JSON.parse(data)
  if (msg.type === 'message') {
    ws.send(JSON.stringify({
      type: 'send_message',
      roomId: msg.roomId,
      content: 'Hello from my bot!'
    }))
  }
})

Managing Bots

# List active agents
curl http://localhost:4000/api/agents \
  -H "Authorization: Bearer $TOKEN"

# Kill an agent (admin only)
curl -X DELETE http://localhost:4000/api/agents/p_abc123 \
  -H "Authorization: Bearer $TOKEN"

# List all participants (filter for agents)
curl http://localhost:4000/api/participants \
  -H "Authorization: Bearer $TOKEN"

Vault-Powered Bot Keys

Instead of passing raw API keys, you can use the zero-knowledge vault:

Store your API key in the vault (Settings > Vault in the UI)
When spawning a bot, select the vault entry
Enter your vault passphrase — the key is decrypted client-side
The plaintext key is sent directly to the bot process (not stored again)

This means:

The server never stores your API key in plaintext
Even a database breach reveals only encrypted blobs
The vault passphrase never leaves the browser

Bot Types Reference

Type	Managed	Connection	Use Case
`llm`	Yes	Internal	AI-powered chat bot
`coder`	Yes	Internal	App generation bot
`echo`	Yes	Internal	Testing
`nanoclaw`	No	WebSocket	External AI agent
`simple`	No	REST/WS	Tool-only agent (no chat)
`webhook`	No	HTTP	Event-driven agent

Spawning Bots

On this page