install-connectonion

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:

  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:

# 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):

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:

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:

  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:

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 global ~/.co/keys.env by default, or to an explicitly selected project's .env, with the write/edit tool (never echo it back): OPENAI_API_KEY=… (gpt-*), ANTHROPIC_API_KEY=… (claude-*), GEMINI_API_KEY=… (gemini-*). 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:

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:

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

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:

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:          [e-mail]
  🤖  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 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.