Headless Bob

IBM Bob was built for the IDE — but engineering work doesn't stop at the developer's desk. The Headless Bob building block is the pattern for running Bob outside the IDE: in CI/CD pipelines, automation scripts, Slack workflows, and any system that needs to call Bob programmatically without a developer actively present.

The reference implementation is headlessbob — a TypeScript/Node.js service that runs IBM Bob Shell 2.0.4 and exposes it through native Agent Communication Protocol (ACP) 0.2.0, thread-based REST APIs, and MCP (Streamable HTTP) — all on the same port, with an integrated browser UI. All three interfaces communicate with Bob Shell internally via IBM's Agent Client Protocol, the officially supported programmatic interface to Bob.

Why This Matters

• Not all engineering work happens interactively. Code reviews, test generation, documentation sync, dependency audits, and deployment validations are repeatable tasks that should run automatically — not wait for a developer to open an IDE. Headless Bob makes these tasks a first-class engineering concern.
• Bob needs an API boundary for automation. Teams integrating Bob into CI pipelines, scheduled jobs, or multi-system workflows need a stable REST surface to call — headlessbob provides that boundary, wrapping Bob Shell in a managed, authenticated API without requiring changes to Bob itself.
• Multi-agent interoperability requires a standard protocol. ACP 0.2.0 lets any ACP-compatible agent or pipeline discover Bob, submit tasks, and consume results in a standardized way — making Headless Bob a first-class node in multi-agent architectures.
• AI calls are asynchronous by nature. Bob runs can take seconds to minutes depending on task complexity. Headless execution requires a queue-and-poll model — or live streaming — so systems can submit work and retrieve results without holding connections or blocking pipelines.
• Persistent conversations enable multi-turn workflows. Thread-based sessions carry workspace context across runs, letting Bob build on previous work — essential for iterative tasks like code generation, refactoring, and incremental deployments.
• Visibility into cost and execution matters at scale. headlessbob captures token counts, execution duration, and tool call metrics per run — giving teams the observability they need to govern autonomous Bob usage. Note: Bob Shell 2.0.4's acp command does not expose cost/turn limit controls; cost and turn limits are legacy CLI settings only and are reported as null by /api/v1/capabilities.

What's Covered

Area	What It Covers
How headlessbob Works	Architecture: REST, ACP, and MCP interfaces, run manager, SQLite, workspace model, browser UI
Interaction Modes	Sync, async, and stream execution modes via ACP and REST
Browser UI	Built-in chat interface with live streaming, file explorer, and run diagnostics
REST API Reference	Full /api/v1 endpoint surface for threads, runs, and files
ACP API Reference	ACP 0.2.0 endpoints for agent discovery, runs, sessions, and events
MCP API Reference	MCP Streamable HTTP endpoint, tools, and client usage
Deployment	Local (Node.js), Docker, and OpenShift setup
Client Examples	Python standard-library clients for REST, ACP, MCP, and cancellation
Use Cases	CI/CD integration, Slack automation, multi-agent orchestration
Bob Skills & Modes	AI-assisted workflows for configuring headless pipelines from your IDE

---

How headlessbob Works

headlessbob sits between any API client and Bob Shell. Clients authenticate with a bearer token, submit work via REST, ACP, or MCP, and receive results synchronously, asynchronously, or via live SSE streaming. Bob Shell runs in an isolated workspace directory per session, with all generated artifacts available for download.

