install-connectonion

# 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 own OpenAI/Anthropic/Google account, save the key with `co env set` (never echo it back): `co env set OPENAI_API_KEY …` (`gpt-*`), `co env set ANTHROPIC_API_KEY …` (`claude-*`), `co env set GEMINI_API_KEY …` (`gemini-*`). That writes global `~/.co/keys.env`; put `co --env-file /abs/path/.env` before `env set` for a project file. `co env` shows what the selected file holds, secrets masked. Plain init does not 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.