Runtime Adapter · FastAPI + Hermes

Hermes Runtime Bridge

NebulaiOS gives external Hermes agents a governed way to accept scoped work, use only advertised capabilities, and report signed evidence back for founder review.

2 hopsdelegation limit
8task MCP tools
120sfreshness window
0production deletes
01
1Register
LIVE
Advertise Runtime
Capability
A Hermes runtime first tells NebulaiOS who it is, what tenant it serves, and which operations it can safely perform.
Endpoint handshake
📡
Registers a runtime endpoint
The tenant runtime posts its agent id, endpoint URL, runtime slug, auth reference, capabilities, and tool descriptors to `/api/v1/runtime-endpoints`.
🔒
Keeps secrets as references
NebulaiOS stores whether an auth or credential reference exists, but response models redact raw secret values.
then gates runtime access
✓
Capability checked. External task tools require `tool.external_task_operations` in both the company grant and runtime advertisement.
!
Freshness checked. Disabled or stale runtime endpoints are rejected before an external agent can claim work.
i
Role checked. The Hermes orchestrator adapter refuses assignments unless the runtime declares the orchestrator role.
02
2Dispatch
Send Scoped
Work
NebulaiOS owns the envelope: tenant, company, project, task, run, policy, branch, memory scope, callbacks, and evidence requirements.
Assignment path
1
Build a Hermes run assignment Includes stable ids, task brief, repo policy, sandbox policy, allowed tools, and callback URL.
→ SEND
2
POST to runtime adapter HTTP mode sends the assignment to `/api/v1/hermes/assignments`; disabled mode blocks safely.
→ ACCEPT
3
Record dispatch evidence The run ledger stores one idempotent assignment message and a handoff action span.
→ LEDGER
or use governed task tools
✓ External lane
Agents can list, create, claim, update, delegate, attach evidence, block, or complete tasks.
✕ Unsafe lane
No matching auth ref, no lease token, stale endpoint, or production deletion request stops the operation.
03
3Report
LIVE
Return Signed
Evidence
Hermes keeps execution details, but NebulaiOS records enough proof to show what happened, what changed, and what needs review.
Callback and evidence loop
✍️
Signed callback arrives
`X-NebulaiOS-Signature` is verified against the active tenant callback secret.
🧾
Usage packet is normalized
Public Hermes usage is combined with subagent spans, tool spans, Git operations, artifacts, and split requests.
👁️
Founder cockpit updates
Runs move through active, split-requested, review-ready, blocked, completed, or failed states.
with hard boundaries
reviewexternal complete stops before done
idempotentcallbacks and mutations replay safely
scopedtenant/company/task ids must match
No raw secrets— only redacted credential references enter prompts, callbacks, and projections