%%{init: {'theme': 'base', 'themeVariables': {'background': '#ffffff', 'primaryColor': '#ffffff', 'clusterBkg': '#f4f6fb', 'clusterBorder': '#c5cde0', 'titleColor': '#1a1a2e', 'fontSize': '14px'}}}%%
flowchart LR
    subgraph Clients["Clients"]
        UI[Browser UI]
        Client[API Client]
        Agent[ACP Client]
        MCPClient[MCP Client]
    end

    subgraph Service["headlessbob"]
        REST[REST API /api/v1]
        ACP[ACP API /agents /runs]
        MCP[MCP /mcp Streamable HTTP]
        Manager[Run Manager]
    end

    subgraph Backend["Storage & Engine"]
        Protocol[Agent Client Protocol]
        Bob[Bob Shell Subprocess]
        Store[(SQLite & Workspaces)]
    end

    UI --> REST
    Client --> REST
    Agent --> ACP
    MCPClient --> MCP
    REST --> Manager
    ACP --> Manager
    MCP --> Manager
    Manager --> Protocol
    Protocol --> Bob
    Manager --> Store

    classDef client  fill:#ffffff,color:#1a1a2e,stroke:#c5cde0,stroke-width:1.5px
    classDef api     fill:#0f3460,color:#ffffff,stroke:#0f3460,stroke-width:1.5px,font-weight:600
    classDef manager fill:#16213e,color:#ffffff,stroke:#16213e,stroke-width:1.5px,font-weight:600
    classDef runtime fill:#1a1a2e,color:#e8eaf6,stroke:#3949ab,stroke-width:1.5px
    classDef bob     fill:#0f3460,color:#ffffff,stroke:#3949ab,stroke-width:2px,font-weight:600
    classDef store   fill:#f4f6fb,color:#1a1a2e,stroke:#c5cde0,stroke-width:1.5px

    class UI,Client,Agent,MCPClient client
    class REST,ACP,MCP api
    class Manager manager
    class Protocol runtime
    class Bob bob
    class Store store

Key design decisions:

• TypeScript/Node.js runtime — headlessbob is a Node.js 22.22+ service. Bob Shell 2.0.4 runs as a managed subprocess within it.
• Agent Client Protocol connector — all three interfaces (REST, ACP, and MCP) share a single BobClientRuntime that communicates with Bob Shell over Agent Client Protocol v1 (bob acp) via stdio. The old BobRuntime (bob run) is retained for legacy compatibility only.
• Triple protocol surface — ACP 0.2.0 endpoints (/agents, /runs, /session) for agent interoperability; thread-based REST (/api/v1) for direct integration and the browser UI; and MCP (/mcp, Streamable HTTP) for any MCP-compatible client or agent framework. All three share the same run manager, workspace layer, and Agent Client Protocol connector.
• Workspace isolation — every session gets its own UUID workspace directory under DATA_DIR/workspaces. Bob's internal history lives under $HOME/.bob.
• SQLite persistence — run metadata, session ownership, task mappings, and ordered events are stored in DATA_DIR/runs.sqlite. Conversations survive service restarts.
• Bearer token auth — all endpoints require Authorization: Bearer <TOKEN>. Tokens are configured in AUTH_TOKENS in .env. No external IdP required.
• Bounded resource usage — concurrency, queue depth, timeouts, and output buffer sizes are all configurable and strictly enforced. Cost and turn limits apply only to the legacy CLI runtime; the default Agent Client Protocol runtime does not enforce them and reports them as null.

---

Interaction Modes

headlessbob exposes Bob through three execution modes, available via both ACP and REST interfaces.

Mode	What It Is	Use When
⚡ Sync	Submit a task and wait — the HTTP response returns only after Bob completes. Returns full output and usage metrics in one response	Short tasks where the caller can hold the connection; simple integrations that don't need polling logic
📡 Stream	Submit a task and receive live output via Server-Sent Events (SSE). Text chunks and lifecycle events arrive in real time	Interactive integrations, browser UIs, Slack bots — any context where live feedback matters
🔄 Async	Submit a task and receive a run_id immediately (HTTP 202). Poll /runs/{run_id} for status, or consume /runs/{run_id}/events for SSE replay	CI/CD pipelines, scheduled jobs, long-running tasks — any system that cannot hold an HTTP connection

Multi-turn session continuation — pass the session_id returned from any run back into a new run request. Bob resumes in the same workspace, retaining all generated files and context from previous turns.

---

Integrated Browser UI

