open-agent-relay

OpenAgentRelay lets teammates or another Agent call something that is already running properly on your computer. The caller only needs to install a small relay CLI, and does not need this repository, the Agent source code, dependencies, prompts, or business credentials.

Purpose Turn any local Agent or automation into a team-callable capability. The publisher owns a working Agent or automation, and the caller interacts with it through the relay CLI. If you do not know how to use it, you can send the project link directly to Codex, Claude Code, or another Agent that can read web pages, tell it the role you need, and it can read the README, install the relay CLI without cloning the repository, and guide or complete the setup. Both publishers and callers can use the corresponding message templates; the access key should be provided through RELAY_ACCESS_KEY, not placed in the message body.

Main capabilities

• Callers can invoke capabilities without the publisher's repository or Agent implementation.
• Direct calls are stateless by default; Relay-managed sessions are supported to preserve context, and after a conversation_id is returned, the conversation can continue.
• Relay stores bounded text records in memory and injects them into new Agent executions; sessions expire after one hour by default and disappear after a server restart. The local Caller ID only prevents accidental cross-caller conversation continuation and is not an authenticated personal identity.
• When calling another Agent or automation, JSON should always be requested; on success there is JSON output.
• Operational CLI failures end with a non-zero exit code and write a JSON error to standard error.
• The public Agent Card is located at /.well-known/agent-card.json; browser users can also open the Relay URL and enter the access key.

Installation and usage Ordinary users do not need to clone the repository; install the CLI with pipx. If pipx is not installed, follow its one-time installation guide (the common path on macOS is brew install pipx). If you are already in a Python 3.11+ virtual environment, you can install it in the corresponding way. Cloning the repository is only for development; released versions are on PyPI.

End-to-end examples The examples/ directory contains three reusable paths: a zero-dependency read-only report based on local CSV data; a temporary Codex review in a dedicated read-only workspace; and a Claude Code review using non-interactive plan mode and blocking write and Web tools. Start with the local report to verify networking and authentication before connecting the Agent.

Publisher: sharing capabilities

1. Start with a safe test: choose an access key of at least 16 characters and do not put it in shell history; start a harmless test capability. A successful start will confirm that the configured key has been loaded and print Serving uppercase on http://0.0.0.0:8787。若未配置密钥，Relay A temporary key will be generated and printed. Verify the service on the publisher's computer; the expected response is {"status":"ok"}.
2. Share connection information: find the publisher's LAN address. On macOS the common command is ipconfig getifaddr en0, and on Linux it is hostname -I. Send the exact connection value through a trusted channel. 0.0.0.0 is the listening address, not the address the caller should use; the firewall may also need to allow inbound TCP traffic on port 8787.
3. Publish an existing command: Relay starts the command once per request. The command must read one request from standard input, write the final answer to standard output, write logs and diagnostics to standard error, and exit when that request ends.
4. Publish a restricted Codex capability: use a dedicated workspace and the minimum credentials required for this capability. Do not expose the everyday Codex environment containing all personal files, MCP servers, Skills, and tokens. Each request typically starts a new codex exec; Codex can use what is available in that restricted workspace, but Relay will not automatically restore the publisher's historical Codex session.

Caller: invoke the capability The caller only needs the relay CLI and the connection information, not the publisher's repository or Agent implementation. Load the shared key without putting it into command history. When executing directly; when invoking another Agent or automation, always request JSON. On success there is JSON output. Direct invocation is stateless by default; when follow-up questions need prior context, start a Relay-managed session, save the returned conversation_id, and continue.

Hand the capability to another Agent Configure RELAY_ACCESS_KEY in the caller Agent environment, then give it the connection block. The Agent needs the CLI and the connection block, not the OpenAgentRelay repository.

Security boundary

• Bearer authentication uses one shared key; it does not identify individual teammates.
• Transport is plain HTTP. Anyone who can observe LAN traffic may see the key, input, and output.
• --expect-agent prevents misconfiguration, but cannot cryptographically prove the server's identity.
• Caller input is untrusted. A capable Agent may read files, call tools, or disclose data accessible to its process.
• Use a dedicated workspace, read-only tools, minimum credentials, and a narrowly described scopecapability.
• Do not expose the port to the public internet or connect it to production write operations.
• Read SECURITY.md before serving a real Agent.

Limitations and current scope relay serve --help exposes execution timeout, request size, output size, concurrency, and session expiration controls. Version 0.1 does not include TLS, per-user permissions, automatic discovery, file transfer, progress streaming, persistent sessions, multiple Agents behind one address, or a sandbox provided by Relay. The asynchronous Hub + Runner experiment is still on the hub-mode branch and is not part of the current direct-mode Alpha path. For source development, see CONTRIBUTING.md. Licensed under Apache-2.0.