Documentation _

Architecture

PHOSPHOR runs on Zeabur as a small set of long-lived services plus per-tenant agent runtimes that are provisioned on demand. Every mutating call flows through three gates (auth → CSRF → entitlement) before any tool is invoked, and every tool call emits an audit event to an append-only NDJSON log.

> Service topology

• phosphor-web — the marketplace UI and API. Next.js 15 (app router) running on 0.0.0.0:$PORT inside a Zeabur container. Hosts /api/run, /api/deploy, /api/checkout, the magic-link auth routes, and the Stripe webhook.
• audit-store — append-only NDJSON store on a Zeabur volume at /var/lib/audit. Reached only from other services via internal DNS audit-store.zeabur.internal:8080. Never exposed to the public internet. See the retention policy at services/audit-store/RETENTION.md.
• phosphor-agent-runtime — a published Zeabur template (code LW76NP) that instantiates a per-tenant agent runtime on /api/deploy. The template takes tenant-specific tokens as variables and runs the agent image declared in the catalog (e.g. ghcr.io/nousresearch/hermes-agent:latest).

> Data flow — "run an agent"

browser                phosphor-web              audit-store
  │  POST /api/run ────► session gate
  │                     csrf gate
  │                     rate-limit gate
  │                     ├─► load manifest
  │                     ├─► load runner
  │                     ├─► Promise.race(
  │                     │    runner(ctx),
  │                     │    timeout(limits.maxRuntimeSec))
  │                     ├─► auditAppend(event) ─────────►  /ingest
  │ ◄──── 200 result ───┤
  │                     └─► deny path also emits event ─►  /ingest

> Data flow — "deploy an agent"

browser                phosphor-web                        Zeabur control plane
  │  POST /api/deploy ─► session + csrf + rate-limit
  │                      validateManifest()
  │                      entitlement check (plan → agent tier)
  │                      zeabur-template install ────────────► create service
  │                                                             wire env vars
  │                                                             attach volume
  │                      ◄──── serviceId + domain
  │                      persist instance record
  │ ◄──── instance ──────┤                                      audit-store ◄──ingest
  │                      │                                           │
  │                      └──► internal DNS ──► runtime on *.zeabur.internal

> Source

• apps/web/app/api/run/route.ts — inline run path
• apps/web/app/api/deploy/route.ts — template install path
• services/audit-store/ — append-only ingest service
• packages/sandbox/src/runner.ts — per-run context & policy guard

User Guide

Five steps take you from a cold browser tab to a running agent with an auditable trail.

> 1. Sign in

Hit /login and enter any email address. PHOSPHOR sends a magic link via ZSend (or Resend) if ZSEND_API_KEY / RESEND_API_KEY is configured. When no provider is configured (dev mode) the link is returned inline on the response so you can click through immediately. GitHub OAuth is also supported when GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET are set.

> 2. Browse the catalog

Open /agents for the full catalog or / for FRESH DROPS. Every card shows a risk chip (low / med / high), a compact permissions summary (net hosts, fs mode, secret count), and a tier badge. Clicking a card loads the detail page.

> 3. Acknowledge permissions

Every agent detail page has a permissions rap sheet listing the full manifest — tools, fs read/write paths, net allow-hosts, env keys, and resource limits. Neither the TRY IT NOW nor DEPLOY button will work until you tick the checkbox. If you try, the rap sheet flashes and scrolls into view.

> 4. Run it inline (free)