Open your deployment URL (or http://127.0.0.1:8000 locally). The root page serves an interactive chat interface — no separate frontend deployment needed.

Connect using your service token (the owner key in AUTH_TOKENS). The token is held only in browser session memory — reloading or clicking Disconnect clears it.

UI Features

Feature	Description
Conversation Management	Create, rename, search, archive/restore, and delete threads
Live Output Streaming	Real-time message streaming with sanitized Markdown rendering — headings, tables, syntax-highlighted code blocks
Execution Controls	Real-time Cancel run button to terminate active or queued runs immediately
Workspace File Explorer	Right-hand panel to browse all files generated by Bob in the workspace — download any file with one click
Run Diagnostics & Cost	Inspect full run JSON, tool calls, execution duration, and token/cost statistics reported by Bob Shell
Integrated API Docs	One-click modal linking to interactive OpenAPI specifications (/api/openapi.json, /acp/openapi.json) and downloadable Python samples

---

REST API Reference

All REST endpoints require Authorization: Bearer <TOKEN> and return structured JSON. Send an Idempotency-Key header when posting messages to safely retry without duplicate executions.

Capabilities & Health

Method	Path	Description
GET	/api/v1/capabilities	Caller identity, readiness, features, and operational limits
GET	/ping, /healthz	Unauthenticated liveness probes
GET	/readyz	Authenticated Bob executable/version/key readiness check

Threads

Method	Path	Description
POST	/api/v1/threads	Create a thread — {} or {"title":"Project Name"}
GET	/api/v1/threads	List/search threads (q, archived, limit, cursor)
GET	/api/v1/threads/{id}	Retrieve thread metadata and status
PATCH	/api/v1/threads/{id}	Update title and/or archived state
DELETE	/api/v1/threads/{id}	Delete thread conversation records (returns 204)
POST	/api/v1/threads/{id}/messages	Send {"content":"Your prompt"} — returns 202 with run ID and events URL
GET	/api/v1/threads/{id}/messages	Read conversation turns (limit, before)

Runs

Method	Path	Description
GET	/api/v1/runs/{id}	Check run status, output, errors, and usage metrics
GET	/api/v1/runs/{id}/events	Live SSE stream with replay cursor support (?after= or Last-Event-ID)
POST	/api/v1/runs/{id}/cancel	Request cancellation of an active run

Workspace Files

Method	Path	Description
GET	/api/v1/threads/{id}/files	List files generated in the thread's workspace (?path=folder)
GET	/api/v1/threads/{id}/files/{path}	Download a workspace file as a binary attachment

---

ACP API Reference

headlessbob natively implements the text subset of ACP 0.2.0. ACP endpoints live at root routes and do not carry the /api/v1 prefix. OpenAPI spec available at /acp/openapi.json.

For full protocol details, see the IBM Bob ACP Documentation.

Agent Discovery

Method	Path	Description
GET	/agents	Agent discovery — lists available agents
GET	/agents/headlessbob	Detailed agent capability manifest

Runs

Method	Path	Description
POST	/runs	Create a run — mode: "sync", "async", or "stream"
GET	/runs/{run_id}	Poll run status, output text, and usage metrics
GET	/runs/{run_id}/events	Fetch stored ACP JSON events in execution sequence
POST	/runs/{run_id}/cancel	Cancel an in-flight ACP run (returns HTTP 202)

Sessions

Method	Path	Description
GET	/session/{session_id}	Retrieve session workspace ID and run history URNs

ACP Run Modes — Quick Reference

Synchronous — waits for full completion:

curl -s -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "$BASE/runs" -d '{
    "agent_name": "headlessbob",
    "input": [{"role": "user", "parts": [{"content_type": "text/plain", "content": "Create a file named hello.txt with content Hello World"}]}],
    "mode": "sync"
  }' | jq .

Streaming — live SSE output:

curl -N -s -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "$BASE/runs" -d '{
    "agent_name": "headlessbob",
    "input": [{"role": "user", "parts": [{"content_type": "text/plain", "content": "Write a Python script that computes Fibonacci numbers."}]}],
    "mode": "stream"
  }'

Asynchronous — fire-and-poll:

# Start async run
RUN_RESP=$(curl -s -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "$BASE/runs" -d '{
    "agent_name": "headlessbob",
    "input": [{"role": "user", "parts": [{"content_type": "text/plain", "content": "Analyze project files"}]}],
    "mode": "async"
  }')
RUN_ID=$(echo $RUN_RESP | jq -r .run_id)
SESSION_ID=$(echo $RUN_RESP | jq -r .session_id)

