Optional head start · 10 minutes

Set Up Before Saturday

One paste into Codex sets up your own AI agent. Totally optional — if you skip it or it fails, we'll do it together at the workshop.

Hit an error anywhere? It really doesn't matter — just come a little early on Saturday (doors 1:40pm) and we'll sort it out together before the start.

Step 1 — Install the ChatGPT desktop app

Download and install the official ChatGPT desktop app (Mac & Windows): chatgpt.com/download
Open the app, sign in with your ChatGPT account, and open Codex.
Start a new conversation in Codex.

The desktop app is required — Codex on the website runs in OpenAI's cloud and can't set anything up on your computer. The app works on your actual machine.

Step 2 — Copy & paste the installer

Click the green button below — it copies everything you need.
Paste into the new Codex conversation and press Enter.
Let it run (a few minutes).

Two normal things while it runs: Codex asks permission to run commands — click Approve. If it asks for your computer password, that's Python installing.

What am I copying? (view the full text)

Follow the skill below right now to install and set up ConnectOnion on this computer. I may not be technical — do all the work yourself, keep me informed in plain language, and only ask me for things only a human can do.

---
name: install-connectonion
description: Install and fully set up ConnectOnion on Windows, macOS, or Linux so EVERY `co` command works — find Python, pip install, `co init` (scaffolds the project AND authenticates, writing keys.env), confirm the account with `co status`, install a browser for `co browser`, then hand the user a plain-language summary. Use when the user says "install connectonion", "set up connectonion", "get me started with co", or a co command fails because nothing is configured yet.
---

# Install ConnectOnion Skill

Take a machine from nothing to a setup where **every `co` command works** — `co status`,
`co email`, `co browser`, the `co/*` models, all of it — on whatever OS the person uses.
Then tell them, in plain words, exactly what they have.

**Assume the person running this may not be technical.** They may not know what a "virtual
environment", "PATH", or "API key" is — that's fine. Do the technical work *for* them and
keep them informed in friendly, jargon-free language. Never dump a raw stack trace; turn
every problem into "here's what happened and here's what I'm doing about it."

## How to run this skill

1. **Work on the user's real OS.** Windows, macOS, and Linux differ in command names and
   shells — do Step 0 first and use the right ones. Don't assume `python3`, `grep`, or the
   `bash` tool exist everywhere.
2. **Verify every step before moving on** — each has a check; run it.
3. **Auto-correct instead of giving up.** On failure, don't paste the error — diagnose,
   apply the *Recovery* fix, retry (up to 2 attempts) before escalating.
4. **Only ask the human for things only a human can do** — installing Python, adding
   credit, an OAuth browser login. One plain sentence.
5. **Never print or store secrets** — confirm a key is *present*, never show its value.

## Step 0: Know the machine

Resolve the platform and the Python command. **Everything below writes `PY` for "the
Python that works here"** — resolve it once, reuse it.

- **Detect the OS** (e.g. `uname` prints `Darwin`/`Linux`; failing/absent → Windows).
- **Find Python (needs 3.10+).** Try in order, keep the first that prints 3.10+ — that's `PY`:
  ```bash
  python3 --version      # macOS / Linux usually
  python --version       # Windows usually
  py -3 --version        # Windows Python launcher
  ```
- **Pick the shell.** macOS/Linux: the `bash` tool is fine. **Windows: the `bash` tool does
  not work** (Unix-only) — use the `shell` tool and avoid `grep`/`cat`/`ls`. Prefer `co …`
  and `PY -c "…"`, which behave the same everywhere.

