connectonion · the agent CLI harness · open source · Apache-2.0
CLI is all you need.
Built for AI agents, not for you to learn. Install it once, tell Claude Code, Codex or OpenCode to use co, and it finds every command through --help.
Start with co init for global settings, inspect them with co env, then connect Microsoft with co auth microsoft and use co outlook. The same pattern reaches Gmail, your browser, files and chat. Credentials stay on your machine.1
1,481 GitHub stars · 218 forks · 232 releases · read 23 Sep 2026
# identity & memory
- 0x addressco init
- Agent mailboxco email
- Memoryco wiki
- Secretsco env
- Creditsco transfer
# mail, calendar & notes
- Gmailco gmail
- Outlookco outlook
- Google Calendarco gcalendar
- Google Meetco gcalendar meet
- OneNoteco onenote
- Teams meetingsco outlook calendar
# chat apps
- WhatsAppco whatsapp
- Telegramco telegram
- Discordco discord
- Feishuco feishu
- Larkco lark
- SMSco sms
# browser & files
- Your Chromeco browser
- Remote browserco remote-browser
- Google Driveco gdrive
- YouTubeco youtube
- Synology NASco syno
- Web searchco search
# coding agents
- Claude Codeco claude
- Codexco skills link
- Your skillsco skills
- Shared skillsco sub
- Evalsco eval
- Cursorco skills discover
- Kiroco skills discover
# models
- Managed keysco/… ($5 credit)
- OpenAIgpt-…
- Anthropicclaude-…
- Geminigemini-…
- Mistralmistral/…
- Groqgroq/…
- Grokgrok/…
- OpenRouteropenrouter/…
- Ollama (local)ollama/…
# agents & servers
- Remote agentsco call
- Your internetco proxy
- Your serversco deploy --to
- SSHco server ssh
- Schedulesco schedule
harness/aha
One request. Several environments.
“Read my Telegram bot's context, check the official docs, ask a teammate's agent to run an allowed check, then email me the answer.” Each hop is a visible CLI command with its own credentials and permissions.
co search ConnectOnion output, condensed for the GIF. The configured search engine may use account credits; search is in the 1.8.9 preview. No Telegram messages were read, remote agents called or emails sent for this demo.THE WORKFLOW · EXAMPLE, NOT A LIVE END-TO-END RUN
- 01Find the source
co searchSearch the web with a sourced answer, then fetch a source page if needed. Available in the 1.8.9 preview; the GIF shows a verified, read-only run.
- 02Bring in context
co telegram receiveRead messages delivered to a bot you control. Receive is experimental and needs a configured bot; it does not access someone else's chats.
- 03Ask another agent
co callRun an allowed check on a reachable remote agent. That agent can use Codex separately only if it is installed, authenticated and permitted there.
- 04Send the result
co email sendSend the finished summary through your connected mailbox, with an explicit recipient and your authorization.
harness/discover
Your agent only needs to know co.
You don't have to find tools, install skills or list commands in a prompt. Tell your agent to use co. It reads the command list, opens --help on the one it needs, and every command ends by printing what to run next.
Read transcript
$ co Commands: gmail · outlook · browser $ co gmail ✓ Next: co auth google
- 01One word to rememberco. Bare co lists every command; co commands lists every subcommand, one per line.
- 02No tool list to keepThe CLI is the list. When a command is added, your agent sees it the next time it runs co.
- 03Wrong turns point the wayErrors end with a Next: line, so an agent that guesses wrong is told what to run instead.
- 04Skills are optionalco skills link puts ConnectOnion's skills into Claude Code and Codex. It saves a step; nothing needs it.
- 05Check any CLI the same wayco audit gh pr scores another tool's help pages the way an agent reads them: usage, examples, documented flags. In the 1.8.9 preview.
- See all 42 commands →
harness/why
Why not MCP? Why not skills?
Both work. Both cost something before your agent does anything: MCP puts every tool definition in the model's context, and a skill only helps once someone has found and installed it for that agent. A CLI costs nothing until it runs, and its --help is the manual.11
MCP server
- Before the first message
- Every tool's name, description and schema is loaded into context. Anthropic measured 58 tools across five servers at about 55K tokens.
- How the agent finds a capability
- From the tool list its client loaded, if that server was installed and configured for this client.
- Setup
- A server process per integration, configured in each client you use.
Skills
- Before the first message
- Each skill's name and description sit in the prompt; the body loads when used.
- How the agent finds a capability
- Only if someone found the skill and put it in this agent's own folder (~/.claude/skills, ~/.codex/…).
- Setup
- A folder per skill, per agent, kept in sync by hand.
co (a CLI)
- Before the first message
- Nothing. co is a program on the PATH, not text in the prompt.
- How the agent finds a capability
- It runs co, then --help on the command it needs, about a thousand tokens each. Errors end with a Next: line.
- Setup
- pip install connectonion, once. Every agent with a shell can use it.
Not either-or: co skills link still gives Claude Code and Codex a shortcut to the right command. It is optional, because the CLI already explains itself.
harness/setup
One command replaces the setup.
Your agent runs the same co commands you would type. Each tab pairs the setup it replaces with a short command demo.
A keypair and address, made on your machine.
Read transcript
$ co init ~/.co/keys.env · global $ co env active settings · values hidden
harness/chat
Share your agent with a chat link.
co ai prints a chat link. Whoever opens it gets a web page, with no sign-up or install and a key made in their own browser.3 The agent also keeps a Home page for them, and redraws it after a run.4
Read transcript
$ co ai chat.openonion.ai/0xcbef…3318 Client opens the chat link. ✓ Home redraws after the run.
Messages pass through the OpenOnion relay, which terminates TLS.
Pulled 41 overdue rows from the portal and saved arrears-march.xlsx to your Drive. I also emailed you the summary.
harness/skills
Save a procedure as a skill.
A coding agent needs only its shell to use co. When you want the same steps every time, write them in a SKILL.md. Claude Code's skills load as they are; co skills discover finds Codex, Cursor and Kiro ones too.5 Codex itself runs as a provider, inside its sandbox.6
Read transcript
$ co skills discover Claude · Codex · Cursor · Kiro SKILL.md keeps the procedure. ✓ Your agent can reuse it.
--- name: monthly-arrears description: Pull overdue accounts from the portal and file the report. tools: [read_file, write_file, Bash(co *)] --- 1. co browser go_to the arrears page 2. co browser get_text 'table.arrears' > arrears.csv 3. co gdrive put arrears-march.xlsx 4. co email send the owner a two-line summary The skill is the runbook. Every step is a command.
harness/trust
Permissions.
Shell commands, file writes and email ask before they run, and file edits arrive as a diff. Another agent can run only what your whitelist names.8
Read transcript
$ co call 0x3d40…a1 co status ✓ Allowed by Bash(co *) $ co call 0x3d40…a1 rm -rf / ✗ Refused by the remote whitelist
- 01Approve a shell commandA human sees the command before it runs.
- 02Review a file diffChanged lines stay visible in the chat.
- 03Limit a remote agentThe host whitelist decides which commands are allowed.
01 ask before bash
02 edits as a diff
03 a whitelist for everyone else
faq
FAQ.
What is ConnectOnion?
ConnectOnion is the agent CLI harness. Each co command connects your AI agent to one service: Gmail, Outlook, Google Calendar, WhatsApp, Telegram, Discord, Feishu, SMS, a real logged-in browser, Google Drive or a Synology NAS. It also gives the agent its own 0x address, mailbox and memory, and it works from Claude Code and Codex. You don't create an OAuth app, add DNS records or write a Playwright script. It is an open-source Python package, Apache-2.0 licensed. Install it with pip install connectonion.
Is ConnectOnion for people or for AI agents?
For AI agents. You install it once and tell Claude Code, Codex, OpenCode or any agent with a shell to use co. The agent runs bare co to see the commands, --help on the one it needs, and follows the Next: line each command prints. You can run the same commands to check what it did, but you don't need to learn them.
Why not an MCP server?
Most MCP clients load every tool definition into the model's context up front. Anthropic measured 58 tools across five servers at about 55K tokens before the conversation starts. A CLI costs nothing until the agent runs it: bare co prints about 5 KB and a command's --help about the same, read only when needed. There is also no server process to configure per client. More: docs.connectonion.com/guides/cli-vs-mcp
Why not skills?
A skill only helps once someone has found it and installed it into that agent's own folder, and each agent keeps its own. With a CLI the program is the list: a new command shows up the next time the agent runs co. Skills are still useful as a shortcut, and co skills link adds ConnectOnion's to Claude Code and Codex, but nothing requires them.
What is an agent CLI harness?
A set of command-line tools an AI agent runs to reach real services: mail, chat apps, a browser, files, servers. Because each capability is an ordinary shell command, any agent with a shell can use it, including Claude Code and Codex, and a person can run the same command to check what the agent did. ConnectOnion's harness is the co command. More: docs.connectonion.com/guides/what-is-an-agent-cli-harness
How do I give Claude Code or Codex access to Gmail?
Install ConnectOnion (pip install connectonion), run co auth google, then co skills link. The last command links ConnectOnion's bundled skills, including co-google, into Claude Code and Codex, so the agent can run co gmail inbox, co gmail read and co gmail reply from its shell. The Google credentials are saved only on your computer. Guide: docs.connectonion.com/guides/claude-code-gmail
How do I give an AI agent its own email address?
Run co init. The agent gets a keypair, a 0x address and a mailbox at 0x…@mail.openonion.ai, hosted by OpenOnion, so there are no DNS records to set up. co email send sends and co email inbox reads. co email name <name> --buy claims a readable name@openonion.ai address from your credits. Guide: docs.connectonion.com/guides/ai-agent-email-address
How do I connect an AI agent to WhatsApp?
Run pip install 'connectonion[whatsapp]', then co whatsapp listen. Scan the QR code from WhatsApp (Settings → Linked devices → Link a device); every message is then written to ~/.co/inbox/whatsapp/. The agent takes the next one with co whatsapp receive and answers with co whatsapp reply. The linked device sees every chat on that number, so use a number meant for the agent. Guide: docs.connectonion.com/guides/ai-agent-whatsapp
Can an AI agent use a browser I am logged into?
Yes. co browser keeps one real browser open between commands. You log in by hand once, including 2FA, and every later command (co browser go_to, co browser get_text, or co browser do "…" for an AI-driven task) runs in that logged-in session. Guide: docs.connectonion.com/guides/ai-agent-browser
How is it different from an AI agent framework?
It still ships a Python Agent class, but the product is the harness. Every capability (browser, email, inboxes, files, remote calls, deploys) is a CLI command, so anything that can run a shell command can use it: your own ConnectOnion agent, or a coding agent such as Claude Code or Codex.
Do I need an API key to try it?
No. New accounts get $5 of credit for managed models through the co/ prefix, routed through OpenOnion's proxy. Put your own OpenAI, Anthropic or Google key in .env and change the model string whenever you like.
How can an agent send email without setting up DNS?
Every agent gets its own mailbox at its address on mail.openonion.ai after co auth. It is an OpenOnion-hosted service, so there is no Resend or SendGrid account and no SPF, DKIM or MX records to add. co email send sends; bare co email shows the inbox.
How does Gmail or Outlook work without my own OAuth app?
co auth google and co auth microsoft run the consent through OpenOnion's OAuth app, so there is no cloud project, consent screen or review queue on your side. The credentials come back encrypted to a one-time key your CLI generated and are saved only on your computer.
Is agent traffic end-to-end encrypted?
No. Traffic between an agent and people outside your network passes through the OpenOnion relay, which terminates TLS and can read it.
How do I control what an agent is allowed to do?
Dangerous tools (bash, shell, file writes, background tasks, email, delete) stop and ask for approval in the chat UI when one is attached, and file edits arrive as a diff. Custom tools you add run without asking unless you list them in .co/host.yaml. Remote agents calling yours with co call can only run what your .co/host.yaml whitelist names.
Which models does it work with?
OpenAI, Anthropic, Google, Groq, Grok, OpenRouter and Mistral, or managed keys through the co/ prefix. The model is a string you can change.
co commands
All commands.
All 46 commands (4 in the preview), generated from co commands. Open a group for what each does and its subcommands.
# identity & accountinit · setup · auth · keys · env · status · trust · transfer · doctor · commands · reset
- co init
- Initialize global ~/.co/keys.env, or use co init ./ for a project.
- co setup
- Set up your global ~/.co/ — identity, agent.json, and skill library.
- co auth
- Sign in to OpenOnion (login, status, logout) or connect a service.↳ login · status · logout · google · microsoft · feishu · lark
- co keys
- Show agent keys and credentials.
- co env
- Show, set and remove settings in the selected env file (global ~/.co/keys.env unless --env-file was given).↳ show · path · get · set · rotate · unset
- co status
- Check credential sources, account status, and deployments.
- co trust
- Manage trust lists (contacts, whitelist, blocklist, admins)↳ list · level · add · remove · block · unblock · admin
- co transfer
- Send credits to another agent address (irreversible, confirms first), or list transfers.
- co doctor
- Diagnose installation.
- co commands
- List every command, including subcommands, one per line with its summary.
- co reset
- Reset account (destructive).
# mail & calendaremail · gmail · outlook · gcalendar · onenote
- co email
- Send and read email from the agent's address↳ send · inbox · read · addresses · default · name · share · unshare · upgrade · sent
- co gmail
- Send and read email from your Gmail account.↳ inbox · read · reply · send · sent · search · mark · archive · star · attachments · download · unanswered · draft · label
- co outlook
- Your Outlook account: mail, scheduled sends, contacts and calendar.↳ send · inbox · read · download · reply · scheduled · cancel · sent · search · contact · calendar
- co gcalendar
- Google Calendar events and Meet links.↳ list · today · read · meetings · free · create · meet · update · delete
- co onenote
- Preview (1.8.9): Your OneNote notebooks: list sections and pages, read a page as text, create a page.↳ ls · pages · read · create
# chat appswhatsapp · telegram · discord · feishu · lark · sms
- co whatsapp
- WhatsApp as an inbox: listen, receive, send, reply.↳ listen · receive · send · reply · edit · delete · react · done · check · ls · chats · log · consume · group
- co telegram
- Telegram bot: send, plus experimental listen, receive and reply.↳ send · listen · receive · reply · done · check · ls · chats · log · consume
- co discord
- Experimental: Discord bot as an inbox: listen, receive, send, reply.↳ listen · receive · send · reply · done · check · ls · chats · log · consume
- co feishu
- Feishu bot as an inbox: listen, receive, send, reply.↳ listen · receive · send · reply · done · check · ls · chats · log · consume
- co lark
- Lark (global Feishu) bot as an inbox: listen, receive, send, reply.↳ listen · receive · send · reply · done · check · ls · chats · log · consume
- co sms
- Pair a phone and read the Agent's encrypted SMS inbox↳ pair · inbox · devices
# browser & networkbrowser · remote-browser · proxy · search · fetch · call
- co browser
- Drive one persistent browser.↳ do · tab · network · cookies · status · close · config · help
- co remote-browser
- Manage an owner-bound browser session on a remote agent over OIP.↳ config · start · status · sessions · stop · diagnose
- co proxy
- Share this computer's internet connection with an authorized agent.↳ share · status · stop · diagnose
- co search
- Preview (1.8.9): Search the web: Gemini grounded in Google Search on credits, or Serper, Brave or DuckDuckGo (free).
- co fetch
- Preview (1.8.9): Fetch a public web page as Markdown, or ask a question about it.
- co call
- Run one command on a remote agent and print the result (no LLM).
# files & mediagdrive · syno · youtube · tiktok
- co gdrive
- List, search, download, and upload Google Drive files.↳ list · search · info · get · put · rm
- co syno
- Connect to a Synology NAS, inspect its state and manage everyday files.↳ login · logout · status · ls · info · search · download · upload · mkdir · copy · move · get · put · shares · nas · network · storage · service · share
- co youtube
- YouTube Data API using your saved Google login.↳ channel · list · video · put · update
- co tiktok
- Experimental: TikTok post plans and read-only readiness. Nothing is uploaded.↳ post · inspect
# coding agents & memoryclaude · skills · sub · announce · wiki
- co claude
- Experimental: Run Claude Code through the ConnectOnion session connector.↳ run
- co skills
- Discover, copy, list and link existing SKILL.md files; does not author or benchmark them.↳ discover · copy · manifest · list · link
- co sub
- Follow public skills: co sub sync <0xaddress> once; co sub refreshes all saved publishers↳ sync · list · remove
- co announce
- Publish ~/.co/agent.json + SKILL.md bodies (publish:true) to the relay.
- co wiki
- Experimental: Personal Wiki — map first, investigate next. Targets 1.9.0.↳ init · investigate · open · list · show · search · start · stop · status · sync · logs · doctor · advanced · scan · map-skills · stub · reflect · reflections · propose · review · abstract · capture · sources · config
# build & testai · create · copy · audit · benchmark · eval
- co ai
- Start AI coding agent or run one-shot prompt.
- co create
- Create new project.
- co copy
- Copy built-in tools/plugins to customize.
- co audit
- Preview (1.8.9): Is a CLI fit for an agent harness? Runs its --help pages and scores them: usage, examples, documented flags, every subcommand reachable.
- co benchmark
- Author the standard BEFORE editing a skill.↳ list · check
- co eval
- Run a benchmark with the real Agent and inspect scored reports.↳ run · report · legacy
# run & shipdeploy · server · schedule
- co deploy
- Deploy to ConnectOnion Cloud, or with --to onto a server you own.
- co server
- Register, list and preflight the servers you can deploy to↳ add · ls · check · new · ssh · fix-key · forget · destroy
- co schedule
- This agent's own recurring work, from .co/schedule.yaml: see it, check it, run an entry now, pause or resume one.↳ list · check · run · pause · resume
~/notes
11 notes: what each claim depends on, and what on this page is simulated
- [1] New accounts get $5 of credit for managed models through the
co/prefix, so nothing needs an OpenAI, Anthropic or Google key on day one. Those requests route through OpenOnion's proxy; put your own key in.envand change the model string whenever you like. The agent runs on your machine.co deployhosts it on ConnectOnion Cloud, andco deploy --toputs it on a server you own. Register servers withco server. ↩ - [2]
co browserruns a daemon that owns one real browser, so a login you complete by hand, including 2FA, stays valid for every later command. Forty operations, listed byco browser help;co browser do "…"puts an agent on the same live browser. Several agents can share it: each opens its own tab withco browser tab open, andco browser tab lsshows every tab and who owns it. ↩ - [3] The chat is a web page, so the person you send it to doesn't install anything or sign up. Their key is generated in their own browser and never sent to us. Because it lives in that browser, a different browser is a different identity unless the recovery phrase is imported. Traffic reaches people outside your network through our relay, which terminates TLS and can read it. It is not end-to-end encrypted. ↩
- [4] The agent edits
dashboard.htmlwith ordinary file tools; the host notices the change and pushes a snapshot after that run; the pane re-renders. No polling, no fetch, no deploy. Capped at 2 MB with images inlined. The generated starter carries up to four skills as buttons, and agent-authored HTML runs underdefault-src 'none'in an opaque-origin frame, so it cannot call out. ↩ - [5]
.claude/skills/and~/.claude/skills/are in the load path;co skills discoveralso scans Codex, Cursor and Kiro. One difference: we read thetools:key, not Claude Code'sallowed-tools, so a skill's auto-approvals do not carry across. Its instructions run unchanged, but it asks for permission more often. ↩ - [6] Requires the
codexbinary (npm install -g @openai/codex). Sandbox levels are read-only, workspace-write and danger-full-access; per-action approvals reach you through the same approval card as everything else. ↩ - [7]
co auth googleandco auth microsoftrun the consent through OpenOnion's OAuth app, so you don't set up a cloud project or consent screen or wait for a review. The credentials come back encrypted to a one-time key your CLI generated, and are saved only on your computer. Calendars are there too:co gcalendarandco outlook calendar. The agent's own mailbox (0xcbef…@mail.openonion.ai) is an OpenOnion-hosted service that activates afterco auth. It is not a mail server on your machine, which is why you add no DNS records. ↩ - [8] A fixed set of tool names counts as dangerous: bash, shell, file writes, background tasks, email and delete. A custom tool you add is not in that set and runs without asking, so name it in your
.co/host.yamlpermissions if it should be. Approvals need a frontend attached: with no chat UI connected there is nothing to ask, and tools run.co callsends bash, not a tool call, so a whitelist entry for thereadtool does not permit areadcommand. ↩ - [9] The 12-word recovery phrase is the only way back. If you lose it, the address is gone, and no reset link or support ticket can restore it.
.co/keys/carries aDO_NOT_SHAREwarning file. The address itself is public by design: it is the same string you hand out as a chat link and an email address. ↩ - [10] Every session on this page is simulated. The commands and the output strings are copied from the CLI's source; the data (addresses, file names, row counts, the client) is invented. The chat, Home and approval screens are drawn from the real components, with invented content. ↩
- [11] From Anthropic's engineering blog. "Most MCP clients load all tool definitions upfront directly into context", and presenting tools for on-demand discovery cut one task from 150,000 tokens to 2,000 (Code execution with MCP, 4 Nov 2025). A five-server setup with 58 tools took about 55K tokens before the conversation started (Advanced tool use, 24 Nov 2025). Clients are adding on-demand loading; a CLI has it by default, since the agent reads
--helponly when it needs a command. The co figures are the size of the printed help on 1.8.9b12. ↩
Apache-2.0. Works with OpenAI, Anthropic, Google, Groq, Grok, OpenRouter and Mistral, or managed keys through the co/ prefix.