# Poll status
curl -s -H "Authorization: Bearer $TOKEN" "$BASE/runs/$RUN_ID" | jq .

# Fetch all recorded events
curl -s -H "Authorization: Bearer $TOKEN" "$BASE/runs/$RUN_ID/events" | jq .

Multi-turn session continuation — pass session_id to resume in the same workspace:

curl -s -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "$BASE/runs" -d "{
    \"agent_name\": \"headlessbob\",
    \"session_id\": \"$SESSION_ID\",
    \"input\": [{\"role\": \"user\", \"parts\": [{\"content_type\": \"text/plain\", \"content\": \"Now add unit tests for the code generated earlier.\"}]}],
    \"mode\": \"sync\"
  }" | jq .

---

MCP API Reference

headlessbob exposes Bob Shell to any MCP-compatible client or agent framework via a Streamable HTTP endpoint at /mcp. The transport is stateless — each call is a standard JSON-RPC 2.0 POST with no session handshake or persistent connection required. Bob's conversation and workspace state persists independently in SQLite.

Authentication: Authorization: Bearer <service-token> (same AUTH_TOKENS token as REST/ACP — not the BOB_API_KEY). Browser Origin requests are rejected on this endpoint.

MCP Tools

Tool	Arguments	Returns
bob_create_thread	title (optional string)	Thread object including id
bob_send_message	thread_id (UUID), content (string), request_id (string)	Thread, run, and message ID
bob_get_run	run_id (UUID)	Run status, completed output, and reported usage
bob_cancel_run	run_id (UUID)	Current cancellation / run status

Typical flow: call bob_create_thread → bob_send_message → poll bob_get_run every few seconds until status is completed, failed, or cancelled. Save the thread ID for follow-up turns. Threads created via MCP are visible in the browser UI for the same caller.

request_id idempotency: use a unique value per intended message (1–128 alphanumeric characters, dots, underscores, colons, or hyphens). On retry, reuse the same request_id with the same thread and content to retrieve the original run without re-executing. Reusing it with different content returns a tool error.

Disconnecting does not cancel a run

Closing an MCP client connection does not stop the server-side Bob run. Use bob_cancel_run explicitly if you need to stop an active run.

MCP Quick Reference

TypeScript SDK client:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const client = new Client({ name: 'bob-client', version: '1.0.0' });
await client.connect(new StreamableHTTPClientTransport(
  new URL('/mcp', process.env.HEADLESSBOB_URL),
  { requestInit: { headers: { Authorization: `Bearer ${process.env.HEADLESSBOB_TOKEN}` } } }
));

// Create a thread and start a run
const thread = await client.callTool({ name: 'bob_create_thread', arguments: { title: 'Demo' } });
const started = await client.callTool({
  name: 'bob_send_message',
  arguments: {
    thread_id: thread.structuredContent.id,
    content: 'Create hello.txt containing hello.',
    request_id: 'demo-1'
  }
});
const runId = started.structuredContent.run.run_id;

// Poll until complete (Bob run continues after client.close())
await client.close();

MCP integration test:

npx tsx --test tests/mcp.test.ts   # verifies auth, ownership, retries, continuation, cancellation — no Bob credit consumed

---

Deployment

Prerequisites

• Node.js 22.22 or newer
• Licensed IBM Bob Shell 2.0.4 binary on your PATH (run sh scripts/download-bob.sh to download and verify)
• BOB_API_KEY configured with valid credentials

Key Configuration

