runspec-registry

A lightweight HTTP registry for runspec agents.

When runspec serve starts on a host it registers itself here. The registry tracks which tools are available, on which hosts, and with what execution metadata. Clients (Chainlit apps, orchestrators, CI pipelines) query the registry to discover agents and route tool calls.

Install

pip install runspec-registry

Start the server

runspec-registry

Options:

--host TEXT            Bind host (default: 0.0.0.0)
--port INT             Bind port (default: 8765)
--api-key TEXT         API key required for write endpoints
--ssl-keyfile PATH     TLS private key
--ssl-certfile PATH    TLS certificate
--purge-interval INT   Seconds between stale-instance sweeps (default: 60)
--reload               Auto-reload for development

API

Instances

Discovery

Write endpoints require X-API-Key header when --api-key is set. Read endpoints are unauthenticated by default.

Authentication

Start with an API key to protect write endpoints:

runspec-registry --api-key mysecretkey

Agents register with the matching key:

runspec serve --registry http://myserver:8765 --registry-key mysecretkey

TLS

Provide a certificate and key to enable HTTPS:

runspec-registry --ssl-certfile cert.pem --ssl-keyfile key.pem

Agents connecting to a registry with a self-signed cert pass the CA cert:

runspec serve --registry https://myserver:8765 --registry-cert ca.pem

How it works

1. runspec serve starts on each host, reads runspec.toml, and registers with the registry
2. It sends a heartbeat every 30 seconds (configurable via heartbeat in runspec.toml)
3. The registry purges instances that have missed heartbeats
4. Clients query /tools to see what's available and on which hosts
5. runspec run --host <host> --registry <url> <tool> looks up the tool, gets the execution metadata for that host, and SSHes to run it

Links

• Documentation
• runspec on PyPI
• Source