Quickstart

This walks a newly invited hosted tenant from "I have an invite link" to watching their first Run stream — one path, start to finish. It assumes you already have an invite (an operator mints those; see the operator runbook if that's you instead) and a GitHub account. There's exactly one way through: connecting a Provider with your own vendor API key, the blessed default for a hosted tenant (ADR-0035) — this page doesn't branch into the personal-subscription paths (oauth_token/auth_file) a self-hosted operator might use instead.

What you need

• An invite link from whoever administers your Zozo deployment, shaped like <control-plane-url>/v1/auth/github/start?invite=<code>.
• A GitHub account.
• An API key from Anthropic (Claude) or OpenAI (Codex) — whichever Provider you want to drive. Either works; you only need one to start.

Sign up and land on your stack

Step 1 — Open your invite link in a browser. It redirects to GitHub; approve the OAuth app. GitHub redirects back to /v1/auth/github/callback, which renders the sign-up result as JSON:

{
  "userId": "...",
  "tenantId": "...",
  "isNewUser": true,
  "isNewTenant": true,
  "sessionToken": "..."
}

That response also sets your control-plane session cookie, so your browser is now signed in — you don't need to copy sessionToken by hand unless you'd rather drive the rest of this from a script (it's a plain bearer token, usable as Authorization: Bearer <sessionToken> on any control-plane request).

Step 2 — Open /v1/handoff/start in the same browser. Once your stack has finished provisioning, this redirects you straight to it, already signed in:

<control-plane-url>/v1/handoff/start

ADR-0042 — the one-time-code handoff

The control plane mints a short-lived, single-use code scoped to your stack and redirects your browser to https://<your-slug>.zozostacks.dev/handoff?code=.... Only your stack's own outbound call can ever redeem that code — no shared secret crosses the boundary between the control plane and your stack, and the code is single- use even if the URL is replayed. Your stack redeems it, mints its own local session, and redirects you to /. See ADR-0042 for the full mechanism.

If /v1/handoff/start 404s, your stack isn't provisioned yet — give it a minute and retry; there's nothing else to do on your end.

You're now signed in at https://<your-slug>.zozostacks.dev/ — your own Dashboard.

Connect your Provider

Open Auth in the Dashboard, pick Claude or Codex, and paste in your API key. This is the whole step: an api_key Credential is the vendor-blessed, unattended default (ADR-0035), so — unlike a personal subscription credential — there's no separate consent checkbox to accept first.

Under the hood, this is one request:

POST /api/providers/claude/credential
{"type": "api_key", "value": "sk-ant-..."}

Start your first Run

Open a new Thread, type a prompt, and send it. That's a Run: one execution of your prompt against the Provider you just connected.

Under the hood, this is two requests: POST /api/threads creates the Thread, then POST /api/threads/:id/runs with {"prompt": "..."} submits the Run.

Watch it stream

The Run's timeline fills in live as it happens — no refresh needed. Two labels to know as you watch:

• The status label, top of the timeline: queued → running → completed (or failed). If you abort a Run instead, its underlying status is aborted, but the label you'll actually see reads Interrupted — a deliberately friendlier word for the same outcome.
• The three filters above the timeline — Messages, Tools, System — group what's streaming in: the agent's own text, every tool call and its result, and everything else (session/context bookkeeping). "All" shows every one of them.

Under the hood, the Dashboard is holding open one SSE connection, GET /api/runs/:id/events, and rendering each HarnessEvent as it arrives.

What's next

• Core concepts — the Provider/Runtime/Thread/Run/Event vocabulary this page used throughout.
• More sections land here as their underlying features ship — see this site's README.md for that policy.