DocsCLIco create

co create

Scaffold a new ConnectOnion agent project with intelligent defaults — identity, API keys, and a runnable agent in one command.

Download

Quick Start: Run co create — picks a template, sets up your global identity, and writes a runnable agent.

Command Flow

co create behaves differently the first time you run it versus every time after.

First-Time User

No ~/.co/ yet. The CLI generates a master keypair, your agent address, and an email — all written to ~/.co/keys.env.

Returning User

Reuses your global identity and copies any saved API keys from ~/.co/keys.env straight into the new project's .env.

First-Time Run

code

bash

co create my-first-agent

output

🚀 Welcome to ConnectOnion!

✨ Setting up global configuration...

✓ Creating ~/.co/ directory

✓ Generating master keypair

✓ Your address: 0x7a9f3b2c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a

✓ Your email: 0x7a9f3b2c@mail.openonion.ai

✓ Creating ~/.co/keys.env (ready for your API keys)

🧅 ConnectOnion Project Creator

========================================

✔ Choose a template:

❯ Minimal - Simple starting point

Web Research - Data scraping & analysis

Playwright - Browser automation

Custom - AI generates based on needs

✔ Paste your API key (or Enter to skip): › sk-proj-xxx

✓ Detected OpenAI API key

✓ Saved to ~/.co/keys.env for future projects

✔ Project name: › my-first-agent

✅ Project created successfully!

📁 Created: my-first-agent

📦 Template: Minimal

✨ AI Features: Enabled

📧 Agent email: 0x7a9f3b2c@mail.openonion.ai (global)

🔑 Agent address: 0x7a9f3b2c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a (global)

🚀 Next steps:

────────────────────────────────────────

1️⃣ cd my-first-agent

2️⃣ pip install python-dotenv

3️⃣ python agent.py

Returning Run

code

bash

co create another-agent

output

🧅 ConnectOnion Project Creator

========================================

✓ Using global identity: 0x7a9f3b2c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a

✓ Using global email: 0x7a9f3b2c@mail.openonion.ai

✔ Choose a template: › Web Research

✓ Found API keys in ~/.co/keys.env

✓ OpenAI key will be copied to project

✔ Project name: › research-bot

✅ Project created successfully!

📁 Created: research-bot

📦 Template: Web Research

✨ AI Features: Enabled

📧 Agent email: 0x7a9f3b2c@mail.openonion.ai (global)

🔑 Agent address: 0x7a9f3b2c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a (global)

🔑 API keys: Copied from global config

💡 Using global email/address. Run 'co status' to view.

What Gets Created

Global Configuration (first time only)

Lives in your home directory and is shared across every project on this machine.

Files created:

~/.co/

├──keys.env# Identity (AGENT_ADDRESS, AGENT_EMAIL) + shared API keys

├──keys/# Master identity

├──agent.key# Private key (for signing)

└──recovery.txt# Recovery phrase

└──logs/

└──cli.log# Command history

Project Structure

Files created:

my-agent/

├──🐍agent.py# Main agent implementation

├──.env# API keys (copied from ~/.co/keys.env)

├──.co/

├──host.yaml# Project config (uses global address/email)

└──docs/# Framework documentation

├──co-vibe-coding-all-in-one.md

└──connectonion.md

├──README.md# Project documentation

└──.gitignore# Excludes .env and sensitive files

Projects use the global address/email by default — no per-project keypair, no duplicate identity.

Configuration Files

Global Identity — `~/.co/keys.env`

Single source of truth for your address, email, and any third-party API keys. Loaded as environment variables.

code
bash
AGENT_CONFIG_PATH=/Users/you/.co
AGENT_ADDRESS=0x7a9f3b2c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a
AGENT_EMAIL=0x7a9f3b2c@mail.openonion.ai
IS_EMAIL_ACTIVE=true                # Becomes true after `co auth`
OPENONION_API_KEY=eyJhbGciOiJI...   # If authenticated
# Plus any third-party API keys you've added
# OPENAI_API_KEY=sk-proj-xxx
# ANTHROPIC_API_KEY=sk-ant-xxx

Project Config — `.co/host.yaml`

Tiny YAML file that tells the runtime which file to launch and where to read environment variables from.

code
yaml
name: my-agent
entrypoint: agent.py
env: .env

Project API Keys — `.env`

Auto-copied from ~/.co/keys.env at create time. Edit per-project as needed.

code
bash
# my-agent/.env
OPENAI_API_KEY=sk-proj-xxx
ANTHROPIC_API_KEY=sk-ant-xxx
# Any other keys from global config

Note: There is no global host.yaml. Identity lives in ~/.co/keys.env as environment variables. The only YAML is per-project, at .co/host.yaml.

API Key Handling

co create resolves API keys in this order:

Priority	Source	When used
1	--key <value>	Explicit override on the command line
2	~/.co/keys.env	Reused from previous projects
3	interactive prompt	Pasted at the prompt and saved globally
4	skip	Add to `.env` later

Auto-Detection

Pasted keys are recognized by prefix — no need to specify the provider:

sk-proj-...→OpenAI

sk-ant-...→Anthropic

AIza...→Google

gsk_...→Groq

Templates

minimal

Basic agent with simple tools — the smallest runnable starting point.

web-research

Web scraping + research tools, ready to crawl and summarize.

playwright

Browser automation with Playwright wired into the agent.

custom

AI generates the agent based on a free-form description.

Selecting a Template

code
bash
# Interactive selection
co create

# Direct specification
co create my-bot --template minimal

# Custom with description
co create assistant --template custom --description "Slack integration bot"

Command Reference

co create [name] [options]

Option	Short	Description
[name]	—	Project name (positional, prompts if omitted)
--template	-t	Template: minimal / web-research / playwright / custom
--description	-d	Description used by the `custom` template
--no-ai	—	Disable AI features (not recommended)
--key	—	API key to use (overrides global)
--yes	-y	Accept all defaults non-interactively

Examples

Quick Start

Terminalbash

$# Simplest form — uses global identity, prompts for name and template

$co create

$# With name

$co create my-bot

$# With name + template

$co create my-bot --template web-research

$# Accept all defaults

$co create quickbot -y

Custom Template

code
bash
# Interactive
co create --template custom

# With description
co create slack-bot -t custom -d "Slack bot for answering questions"

Override the API Key

code

bash

# Use a specific key for this project only — global config is unchanged
co create scratch-bot --key sk-proj-xxx

Identity Flow

1.First co create generates your global address/email and writes them to ~/.co/keys.env.

2.Every project after reuses the same address/email — one identity for all your agents.

3.API keys are copied from global keys.env into each project's .env.

4.Run co status any time to see your current address and email.

Troubleshooting

Check Your Address

Terminalbash

$co status

Permission Errors

Terminalbash

$# Fix global permissions

$chmod 700 ~/.co

$chmod 600 ~/.co/keys.env

$# Fix project permissions

$chmod 700 my-agent/.co

co create

Command Flow

First-Time User

Returning User

First-Time Run

Returning Run

What Gets Created

Global Configuration (first time only)

Files created:

Project Structure

Files created:

Configuration Files

Global Identity — ~/.co/keys.env

Project Config — .co/host.yaml

Project API Keys — .env

API Key Handling

Auto-Detection

Templates

minimal

web-research

playwright

custom

Selecting a Template

Command Reference

Examples

Quick Start

Custom Template

Override the API Key

Identity Flow

Troubleshooting

Check Your Address

Permission Errors

Star us on GitHub

Global Identity — `~/.co/keys.env`

Project Config — `.co/host.yaml`

Project API Keys — `.env`