git:20260717.736699b to git:20260808.c57e60c

0 added, 12 removed. Audit A to A.

---

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.

- tools:

- - Bash(python *)

- - Bash(python3 *)

- - Bash(py *)

- - Bash(pip *)

- - Bash(pip3 *)

- - Bash(co *)

- - Bash(patchright *)

- - shell

- - read_file

- - write

- - edit

---

# 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.