eyeballdocs
Self-hosting

Operations and upgrades

Replace in-memory defaults, protect public edges, and deploy compatible packages together.

Before production:

  • configure EYEBALL_DATABASE_URL or provide equivalent durable execution, job, webhook-work/source, delivery, FileStore, AgentStore, voice-observer, and MCP SessionStore implementations;
  • retain idempotency correlation, immutable terminal records, and the stable recovery metadata during migrations;
  • run the executor, gateway, and dashboard behind TLS and authentication;
  • rate-limit bearer keys and MCP sessions;
  • configure the executor's redacted logs and optional OpenTelemetry export, then add deployment metrics for queue age and provider saturation;
  • route executor traffic only to instances whose public GET /ready probe returns 200; use GET /health separately for process liveness;
  • keep provider credentials and staged-file bytes out of custom logs, traces, errors, collector configuration, and client bundles;
  • back up execution/voice history, immutable voice-agent revisions, bindings, pointers, receipts, voice_agent_session_observers, voice_webhook_sources, MCP sessions/tasks, and any retained staged-file rows according to retention policy, then test restore paths;
  • monitor database growth and vacuum behavior for potentially large bytea rows; monitor and clean untouched expired mcp_sessions by indexed expires_at without weakening logical expiry; plan for TTL cleanup and replacement with an object-store-backed FileStore when workload or retention makes inline blobs inappropriate;
  • monitor durable queue age, expired leases, repeated recovery, execution_interrupted outcomes, observer retry age, exhausted observers, exhausted-but-unsignaled rows, repeated observer lease takeover, voice-source invariant misses, and exhausted webhook deliveries; signing and retry semantics are fixed by RFC 001.

The dashboard uses a server-side proxy; keep EYEBALL_API_KEY server-only. Mockhouse and /_mock must stay on loopback or an isolated test network.

Checked-in Vercel manifests

Use one Vercel project per deployable web surface. The manifests are deliberately small and keep every environment-specific value in the platform's encrypted Project Settings.

SurfaceVercel Root DirectoryChecked-in contract
Dashboardapps/dashboardapps/dashboard/vercel.json selects Next.js and runs the filtered Turborepo build from the repository root. Keep source files outside the Root Directory available for workspace dependencies.
Landingapps/landingapps/landing/vercel.json selects Next.js and serves the intentional static out export. Keep Include source files outside of the Root Directory enabled so the build can read the root pnpm lockfile, Turbo binary, and @eyeball/catalog workspace package. It requires no runtime secret.
Cloud control planePrivate cloud repository rootThat repository's vercel.json builds the Hono api/index.ts function and schedules the authenticated five-minute jobs adapter. Its production environment-variable names and equality constraints remain documented in the private repository.

These files make the deployment shape reproducible; they are not evidence of a live production deployment. Production still requires platform project setup, TLS and domains, encrypted environment values, Postgres/KMS/Stripe operations, health checks, backup/restore drills, and the founder-blocked launch validation.

Executor health checks

Configure the executor's own routes directly on the workload or load balancer:

Text
livenessProbe:
  httpGet:
    path: /health
    port: 3000
readinessProbe:
  httpGet:
    path: /ready
    port: 3000
  periodSeconds: 15
  timeoutSeconds: 12
  failureThreshold: 2

/health proves only that the executor process is responsive. Do not use it to admit traffic. /ready returns 503 when Postgres is unreachable, the applied migration journal differs from the committed executor migrations, the selected credential provider is unhealthy, the task queue is not accepting work, or its durable store cannot perform the non-writing admission capability check. Every dependency check has an executor-owned 10-second deadline, below the caller timeout above. The body contains only per-check ok or error status and is safe for probe logs.

Keep /ready unauthenticated for orchestrators, but expose it only through the same network controls used for other operational endpoints. During a dependency outage, remove an unready instance from service while leaving liveness alone; restarting an otherwise responsive process cannot repair an unreachable shared database or Cloud credential endpoint.

Upgrade order

  1. Update compatible core, catalog, toolkits, executor, gateway, SDK, and dashboard revisions.
  2. Regenerate toolkit docs and review schema/version diffs.
  3. Replay mock contract tests, including mutation idempotency and worker recovery.
  4. Apply both committed migration histories with pnpm db:migrate before deploying binaries; each service also applies only its own stream at boot.
  5. Deploy executor support for additive contracts.
  6. Deploy gateway/dashboard and then SDK clients.
  7. Monitor normalized error shifts, queue state, observer retry/exhaustion state, and voice-source invariant logs.

Tool and catalog versions in each execution provide the audit trail; do not discard them during migration.