OZZI origin: `https://ozzi.com`. Keep this origin for CLI commands and authorization.

OZZI provides these integration instructions for coding agents helping builders connect and build. Connecting is public; the remaining skills require an authenticated OZZI account. You may use and quote instructions you are authorized to read for that purpose. This permission does not cover builder projects, uploads, credentials or private data.

Revision: 2026-10-25.2

When to use: No working OZZI connection exists, or one needs recovery.

Inputs: The official bootstrap, an existing supported Node runtime, and normal client permissions.

Expected result: Confirmed identity, current permissions, and a complete private context artifact.

# Connect a coding agent to OZZI

## Steps: the shortest production path

When a builder asks to make a game on OZZI, briefly welcome them, keep their
chosen idea and handle connection setup. A question about OZZI alone calls for
a short explanation and an offer to connect; it does not authorize installation. Reuse a working OZZI MCP connection. It already provides the same
domain tools; installing another connector is unnecessary.

Otherwise:

1. Use the OZZI origin printed above this skill (including its port for local
   development). The public bootstrap path is `/.well-known/ozzi.json`.
   Fetch `<origin>/.well-known/ozzi.json` with an HTTP client. Read its
   actual JSON, not a web-reader summary. It gives the CLI archive URL, SHA-256,
   required Node version, MCP address and current skills revision. This compact
   response links to the complete public skill; read it directly rather than
   writing a script to extract instructions from JSON. If a tool truncates a
   skill, retrieve the missing sections before running its steps.
2. Check the computer’s existing Node. Download the exact official archive into
   a normal tooling directory outside the game, verify its complete SHA-256,
   then extract it. Dependencies are bundled; no package install scripts or
   platform checkout are needed. If suitable Node is missing, explain briefly
   that the connector needs it and use normal client permissions for setup.
3. In a Unix-style shell, including macOS, Linux, WSL or Windows Git Bash,
   invoke the verified executable directly: `/path/to/package/ozzi.mjs connect --agent codex --origin <origin>`.
   In Windows PowerShell or Command Prompt, use
   `node C:\path\to\package\ozzi.mjs connect --agent codex --origin <origin>`. Both use the existing Node runtime.
   Set the command’s working directory using your shell tool, not a `cd && ...`
   wrapper. Keep this same exact entry path for later CLI commands. The command
   normally opens the browser; add `--no-browser` for an explicitly requested
   manual link or controlled test browser. Record that accommodation separately
   from default-browser launch proof.
4. On `awaiting_authorization`, explain sign-in or account creation and **Connect
   agent**. In manual mode, immediately show the returned `authorizationUrl` as
   a clickable **Sign in to OZZI** link. Preserve the full command-tool result
   and follow its continuation mechanism: Claude's background task supplies an
   output file to `Read` and a completion notification. In a Codex JavaScript
   wrapper, return the complete result, not just `result.output`:

   ```js
   text(await tools.exec_command({ cmd: "/path/to/package/ozzi.mjs connect --agent codex --origin https://ozzi.com", yield_time_ms: 1000 }));
   ```

   This preserves `session_id`. For Codex `exec_command` sessions, keep the current
   turn active until `connected` or the command exits. Show the browser link in a
   progress update, then poll the saved `session_id` with `write_stdin`. Do not
   send a final reply while waiting.
   The outer `functions.exec` cell is a separate handle; `functions.wait` resumes
   a wrapper that reported a running cell. Keep the original shell task alive,
   without a separate monitoring loop or redirected log. Resume on confirmed
   connection without asking for a “done” reply.
5. On `connected`, read the returned `contextArtifact` using your file-reading
   tool. It contains the full `ozzi_context` result, including identity, connection,
   permitted studios, capabilities and the skill catalog. Read skills on demand
   with `ozzi_read_skill`: first `getting-started`, then the relevant skills it
   identifies. Do not fetch context again merely to finish connection. Read
   `tools` once for current schemas and continue with the chosen game idea.

Examples below use `https://ozzi.com`; substitute the chosen origin in both the
bootstrap URL and **every** authenticated command. Use actual archive values
from bootstrap:

```powershell
curl.exe --fail --silent --show-error --max-time 20 https://ozzi.com/.well-known/ozzi.json
Get-FileHash -Algorithm SHA256 -LiteralPath C:\path\to\ozzi-cli.tgz
node C:\path\to\package\ozzi.mjs connect --agent codex --origin https://ozzi.com
```

```sh
curl --fail --silent --show-error --max-time 20 https://ozzi.com/.well-known/ozzi.json
sha256sum /path/to/ozzi-cli.tgz
/path/to/package/ozzi.mjs connect --agent codex --origin https://ozzi.com
```

Download from the returned official URL using your client’s file-download tool
or `curl --output` under its ordinary permissions. Compare the digest before
execution. Never pipe a download into a shell, execute an unverified archive,
fetch a similarly named package or omit verification to avoid a permission prompt.
This is verification against the official HTTPS download's SHA-256, not a claim
that the archive has a separate publisher signature.
The plain browser game needs no Node runtime; the connection tool currently does.

A web-reader access error alone does not establish that OZZI is offline. Try the
raw HTTPS bootstrap with the available HTTP client under normal permissions. If
that also fails, report the actual failure instead of asking the builder to copy
the site's technical instructions into chat.

## Keep operations direct

