git:20260902.b076990 to git:20260908.3b1ff0b

---

name: install-connectonion

description: Install and set up ConnectOnion on Windows, macOS, or Linux, initialize global credentials, and verify the requested CLI capabilities. Use for "install connectonion", "set up connectonion", "get me started with co", or missing installation/configuration. Project scaffolding requires an explicit project path.

---

# 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 global credentials; create a project only when requested

Plain **`co init` initializes global `~/.co/keys.env` and the machine identity**,

then attempts authentication. It does not create or modify `.env`, `.co/`, or

`agent.py` in the current directory, even when run inside a project. Use `--yes`

for unattended setup:

```bash

co init --yes # global credentials only

# Only if the user wants a project:

co init ./ --yes # existing folder: config, .env, and docs

co init ./ --template co-ai --yes # also add the hosted agent template

co create my-agent --yes # new folder with the co-ai template

```

The `co-ai` and `custom` templates are supported. `co create` defaults to

`co-ai`; `co init ./` defaults to configuration only. An explicit directory is

required with `co init --template`, `--description`, or `--force`.

After authentication succeeds, `~/.co/keys.env` contains:

```

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") → local setup 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.

> - Project directory not empty → use `co init ./ --yes` to add configuration while

> preserving source files. Use `--force` only with approval to overwrite template files.

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

copy implicitly loaded project or process keys into global storage; `--key` is

an explicit request to save a provider key. 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 (only if requested)

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.