Zozo Docs

Understanding Credentials ​

The Quickstart and Connect a Personal Subscription Credential cover connecting a subscription Credential and checking that it works. Connect OpenCode with OpenRouter covers the metered OpenCode path. This page explains when each Provider fits, how each Project maps to a Credential, and how fallback works.

Choose a Provider ​

Choose Claude or Codex when you want to run Claude or GPT models. Their subscription Credential kinds are the recommended path for a solo tenant working on their own repositories because inference is covered by the subscription alongside Zozo's flat hosted fee.

Choose OpenCode when you want models beyond Anthropic and OpenAI. OpenCode uses your OpenRouter account, so its inference is metered on top of Zozo's flat hosted fee. It fits especially well as a low-cost Fallback Credential behind a subscription Primary: when the Primary's usage window closes, new work can move to the metered model instead of stalling.

OpenCode isn't the recommended route for Claude or GPT models. It also can't hold a subscription Credential. Choose Claude or Codex directly for those models and their subscription authentication.

How Projects Map Activities to Credentials ​

Every Project has two Credential Routes: one for Dispatch and one for Intake Sessions plus Wayfinder work. Each route names one primary Credential and at most one fallback. Every Credential carries its Provider, so the route's Provider is derived from the selected name. It also carries a Credential Runtime Profile, the model and effort for each activity.

Adding a Project always asks for both primary Credentials. No global Provider or Credential default fills either field. This keeps a client's Project on the client's api_key and your own Projects on your personal subscription.

The Credentials column in Watched Projects shows each Project's chain in routing order: the primary first (for example claude: my-claude), then the fallback, or no fallback when there is none.

Change an Added Project's Credentials ​

  1. Open Projects in your Dashboard (#/projects).
  2. Open the Project's … menu and click Edit credential.
  3. Set the primary and optional fallback Credential for Dispatch.
  4. Set the primary and optional fallback Credential for Intake.
  5. Click Save credential. Zozo saves both complete routes together.

Each primary needs a Credential. A fallback can stay empty. When present, it must name a different Credential from the primary, but both can derive the same Provider. This supports routes such as claude-subscription followed by claude-api as well as Claude followed by Codex. Runs already in flight finish on the Credential their Thread selected. Existing Threads keep that selection, and the change applies when Zozo creates the next Thread.

Paused and unhealthy Credentials remain selectable and savable because those states can recover. A missing configured name remains visible so you can repair it, but saving is blocked until every configured name resolves.

Two failures are loud on purpose:

  • Naming a Credential that doesn't exist fails Thread creation outright, with an error naming the missing Credential. It never quietly selects an unconfigured account, because that would bill the wrong one with nothing to notice.
  • Deleting a Credential any Project still names is refused, and the refusal names every Project that still references it. Fix the Projects first, then delete.

How Fallback Works on a Project ​

A Project opts into failover by choosing a second Credential for an activity. Its Runtime serves a new Thread when the primary can't. The fallback can derive the same or a different Provider. With no fallback chosen, a struggling primary parks the work and surfaces a Fleet Fault (the Dashboard's signal that Dispatch stopped for a reason a person should see).

Three triggers route a Run to the fallback, and opting in opts into all three. There's no per-trigger switch, and the same set applies whichever Provider is primary:

TriggerHow it behaves
Capped: the primary hit its usage capTransient. Routing returns to the primary the moment the cap resets.
Credential-unhealthy: the primary's Credential no longer authenticatesPersistent until a person re-authenticates it.
Policy mismatch: the primary's Runtime can't enforce the policy a Run requiresStructural and permanent.

The selected Credential is always visible. A Thread routed to its fallback records the primary Credential, fallback Credential, and safe reason for the substitution. Every Thread also records the Provider derived from the selected Credential, plus the model and effort that Credential brought. Choosing a fallback therefore chooses its billing identity, model, and effort together.

Tune a Credential's Runtime ​

Each Credential has its own expandable Runtime tuning panel on the Credentials page (#/auth). Open Tune runtime on its row, then set Model and Effort independently for:

  • Intake + Wayfinder, which covers Intake Sessions and all Wayfinder work.
  • Dispatch, which covers ordinary dispatched Runs.

The model field suggests model IDs known to the deployed build, but you can enter another Runtime-native ID. Model and effort values pass through to the Runtime, which rejects values it doesn't recognize. Leave a field blank to use the Provider's default. Click Save tuning to save the profile without rotating the Credential's authentication material or changing its health.

Existing Thread identity is immutable

Changing a Project's route affects only new Threads. Every existing Thread keeps its selected Credential and derived Provider for all later Runs, including resumptions and clarification continuations.

Docs for Zozo: a coding-agent harness.

Copyright © Zozo