OctoBus

What OctoBus is

OctoBus is a locally running, single binary gateway from Chaitin for managing pluggable Node.js service packages and exposing the gRPC capabilities inside those packages to clients or agents through a capset. The README describes the current implementation as a Go built octobus binary that handles several duties. A daemon starts the local control plane and the public data plane and manages Node.js subprocesses according to each service runtime mode. A CLI manages services, instances, and capsets through the local admin API. A gateway exposes selected methods as gRPC and also exposes unary methods as Connect RPC and MCP streamable HTTP. A storage layer uses SQLite to record services, instances, capsets, method bindings, descriptors, and runtime state, and a runtime management piece imports service packages, prepares runtime directories, and manages long running or on demand Node.js instances. The core model centers on four ideas. A service is a service root inside an importable Node.js package that contains service.json, proto files, and a gRPC implementation. An instance is one runtime of a service with its own config and workdir. A capset is a deterministic set of capabilities for an agent or use case, built from capset to service to instance to method bindings. A method binding is the gRPC method that is selected and exposed in a capset. The README frames OctoBus as infrastructure for controlled, auditable service access rather than a general purpose proxy.

Running and exposing services

The README documents several ways to run the daemon. OctoBus is published as the npm package @chaitin-ai/octobus, which installs a small Node.js launcher and pulls the matching native Go binary through platform specific optional dependencies, so a user can install it globally or run it with npx. A Docker image bundles the binary and the runtime dependencies, and it listens on 0.0.0.0:9000 by default while storing state under /var/lib/octobus. A checkout can be built with a task command and started with the serve subcommand, and the data directory, address, and other defaults can be set through flags or environment variables. By default the daemon listens on 127.0.0.1:9000, and the admin API, gRPC, Connect RPC, MCP, and reflection are all dispatched through that one port. The README warns that when exposing OctoBus remotely with a different bind address, the operator is responsible for network access control. Service packages default to the long running runtime mode, which launches a resident Node.js gRPC subprocess, while a package can declare an on demand mode that starts a short lived invoke subprocess per request. The data directory holds the SQLite database, service artifacts, runtime directories, instance config, and logs, and the default is a .octobus folder under the working directory. Normal service import still requires node, npm, protoc, and git on the host.

Capabilities, tokens, and access logs

The README explains how capsets expose methods and how access is controlled. When no token has been added to a capset, its Connect RPC, MCP, gRPC, reflection, and public OpenAPI endpoints remain publicly accessible, which the README states plainly as the default. After one or more tokens are added, those resources require valid credentials: the HTTP based protocols use an Authorization Bearer header and gRPC and reflection use the same name in metadata. Token secrets are submitted only at creation time, and OctoBus persists validation hashes rather than plaintext tokens. The catalog command returns each method by protocol, including runtime mode, backend state, gRPC metadata, Connect RPC endpoint, MCP tool name, descriptor hash and version, and request and response message names, with query parameters to select gRPC, connect, MCP, or all. The gRPC gateway supports unary, server streaming, client streaming, and bidirectional streaming for long running services, while on demand services only support unary invoke. Public protocol access for capsets is written to an access log under the data directory as NDJSON with restricted permissions; the README notes it records protocol, capset, service, instance, method, route, status, duration, remote address, and user agent, but not request bodies, responses, authorization, tokens, secrets, or business metadata. This logging gives operators a record of what was called without exposing sensitive material. The project is licensed under GPL 3.0 and carries a security feedback policy.

Editorial conclusion

OctoBus is published under the GPL 3.0 license and its most recent commit was on 2026-08-26.