> **Recovery — Python missing or < 3.10** (give the path for *their* OS, don't install it yourself):
> - **Windows:** python.org installer (tick "Add python.exe to PATH") or `winget install Python.Python.3.12`; then `py -3` works.
> - **macOS:** python.org installer or `brew install python@3.12`.
> - **Linux:** `sudo apt install python3 python3-venv python3-pip` (or the distro equivalent).

## Step 1: Isolate with a virtual environment (recommended)

Keeps the install tidy and avoids "externally-managed-environment" errors:

```bash
# macOS / Linux
PY -m venv .venv && source .venv/bin/activate
# Windows PowerShell
py -3 -m venv .venv ; .venv\Scripts\Activate.ps1
# Windows cmd
py -3 -m venv .venv & .venv\Scripts\activate.bat
```

After activating, `python`/`pip` point inside `.venv` — `PY` can just be `python`. If venv
creation fails, it's optional: continue globally and note it to the user.

## Step 2: Install the package

Use `PY -m pip` (works even when a bare `pip` isn't on PATH):

```bash
PY -m pip install connectonion       # add -U to upgrade
co --version                          # confirm the CLI is on PATH
```

> **Recovery**
> - `co: command not found` after a good install → scripts folder not on PATH. Confirm with
>   `PY -m connectonion.cli.main --version`; then either use `PY -m connectonion.cli.main …`
>   or reinstall via `pipx install connectonion`.
> - "externally-managed-environment" / permission error → go back to Step 1's venv, retry.

## Step 3: Initialize the project — this also sets up keys.env

This is the core step. **`co init` does two things at once**: it scaffolds the project
(`agent.py`, `.env`, `.co/`) **and authenticates**, writing the account credentials to the
global `~/.co/keys.env` and copying them into the project `.env`. **Always pass `--yes`** so
it doesn't stop on a prompt:

```bash
co init --yes                     # existing folder: config + auth
# or start a fresh project folder (also authenticates):
co create my-agent --yes          # then: cd my-agent
```

Templates for `co create`: `minimal` (default), `coder`, `browser`, `web-research`,
`hosted-browser`, `co-ai`. Use `--template <name>`.

After this succeeds, `~/.co/keys.env` (and the project `.env`) contain:

```
OPENONION_API_KEY=<token>              # unlocks co/* models, co status, co email
AGENT_EMAIL=0x…@mail.openonion.ai      # the agent's own mailbox
IS_EMAIL_ACTIVE=true                   # co email is live
AGENT_ADDRESS=0x…                      # the agent's identity (public)
```

(The signing private key lives in `~/.co/keys/agent.key`, **not** in keys.env — never touch
or print it.)

> **Recovery — this is where `co auth` comes in**
> - `co init` printed an auth/network error, or the token didn't land (Step 4's `co status`
>   says "No API key found") → the scaffold worked but authentication didn't. Complete it:
>   ```bash
>   co auth        # re-runs just the authentication, writes OPENONION_API_KEY + AGENT_EMAIL
>   ```
>   `co auth` is safe to re-run any time; it refreshes the token in place.
> - "Directory not empty" → add `--force` only after the person confirms it's safe here.
> - Command hangs → you forgot `--yes`; re-run with it.

## Step 4: Confirm the account is wired up

Prove keys.env is good — `co status` needs `OPENONION_API_KEY` + the signing key + the
backend, so a clean result means everything downstream (models, email) will work:

```bash
co status        # shows agent email, balance, and free credit
co doctor        # cross-platform health check; "API Key" line should be ✓
```

**Optional — own provider keys instead of managed:** if the person would rather use their
own OpenAI/Anthropic/Google account, add the key to the project `.env` with the
`write`/`edit` tool (never echo it back): `OPENAI_API_KEY=…` (`gpt-*`),
`ANTHROPIC_API_KEY=…` (`claude-*`), `GEMINI_API_KEY=…` (`gemini-*`). Managed `co/*` still
needs `OPENONION_API_KEY` from Step 3.

> **Recovery**
> - "No API key found" → auth didn't land in Step 3. Run `co auth`, then re-check.
> - `co status` 401 / token expired → `co auth` again.

## Step 5: Browser — do this so `co browser` works (only if they need it)

Skip unless the person wants web automation (`co browser`, or the `browser`/`hosted-browser`
template). Two things to know first:

- **From connectonion 1.2.1, the first page-driving `co browser` command auto-installs a
  browser when none exists** (visible one-time download in the terminal) — normally there
  is NOTHING to do here. The manual step below is the fallback for older versions,
  airgapped machines, or a failed auto-install.
- **`co browser` works natively on Windows from connectonion 1.2.1** (named-pipe daemon —
  plain PowerShell/cmd is fine, no WSL). On an OLDER version (`co --version` < 1.2.1),
  native Windows isn't supported: upgrade first (`PY -m pip install -U connectonion`), or
  do the browser work inside WSL.

If a manual install IS needed (older version / auto-install failed): the agent uses
desktop **Google Chrome** when present at the standard OS path; otherwise install
Patchright's browser:

```bash
PY -m patchright install chromium        # per-user dir, NEVER needs admin (what auto-install runs)
PY -m patchright install chrome          # branded Chrome: best stealth, but a system installer
# Linux/CI without desktop libraries may need system deps (asks for sudo):
PY -m patchright install --with-deps chromium
```

**Verify it actually launches — `co doctor` is NOT enough here.** `co doctor` only checks
the patchright library/stealth driver; it shows `ok` even when no Chrome exists and the real
launch would fail. Prove the real thing by driving a page:

```bash
co browser go_to example.com     # navigates → Chrome launched OK. Then: co browser close
```

> **Recovery**
> - *"Chrome failed to start … ~/.co/browser.log"* → no drivable browser. Run
>   `PY -m patchright install chromium` (Linux: add `--with-deps`), or install desktop Google
>   Chrome to the standard path. Note: a Chrome in a non-standard spot (Windows per-user
>   `%LOCALAPPDATA%`, Linux snap/flatpak) isn't auto-detected — use `patchright install chromium`.
> - `co doctor` Browser line **missing** → patchright library gone: `PY -m pip install patchright`.
> - `co doctor` Browser line **broken** (stealth driver) → `PY -m pip install --force-reinstall --no-cache-dir patchright`.
> - `co browser do "…"` says *"requires authentication"* → the natural-language mode uses a
>   managed model; run `co auth` (Step 3 covers this). Direct verbs like `go_to` don't need it.

## Step 6: Optional integrations (Gmail / Outlook / Calendar)

Only if they want the agent to use their *personal* Gmail or Outlook. These are **separate**
from the built-in `co email` mailbox and require `OPENONION_API_KEY` first (Step 3):

```bash
co auth google       # Gmail Send + Google Calendar (browser OAuth)
co auth microsoft    # Outlook + Microsoft Calendar (browser OAuth)
```

Each opens a browser login — hand off: *"finish the login in the window that opened."*
Tokens are saved to `.env` / `~/.co/keys.env`. `co email` does **not** need these.

## Step 7: Verify the commands actually run

Confirm the things the person will use — not just that files exist. Run what's relevant:

```bash
co status                                          # account reachable
co email inbox --last 5                            # built-in mailbox responds (needs Step 3)
PY -c "from connectonion import Agent; print(Agent('smoke', max_iterations=2).input('Reply with exactly: OK'))"
co browser go_to example.com && co browser close   # only if Step 5 done — proves Chrome launches
```

> **Recovery — read the error and act**
> - `InsufficientCreditsError` (smoke run) → managed account out of credit; a *money* thing
>   only the person fixes. Show address/balance from `co status`, point to top up
>   (https://o.openonion.ai/purchase) or Discord (https://discord.gg/4xfD9k8AUF).
> - `co email` "No API key" / "AGENT_EMAIL not found" → auth didn't complete; run `co auth`.
> - `ModuleNotFoundError: connectonion` → wrong Python/venv active; re-activate Step 1's venv.

## Step 8: Hand the user a plain-language summary

The payoff. Run `co status`, then translate it — **don't paste the raw panel**:

| `co status` field | Say it like this |
|--------------------|------------------|
| Credits            | 🎁 **Free credit from ConnectOnion** — money they gave you to start |
| Balance            | 💰 **Money available right now** to run your agent |
| Email              | 📧 **Your agent's own email address** (send/receive with `co email`) |
| Agent Address/ID   | your agent's unique identity |

```
✅ You're all set up! Here's your ConnectOnion account:

  🎁  Free credit ConnectOnion gave you:  $X.XX
  💰  Money available to use now:          $X.XX
  📧  Your agent's email address:          you@mail.openonion.ai
  🤖  Model access:                        managed (co/* models) — nothing else needed
  🌐  Browser (co browser):                ready   (or "not set up — tell me if you want it")
  📦  Installed:                           connectonion vX.Y.Z  (Python 3.12 on Windows)
  📁  Your project:                        ./my-agent  (minimal template)

  What you can do now:
    • co status                      — check your balance any time
    • co email                       — read your agent's inbox
    • co email send <to> <sub> <msg> — send mail from your agent
    • co browser do "…"              — drive a web browser  (if set up)
    • python agent.py                — run your agent

  If the balance ever runs low, add more at https://o.openonion.ai/purchase —
  the free credit is enough to get going.
```

Adjust: **balance $0/low** → say it gently with the top-up link, no alarm. **Path B (own
keys)** → swap the money lines for "your own <provider> key", skip balance. **No browser** →
say it's not set up and offer. Keep it to the lines that matter to *this* person.

## Notes

- **`co init` / `co create` already authenticate** — you don't normally need a separate
  `co auth`; it's the repair step when init's auth didn't land (e.g. offline).
- **`co email` is the built-in managed mailbox** (`…@mail.openonion.ai`), activated by
  authentication (Step 3). It needs only `OPENONION_API_KEY` — *not* `co auth google`.
- **Cross-platform gotchas:** the `bash` *tool* is Unix-only (use `shell` on Windows);
  `python3` may be `python`/`py -3`; the browser binary is never auto-installed; and
  **`co browser` runs natively on Windows/macOS/Linux from 1.2.1** (Unix sockets on
  POSIX, named pipes on Windows); older versions need WSL on Windows.
- **`co doctor` does not confirm the browser can launch** — it only checks the patchright
  library/stealth driver. The real proof is `co browser go_to example.com`.
- `--yes` on `co init`/`co create` is mandatory for unattended runs.
- Never print, log, or commit keys; templates gitignore `.env` — keep it that way.
- State lives in `~/.co/` (global identity + keys.env) and the project's `.co/` + `.env`.
  Deleting one project never breaks another.

After installation verifies, offer an optional workshop check-in:
1) Run `co status` and note only the public agent address. Never include the computer username or any secret.
2) Show the user the exact recipient, subject, and body: recipient `openonionai@gmail.com`, subject `Workshop check-in`, body containing only the public agent address.
3) Ask for explicit approval to send that exact email. If approved, send it once. If declined, skip it; setup still succeeds.
4) Finish with: "You're all set for Saturday. See you at 2pm!"
If setup fails after two repair attempts, explain the failed check in plain language and say: "Setup hit a snag—come a little early on Saturday and Aaron will sort it out with you."
Only ask the user to approve commands, complete browser login, or approve the optional check-in. Never request secrets or unrelated personal information.

Step 3 — That's it

Codex finishes everything on its own — you only click Approve when it asks.
At the end, Codex shows an optional check-in email containing only your public agent address. You decide whether to send it.
There's a surprise waiting for your agent on Saturday.

If Codex says setup hit a snag — no problem at all. Come by 1:40pm Saturday and Aaron will fix it with you in person.

The workshop slides

Follow along on Saturday. The slides are unlocked with the password Aaron gives you in the room.

Open the workshop slides →