Variable	Default	Description
BOB_API_KEY	—	Required. Bob Shell authentication key
AUTH_TOKENS	—	Required. Bearer tokens for service access (JSON object — owner key is the UI token)
DATA_DIR	.headlessbob	Root for SQLite database and all Bob run workspaces
BOB_MODE	agent	Bob agent mode passed to the runtime
BOB_ENABLE_CONTINUATION	false	Set to true to enable multi-turn session continuation across runs
MAX_CONCURRENT	2	Maximum concurrent Bob runs
MAX_QUEUED	100	Maximum queued tasks
RUN_TIMEOUT_MS	300000	Maximum runtime per Bob job (milliseconds)
MAX_OUTPUT_BYTES	2097152	Maximum combined stdout/stderr bytes per run (2 MiB)
MAX_BODY_BYTES	65536	Maximum incoming HTTP request body size (64 KiB)
MAX_EVENTS	10000	Maximum protocol events stored per run
BOB_MAX_TURNS	20	⚠ Legacy CLI runtime only. Maximum conversation turns per run. Not enforced by the default Agent Client Protocol runtime; reported as null by /api/v1/capabilities
BOB_MAX_COST	1.00	⚠ Legacy CLI runtime only. Maximum Bob cost (USD) per run. Not enforced by the default Agent Client Protocol runtime; reported as null by /api/v1/capabilities
KILL_GRACE_MS	2000	Grace period (ms) between SIGTERM and SIGKILL for subprocess cleanup

Local (Node.js)

cd assets/headlessbob
npm ci
cp .env.example .env
# Edit .env: set BOB_API_KEY and AUTH_TOKENS
npm run build
npm start

Access the UI at http://127.0.0.1:8000. Connect using your owner service token.

Run the test suite:

npm run check              # TypeScript type-check, fixture/HTTP unit and contract tests (no API key required)
npm run smoke              # End-to-end smoke test via legacy Bob runtime (consumes small credit)
npm run smoke:client-bridge  # End-to-end smoke test via Agent Client Protocol bridge (consumes small credit)
npx tsx --test tests/mcp.test.ts  # MCP SDK integration tests — auth, ownership, retries, continuation, cancellation (no Bob credit)

Docker

The container image uses Node.js 24. Run sh scripts/download-bob.sh inside assets/headlessbob to download and verify the Bob Shell 2.0.4 binary before building.

cd assets/headlessbob
sh scripts/download-bob.sh   # downloads and SHA-256 verifies vendor/bobshell-2.0.4.tgz
docker build -t headlessbob .
docker run -d -p 8000:8000 \
  -e BOB_API_KEY="your-key" \
  -e AUTH_TOKENS='{"owner":"your-service-token"}' \
  headlessbob

OpenShift

OpenShift manifests are in assets/headlessbob/openshift/:

# Download and verify the Bob Shell 2.0.4 binary
sh scripts/download-bob.sh

# Deploy BuildConfig and ImageStream
oc apply -n binb -f openshift/build.yaml

# Build image from local archive (including vendor Bob binary)
tar -czf /tmp/headlessbob-build.tgz Dockerfile package.json package-lock.json \
  tsconfig.json src browser spec public examples scripts/container-entrypoint.sh vendor/bobshell-2.0.4.tgz
oc start-build headlessbob -n binb --from-archive=/tmp/headlessbob-build.tgz --follow

# Generate Secrets/ConfigMap from local .env and deploy
node --env-file=.env scripts/configure-cluster.mjs
oc apply -n binb -f openshift/app.yaml
oc rollout status deployment/headlessbob -n binb

---

Client Examples

Ready-to-use Python clients using only Python's standard library are in assets/headlessbob/examples/python/. Set environment variables first (use your service access token, not the Bob API key):

export HEADLESSBOB_URL="http://127.0.0.1:8000"
export HEADLESSBOB_TOKEN="your-service-token"

ACP — agent discovery, runs, and multi-turn continuation (acp.py):

# Default: async run (submits and polls)
python3 examples/python/acp.py "Say hello in one sentence."

# Live streaming output
python3 examples/python/acp.py --mode stream "Generate a quick HTTP server in Go"

# Continue a previous session in the same workspace
python3 examples/python/acp.py --session "<SESSION_ID>" "Add a health check endpoint to that server"

REST — threads, live output, and file downloads (rest.py):

# Create a thread, send a task, stream output, and download a generated file
python3 examples/python/rest.py "Create hello.txt containing Hello from Python." \
  --download hello.txt --output hello.txt

# Continue an existing thread
python3 examples/python/rest.py "Explain the file you created." --thread <THREAD_ID>

MCP — drive Bob over Model Context Protocol (mcp.py):

# Run a prompt and print Bob's response
python3 examples/python/mcp.py "Create hello.txt containing Hello from MCP."

