Profiles

A profile is one agent. Use profiles to keep areas of work apart: one for home, one for your business, one for each client. Each is a folder under ~/.commonos/profiles/. No profiles ship with CommonOS; you create every one.

The folder

config.toml               provider, model, tags, tools, max_iterations
.env                      API keys for this profile only
SOUL.md                   the persona (stable prompt tier)
skills/<name>/SKILL.md    one folder per skill

COMMONOS_HOME moves the whole ~/.commonos folder.

config.toml

provider = "anthropic"
model = "<model id>"
tags = ["client:acme", "kind:business"]
tools = ["session_search", "delegate_task"]
max_iterations = 200

.env

Keys for this profile only, one KEY=value per line. Lines starting with # are ignored, and values may be quoted.

ANTHROPIC_API_KEY=sk-ant-...

A key missing from the profile’s .env is read from the environment cos runs in. .env files are ignored by git.

SOUL.md

The persona, sent as the first, cached block of the system prompt. Edit it freely. New profiles start with:

You are a helpful personal agent. Be direct and brief. Use your tools when they help, and say plainly when you can't do something.

Skills

Each skill is a folder with a SKILL.md that starts with front matter:

---
name: invoices
description: Send invoices
---
How this business writes and sends invoices…

The name and description of every skill form the skills index in each new session’s context:

Skills:
- invoices: Send invoices

Names

Profile names start with a letter and use letters (any case), digits, - and _, up to 40 characters. BusinessManager and Acme_2 work; Acme Manager doesn’t, because the name is also a folder, a command-line argument and a database id.

A name that differs from an existing one only by case is refused. macOS file systems ignore case, so the two would share a folder.

Commands

# A new profile
cos profile create BusinessManager --model <model id> --tag kind:business

# A mock profile, no key needed
cos profile create Sandbox --provider mock

# A copy of an existing profile
cos profile create AcmeManager --from BusinessManager --tag client:acme --tool session_search

cos profile list
cos profile show AcmeManager
cos -p AcmeManager chat

--from copies config.toml, SOUL.md and skills/. It never copies .env (keys belong to one account) or anything in the database, so the new profile starts with no sessions and no memory. --tag, --tool, --provider and --model replace the copied values when given.

What is separate, what is shared

Separate per profile:

• SOUL.md, skills, .env and tools
• sessions and their messages
• memory (the Memory plugin keys entries by profile)
• session_search results
• tags on every model call, so CommonBill can report each client’s cost on its own

Shared:

• one database (every row carries profile_id)
• one dashboard and one operator; there are no per-client logins yet
• the environment’s API key, for profiles without their own