For inline-runnable agents (e.g. Hermes, Openclaw Dench) the TRY IT NOW panel runs the agent synchronously in phosphor-web. Leave the API key blank for deterministic mock mode — useful for demos — or paste an sk-ant-… key for live Claude. You can override the base URL and model to point at any OpenAI-compatible provider (default placeholder: https://api.openai.com/v1).

> 5. Deploy to a sealed runtime

The deploy panel provisions a per-tenant Zeabur service from the phosphor-agent-runtime template (code LW76NP), wiring your configuration as template variables. Plan tier gating applies: a pro-tier agent (like Hermes) cannot be deployed on astarter plan — the response includes a requiredTier field so the UI can prompt the upgrade.

> Source

• apps/web/app/login/page.tsx — magic link UI
• apps/web/components/AgentDetailFlow.tsx — rap-sheet ack, run panel, deploy panel

API Reference

Every route listed here lives under apps/web/app/api/. All mutating routes require auth + CSRF unless noted; run and deploy are additionally rate-limited. All responses are JSON. Errors use { error: string }.

> POST /api/run

Execute an inline-runnable agent synchronously in phosphor-web.

auth

required (phosphor_session)

csrf

required (X-Phosphor-CSRF)

rate-limit

10/min per user, key run:<sub>

body

{ agentId, input, config?, tenantId? }

200

{ runId, output, latencyMs, audit: {...} }

401

missing / invalid session

403

csrf check failed OR agent not inline-runnable

429

rate limited — Retry-After header set

curl -X POST https://phosphor.zeabur.app/api/run \
  -H 'Content-Type: application/json' \
  -H 'Cookie: phosphor_session=<session>' \
  -H 'X-Phosphor-CSRF: <csrf>' \
  -d '{
    "agentId": "hermes-agent",
    "input": {
      "messages": [{
        "channel": "gmail",
        "from": "cfo@acme.test",
        "subject": "Q2 forecast",
        "body": "Review by EOD."
      }]
    },
    "config": { "ANTHROPIC_API_KEY": "sk-mock" }
  }'

> POST /api/deploy

Provision a per-tenant Zeabur service from the phosphor-agent-runtime template.

auth

required

csrf

required

rate-limit

10/min per user, key deploy:<sub>

body

{ agentId, tenantId, plan, acknowledgedPermissions, config? }

200

{ instanceId, serviceId, domain }

402

entitlement denied — requiredTier in body

403

permissions not acknowledged

> GET /api/instances

List the current user's deployed agent instances.

auth

required

csrf

not required (GET)

200

{ instances: Instance[] }

> POST /api/checkout

Create a Stripe Checkout Session for a paid agent upgrade. Returns a redirect URL that resolves against the public origin (publicOrigin(req)) so success / cancel URLs are never the internal bind address.

auth

required

body

{ agentId, plan }

200

{ url, sessionId }

> POST /api/checkout/mock-confirm

Deterministic mock for the checkout flow (for demos without a live Stripe account). Classifies card numbers into paid / declined / 3ds / invalid based on digit rules.

> POST /api/stripe/webhook

Stripe webhook receiver. Verifies the signature with STRIPE_WEBHOOK_SECRET and grants entitlement on checkout.session.completed.

> POST /api/auth/login

Accepts { email } or { provider: "github" }. For magic link: issues a one-time token and sends it via ZSend/Resend (or returns it inline when no provider is configured, for dev). For GitHub: returns an OAuth redirect URL.

> GET /api/auth/callback

Consumes a magic-link token or a GitHub OAuth code, upserts the user, signs a session cookie, and redirects to /agents on the public origin.

> CSRF token bootstrap

On every navigation, apps/web/middleware.ts ensures a phosphor_csrf cookie exists (24-byte hex, 7-day max-age, SameSite=Lax). Client code reads it with document.cookie and echoes it in the X-Phosphor-CSRF header on mutating calls.verifyDoubleSubmit compares with constant-time equality.

• CLAUDE.md — project brief, rubric, current self-evaluation, and the running tally of skills / features used.
• DEMO.md — 8-step runbook for the face-cam walkthrough.
• build-log/ — one file per completed step, including every bug fix and its root cause.
• deploy/DEPLOY-LEDGER.md — append-only log of every Zeabur action (service create, deploy, env var, domain, restart).
• services/audit-store/RETENTION.md — retention / rotation / backup contract for the audit store.