# Follow up in the same thread
python3 examples/python/mcp.py "What did you just create?" --thread <THREAD_ID>

# Retry the same send safely (reuse the same --request-id)
python3 examples/python/mcp.py "Create hello.txt containing Hello from MCP." \
  --thread <THREAD_ID> --request-id my-unique-key-1

# Cancel an active run
python3 examples/python/mcp.py --cancel <RUN_ID>

Cancel an active run (cancel.py):

# Cancel via REST or ACP using a printed run ID
python3 examples/python/cancel.py <RUN_ID> --api rest
python3 examples/python/cancel.py <RUN_ID> --api acp

Interactive CLI test tool:

npm run client -- /agents
npm run client -- /runs examples/run.json

Example	Description
acp.py	Agent discovery, ACP runs (async/stream/sync), multi-turn session continuation
rest.py	Create threads, send tasks, stream live output, download generated workspace files
mcp.py	Drive Bob over MCP (Streamable HTTP); create threads, send messages, poll for completion, cancel runs
cancel.py	Cancel an active run by ID via REST or ACP; waits for terminal status
client.py	Shared HTTP helpers (request, api, events, wait_run) used by the other examples — not a standalone script

---

Operational Limits & Trust Model

Limit	Default	Environment Variable
Concurrent runs	2	MAX_CONCURRENT
Queued tasks	100	MAX_QUEUED
Job timeout	300,000 ms	RUN_TIMEOUT_MS
stdout/stderr buffer	2 MiB	MAX_OUTPUT_BYTES
Request body size	64 KiB	MAX_BODY_BYTES
Events per run	10,000	MAX_EVENTS
Max turns per run ⚠	20 (legacy only)	BOB_MAX_TURNS
Bob cost limit ⚠	$1.00 (legacy only)	BOB_MAX_COST

⚠ Cost and turn limits apply only to the legacy BobRuntime (bob run). The default Agent Client Protocol runtime (BobClientRuntime, bob acp) does not enforce them; /api/v1/capabilities reports these as null.

Trust boundary: headlessbob is intended for deployment within trusted environments. Bob Shell executes code and terminal commands on the host or container. Workspace token checks prevent caller crossover between sessions, but the service does not provide an OS sandbox between mutually untrusted actors.

Process cleanup: Subprocesses are spawned in their own process groups and cleaned up with SIGTERM followed by SIGKILL escalation after KILL_GRACE_MS.

Storage: SQLite stores run metadata, session ownership, task mappings, and ordered events. Bob workspaces are UUID directories under DATA_DIR/workspaces. Bob's internal history database lives under $HOME/.bob.

---

Use Cases

Use Case	What Headless Bob Does
CI/CD Pipeline Integration	A GitHub Actions or Tekton pipeline POSTs a prompt to /api/v1/threads/{id}/messages after a PR is merged — Bob runs code review, generates test stubs, or updates documentation autonomously. The pipeline polls the run for completion and downloads generated artifacts
Scheduled Engineering Tasks	A cron job triggers nightly: Bob audits dependencies, generates a summary report, and posts it to Slack — without a developer touching anything
Slack-Driven Workflows	Developers use /bob <prompt> in Slack — headlessbob handles the slash command, runs Bob asynchronously, and posts the result back via response_url. No IDE required
Multi-Agent Orchestration	An orchestrating agent (Claude, watsonx, LangGraph) calls Bob via ACP 0.2.0 as a specialist node — Bob handles coding and engineering tasks while the orchestrator handles routing, memory, and business logic
Multi-Turn Engineering Sessions	A project intake tool creates an ACP session — Bob builds iteratively across multiple prompts in the same workspace, generating files that reference and extend each other across turns
Automated Code Generation Pipelines	A pipeline seeds a workspace with existing source files, then invokes Bob across multiple async runs to generate tests, documentation, and refactored code — each run building on the last via session_id continuation

---

GitHub Repository

headlessbob — Headless Bob Reference Implementation

ACP Protocol Reference

For full IBM Bob ACP 0.2.0 protocol capabilities, see the IBM Bob ACP Documentation. OpenAPI specifications are available at /api/openapi.json (REST) and /acp/openapi.json (ACP) on any running headlessbob instance.