inter-agent-core

inter-agent-core is the host-neutral Python runtime for a local authenticated message bus. It provides the WebSocket server, protocol, routing, channels, TLS, shared state, and generic command-line clients used by host integrations such as Pi, Claude Code, and OpenCode.

Requirements

• Python 3.10 or newer
• uv for the installation and development commands below

Install

Create an isolated environment and install the released 0.3.0 package:

uv venv .venv
source .venv/bin/activate
uv pip install inter-agent-core==0.3.0

The package installs the inter-agent-* command-line clients and the inter-agent Python API. On Windows, activate .venv with the equivalent PowerShell or Command Prompt command. Contributors working from a checkout should use the separate development procedure below instead of installing the registry package into that checkout’s environment.

Quick start

Start the bus in one terminal:

inter-agent-server

In a second terminal, connect a named client and leave it listening:

inter-agent-connect alice

In a third terminal, inspect the bus and send a direct message:

inter-agent-status
inter-agent-list
inter-agent-send alice "hello from the command line"

The alice terminal receives the message as a JSON protocol frame. Stop a foreground server with Ctrl-C. Use inter-agent-shutdown only when you intend to disconnect every client on that shared bus.

By default, local clients use 127.0.0.1:16837 and discover the same generated secret from the shared state directory. If you configure a different endpoint, data directory, or secret, use the same values for every client and server.

Persistent custom messages

A host integration with an established AgentSession can send a generic targeted custom envelope with send_custom(custom_type, payload, to). The method reuses that session's authenticated connection, routing identity, reader, inbox, and serialized command lock; it does not create another connection or accept a caller-supplied sender identity. to is a target routing name or an unambiguous target prefix, and payload is passed through for the receiving integration to interpret.

The method sends the custom frame followed by an ordered application-level ping barrier. A routing error observed before the matching pong is returned as an unsuccessful local result. submitted is true only after the barrier is observed without such an error: it means the server finished processing the preceding frame on that connection, not that a target received, accepted, or acted on the payload. The generic core does not define the custom type or payload schema.

If the barrier times out, the connection closes, or the operation is cancelled, the session fails closed before returning or propagating the failure. The late routing error and barrier cannot enter the ordinary inbound queue; a listener may establish a replacement session according to its own lifecycle. Custom envelopes and local bridge exchanges remain subject to the existing protocol, frame, and 64 KiB local-bridge limits.

Commands

Every command supports --help. Endpoint-aware commands also accept --host, --port, --tls or --no-tls, and TLS certificate overrides.

Use direct messages for normal coordination. Use broadcasts only when every connected session needs the message. Channels are in-memory groups owned by one server and disappear when that server stops.

Configuration and security

Configuration resolves in this order: command-line options, environment variables, the JSON configuration file, then built-in defaults. The main environment variables are:

• INTER_AGENT_HOST and INTER_AGENT_PORT — endpoint overrides;
• INTER_AGENT_SECRET — an explicit shared secret;
• INTER_AGENT_DATA_DIR — state, generated secret, and generated TLS material;
• INTER_AGENT_CONFIG — an alternate JSON configuration file;
• INTER_AGENT_TLS, INTER_AGENT_TLS_CERT, and INTER_AGENT_TLS_KEY — TLS settings.

Loopback endpoints default to plaintext ws://. Non-loopback endpoints default to TLS wss://; clients never downgrade a failed TLS connection automatically.

The default trust boundary is one trusted operating-system user on one machine. HMAC-SHA-256 authentication prevents clients without the shared secret from joining, and TLS protects network transport, but neither protects against hostile code running as the same user. Do not commit or share secrets, private keys, certificates, or state. See SECURITY.md and the detailed threat model.

For a common failure, run inter-agent-status first. If clients cannot authenticate, check that they resolve the same endpoint, state directory, and secret. Use a separate endpoint and data directory for tests or isolated buses rather than disturbing an existing one.

Reference and development

• spec/ — protocol definition, schemas, examples, and error codes
• ARCHITECTURE.md — runtime and extension boundaries
• CHANGELOG.md — released changes
• README.md#commands — generic CLI reference
• inter-agent-pi — Pi integration
• inter-agent-claude-code — Claude Code integration
• inter-agent-opencode — OpenCode integration

Host-specific commands, listeners, rendering, and tools belong in those extension repositories; this package supplies the shared runtime.

For development, clone the repository and run:

git clone https://github.com/arcanemachine/inter-agent-core.git
cd inter-agent-core
uv sync --locked
./run-checks.sh

License

MIT. See LICENSE.md.