Install Connectonion
Apps & Automationinstall-connectonionInstall Connectonion is an Agent Skill for apps & automation published in the openonion/connectonion repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/openonion/connectonion/blob/HEAD/connectonion/useful_skills/install-connectonion/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/install-connectonion, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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
- 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 thebashtool exist everywhere. - Verify every step before moving on — each has a check; run it.
- 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.
- Only ask the human for things only a human can do — installing Python, adding credit, an OAuth browser login. One plain sentence.
- 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.
unameprintsDarwin/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
bashtool is fine. Windows: thebashtool does not work (Unix-only) — use theshelltool and avoidgrep/cat/ls. Preferco …andPY -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; thenpy -3works.- macOS: python.org installer or
brew install [email protected].- 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 foundafter a good install → scripts folder not on PATH. Confirm withPY -m connectonion.cli.main --version; then either usePY -m connectonion.cli.main …or reinstall viapipx 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:
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 authcomes in
co initprinted an auth/network error, or the token didn't land (Step 4'sco statussays "No API key found") → the scaffold worked but authentication didn't. Complete it:co auth # re-runs just the authentication, writes OPENONION_API_KEY + AGENT_EMAILco authis safe to re-run any time; it refreshes the token in place.- "Directory not empty" → add
--forceonly 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:
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 status401 / token expired →co authagain.
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 browsercommand 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 browserworks 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 — usepatchright install chromium.co doctorBrowser line missing → patchright library gone:PY -m pip install patchright.co doctorBrowser 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; runco auth(Step 3 covers this). Direct verbs likego_todon'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 fromco 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; runco 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 |
📧 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: [email protected]
🤖 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 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 createalready authenticate — you don't normally need a separateco auth; it's the repair step when init's auth didn't land (e.g. offline).co emailis the built-in managed mailbox (…@mail.openonion.ai), activated by authentication (Step 3). It needs onlyOPENONION_API_KEY— notco auth google.- Cross-platform gotchas: the
bashtool is Unix-only (useshellon Windows);python3may bepython/py -3; the browser binary is never auto-installed; andco browserruns natively on Windows/macOS/Linux from 1.2.1 (Unix sockets on POSIX, named pipes on Windows); older versions need WSL on Windows. co doctordoes not confirm the browser can launch — it only checks the patchright library/stealth driver. The real proof isco browser go_to example.com.--yesonco init/co createis 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.