OctoBus Local Agent Gateway

What does this agent do, and when should you use it?

OctoBus is a locally running, single-binary gateway (a Go-built `octobus` program) for managing pluggable Node.js service packages and exposing their gRPC capabilities to clients or agents by capset. The daemon listens on `127.0.0.1:9000` by default, multiplexing the local admin API, gRPC, Connect RPC, MCP streamable HTTP, and gRPC reflection through that one port. Its core model has four layers: service (a Node.js package root with service., protos, and a gRPC implementation), instance (a runtime copy with independent config and workdir), capset (a deterministic capability set scoped to an agent or use case), and method binding (the gRPC methods actually exposed within a capset). Service packages default to a long-running mode supervised as resident Node.js gRPC subprocesses, or can declare on-demand mode to spawn a short-lived `invoke` subprocess per request. State is stored in SQLite, and access logs are written as NDJSON to a 0600-permission access.log that excludes request bodies, secrets, and business metadata. The project is GPL-3.0 licensed and deployable via npm, Docker, or source build.

The OctoBus daemon starts a local control plane and data plane, and the octobus CLI manages services, instances, and capsets via the local admin API. On service import (octobus service import calculator ./examples/calculator-js), it fetches and unpacks npm/local-directory/Git/HTTP-archive sources, compiles proto descriptors with protoc, and prepares runtime directories; sources support a //service-dir suffix to select a service root inside a package, and --recursive imports all discovered service roots. After instance create, long-running instances launch resident Node.js gRPC subprocesses with health checks, while on-demand instances spawn a one-shot invoke subprocess per request exchanging protobuf wire format over stdin/stdout. Once a capset is created and an instance attached via capset add-instance, methods are callable over three protocols: gRPC (original method paths, routed via x-octobus-capset/x-octobus-instance metadata, all four streaming kinds), Connect RPC (POST /capsets/{id}/connect/{instance}/{service}/{method}, unary only), and MCP streamable HTTP (POST /capsets/{capset_id}/mcp, default tool names {service}__{instance}__{method}). Capsets manage access tokens via add-token (only validation hashes persisted, never plaintext); without tokens the endpoints are publicly accessible. The companion @chaitin-ai/octobus-sdk handles the --runtime serve/invoke/dev protocol via runServiceMain, OpenAPI endpoints expose per-method schemas, and octobus logs filters access logs by capset/instance/service.

1. Platform engineers who need internal AI agents to call APIs like GitLab without handing agents raw system credentials — capsets plus tokens authorize method subsets per agent
2. Teams with existing Node.js internal tooling that want a unified gRPC/Connect/MCP interface for diverse clients — wrap the tools as OctoBus service packages and import them
3. Developers providing a controlled toolset to MCP clients locally — integrate through the POST /capsets/{id}/mcp streamable HTTP endpoint
4. Security teams requiring audit trails for agent tool calls — access.log records protocol, capset, method, status, duration in NDJSON without sensitive data
5. Operators who want infrequent tools to consume no resident resources — declare packages in on-demand mode and spawn one-shot processes per request
6. Scenarios needing differently-scoped tool catalogs per agent — use select-method per capset for precise method-level exposure control

What are this agent's strengths and limitations?

How do you install or deploy this agent?

Three options:

1. npm (the main package installs a small Node.js launcher and pulls the matching native Go binary via platform-specific optional dependencies):

bash

npm install -g @chaitin-ai/octobus
octobus serve

Or without a global install: npx @chaitin-ai/octobus serve

1. Docker:

bash

docker run --rm \
-p 9000:9000 \
-v octobus-data:/var/lib/octobus \
ghcr.io/chaitin/octobus:latest

The container listens on 0.0.0.0:9000 and stores state under /var/lib/octobus.

1. Build from a checkout (requires Go 1.26.1 and Task):

bash

task build
./bin/octobus serve --data-dir .octobus --addr 127.0.0.1:9000

Normal service import and instance startup also require node, npm, protoc, and git on PATH. Defaults can be overridden via OCTOBUS_DATA_DIR and OCTOBUS_ADDR environment variables.

How do you use this agent?

1. Start the daemon and verify CLI connectivity: ./bin/octobus status.
2. Import the example package: ./bin/octobus service import calculator ./examples/calculator-js (sources support local directories, tgz/tar.gz/zip archives, npm:, and HTTPS Git; append //service-dir to pick a service root).
3. Create and start an instance:

bash

./bin/octobus instance create calculator-test \
--service calculator \
--config- '{"label":"primary"}' \
--secret- '{"apiToken":"dev-token"}'

1. Create a capset and attach the instance:

bash

./bin/octobus capset create dev --name DevAgent
./bin/octobus capset add-instance dev calculator-test
./bin/octobus catalog dev --all --

1. Invoke (Connect RPC example):

bash

curl -X POST \
http://127.0.0.1:9000/capsets/dev/connect/calculator-test/calculator.v1.CalculatorService/Add \
-H 'Content-Type: application/' \
-d '{"left":20,"right":22}'

MCP: POST /capsets/dev/mcp with JSON-RPC tools/list / tools/call. gRPC via grpcurl with x-octobus-capset/x-octobus-instance metadata. Optional: capset add-token dev local --token-stdin to enable Bearer auth (gRPC/reflection use identically named metadata); octobus logs --follow to stream access logs.

How does this agent compare with similar options?

FAQ