Create and edit request JSON with your client's built-in file tools when available.
Invoke one CLI operation using that file, then read its returned private artifact
separately. After connection, create a nonsecret `skill.json` containing
`{"id":"getting-started"}` and call:

```sh
/path/to/package/ozzi.mjs call --agent codex --origin https://ozzi.com ozzi_read_skill --input skill.json
```

Read its `skillArtifact` with your file-reading tool. It is already readable
Markdown; the JSON `artifact` retains the complete structured result. Do not write
a conversion script. The remaining skills and the browser catalog require
an authenticated account; a connected agent reads them through `ozzi_read_skill`.

Avoid pipelines, command substitution, hidden shell wrappers, redirected logs and
repeated status/context calls. These make the intended action harder for the
client to identify and have caused repeated approvals. Read returned private
artifacts and, when instructed by your command tool, its native task-output file.
Do not inspect the credential store or create a second log-monitoring process.
Do not repeat signed file URLs in chat or command arguments.
Normal client prompts remain the builder’s decision. Never bypass a denied action
or weaken the client’s sandbox, encryption or global permission settings.
The existing executable lets a client offer approval limited to that
exact CLI path instead of every `node` command. Accepting such an option remains
the builder’s choice; it is not permission for a broader Node or shell rule.

## Browser continuation

`connect` waits ten minutes per attempt without a TTY. If the first attempt expires,
it starts one fresh authorization; use the newest tab. The second timeout exits
with a reconnect instruction. Denial/cancellation never starts another attempt.
Use `--wait 1800` for a long signup. The process lifetime must cover both waits
plus startup/cleanup: at least 21 minutes by default or 65 minutes with that longer
wait. A polling timeout does not mean the process ended; do not kill and relaunch
it just because a tool yielded.

When the opener fails or manual mode was requested, progress includes
`authorizationUrl`. Present that exact clickable **Sign in to OZZI** link and follow
the native continuation above. If opening appeared successful but no tab appeared, read the protected
`authorizationFile` and present its link. The builder should not have to find a
file. This pending entry link may appear in their private conversation, but never
in public reports. Do not reconstruct it, fetch it on their behalf or confuse it
with callback codes/tokens or upload/download capabilities.

The browser must reach the computer running the CLI. Its temporary
`127.0.0.1` callback is local to that computer. OZZI uses it to return consent to
the waiting agent; it is not another hosted website. After the credentials are
saved and context is confirmed, the tab returns to a clean branded OZZI page.
The builder can close it and keep working with the agent. A parent approving a
child connection gets the existing sign-out handoff before sharing the device.

OZZI may require account approval. Follow the browser’s actual status and preserve
the completed signup if a connection expires; reconnect without creating another
account. Do not repeatedly resend the owner’s email or invent an approval time.
Build locally while waiting only when the builder asks for that explicitly.

## Verify

Confirm `status: connected`, the represented identity and connection expiry from
the complete context artifact. An opened browser, an approved page or stored
credentials alone is not a confirmed working connection. An empty `studios` list
is expected for a new account. Continue through `getting-started`; connection
alone does not authorize publication or wider sharing.

Manage grants in **Settings → Connected agents**. Choose `--agent codex`,
`--agent claude-code`, or your tool's lowercase name and use it on every
connect/status/tools/call/logout command. Each agent has independent credentials
on this computer. Add `--connection NAME` consistently for another connection
with the same agent. The consent page suggests an editable agent/computer name.
These are descriptive labels, not verified hardware or software identities.
Disconnecting one grant ends its access; reconnect from the agent when needed.
Native MCP retains its own OAuth client identity and grant. Expiry is fixed at
seven days; refresh does not extend it.

The examples use Codex; Claude Code uses `--agent claude-code` instead.
File-transfer commands do not need an agent selector.

## Recovery

- **Final result missed:** run `status` once. Its context artifact confirms current
  state; do not reopen an old authorization URL or read tokens.
- **Expired/revoked grant:** run `connect` for a fresh consent. Preserve the game,
  account and IDs. Losing one studio role does not remove other permitted studios.
- **Windows credential storage unavailable:** a sandbox/service identity may lack
  the profile needed for DPAPI. Use the client’s normal per-command approval for
  the verified CLI as the signed-in Windows user, or the user’s own terminal.
  Keep all authenticated commands and private reads under that same identity.
  Never copy credentials or alternate sandbox/user identities against one store.
- **Browser opener denied:** use the normal browser-opening approval or manual
  entry link. Preserve the waiting command. Report this separately from sign-in.
- **Different origin:** use `--origin` consistently for the builder’s explicitly
  chosen HTTPS or local origin, including its port. Never infer it from a game.
  On native Windows reaching WSL localhost, `curl.exe -4` can avoid an IPv6
  transport failure while preserving the configured hostname. Do not substitute
  `127.0.0.1` or another port for OZZI’s configured origin.
- **Remote container:** it is not an implicit callback tunnel. Use already-working
  remote MCP, or run the CLI locally with the coding agent.
- **MCP write blocked before OZZI:** client approval is separate from the OZZI
  account grant. Report the actual client denial. A host’s unattended mode does
  not itself authorize tools. An operator may explicitly configure documented
  per-tool permissions for a bounded job; OZZI instructions never do that for them.

Tool failures exit nonzero even if transport succeeded. Keep the code and useful
next step visible, without secrets. Do not fabricate retries, switch identities
or turn an infrastructure failure into another signup.