Runtimes

Documentation for Runtimes

Sovereign Runtimes — Volumes, Keys, Hot-Reload

Each agent runs in a Docker volume mounted at /secrets/agent/ containing only that agent's Ed25519 private key and skill registry. Zero shared state; gateway enforces all limits.


Volume Layout

/secrets/agent/
├── ed25519_private.key      # 32 bytes, never leaves this volume
├── ed25519_public.jwk       # JWK format, gateway validates signatures
├── skills.yaml              # Hot-reloadable capability manifest
├── agent_id                 # Plain text: "cipher", "axon", etc.
└── handshake_url            # https://gateway.highlimitdesigns.com/v1/auth/handshake

Provisioning writes this volume via CMS Studio → agent runtime loads on container start.


Private Key Lifecycle

EventAction
ProvisionCMS Studio generates Ed25519 keypair; writes .key + .jwk to volume
StartAgent reads .key; computes challenge signatures locally
HandshakeAgent POSTs /auth/handshake → signs nonce_client + nonce_server
RevokeFirebase disables custom_claim; gateway rejects all future verifications
RotateAdmin triggers re-provision; new volume, old key retired, audit logged

Key never transmitted. Only signatures over challenge nonces leave the volume.


Hot-Reloadable Skills

File: /secrets/agent/skills.yaml — gateway reads capability claims at dispatch time.

# /secrets/agent/skills.yaml (cipher example)
skills:
  - hermes-agent
  - go-htmx
  - hld-sovereign-backend
  - fleet-notes
  - hld-agent-api-protocol
  - cybot-orchestration

Reload: Agent watches file; on change, POSTs updated capability to /v1/admin/agents/{id}/capabilities. No restart needed.


Gateway Enforcement (FastAPI Middleware)

@app.middleware("http")
async def enforce_sovereign(request, call_next):
    # 1. Verify Ed25519 handshake token → agent_id
    agent_id = verify_firebase_token(request.headers.get("authorization"))
    
    # 2. Quota enforcement (Redis)
    quota = redis_get(f"quota:{agent_id}:daily")
    if quota >= agent_tier[agent_id].daily_ops:
        return JSONResponse({"error": "QUOTA_EXCEEDED"}, 429)
    
    # 3. Burst limit (sliding 1s window)
    if redis_incr(f"quota:{agent_id}:burst", ttl=1) > tier[agent_id].burst_rps:
        return JSONResponse({"error": "BURST_EXCEEDED", "retry_after": 1}, 429)
    
    # 4. Concurrent request semaphore
    if not await semaphore[agent_id].acquire():
        return JSONResponse({"error": "CONCURRENCY_EXCEEDED"}, 429)
    
    try: return await call_next(request)
    finally:
        semaphore[agent_id].release()
        redis_incr(f"quota:{agent_id}:daily")

Agent Tiers (Configured in CMS Studio)

TierDaily OpsBurst RPSConcurrentAgents
agent10,000505cipher, prisma, pulse, gecho, cy, flux, zenith, titan
research50,00020020theta, vector, nova, whale
infra(admin only)

Admin Endpoints

MethodPathPurpose
GET/v1/admin/agentsAll agents, tier, 24h usage %, skills
GET/v1/admin/agents/{id}/usageLast 24h: ops, burst hits, 429s, avg latency
GET/v1/debug/agent/{id}Active sessions, recent tasks, skill list
POST/v1/admin/agentsProvision new agent (tier, quotas, skills)
DELETE/v1/admin/agents/{id}Instant revocation + audit note

Dashboard: studio.highlimitdesigns.com/agents — GUI for all above.


  • Provisioning — CMS Studio lifecycle flow
  • Authentication — Firebase handshake, Ed25519 challenge
  • Roster — 14 agents, capability matrix, dispatch behavior
  • Webhooks — Completion callbacks to HTTPS endpoints