README and quickstart: install, run, change safely, ship

This document takes a new operator from an empty machine to a running OGL Cortex fleet, then covers daily operation, safe changes and the ship chain. Internals are in 01-core-architecture.md and 02-execution-engine.md. Settings are in 03-configuration-registry.md. Guards are in 04-failsafe-boundary-log.md.

The command-line tool is named cortextos.

Every cortextos command below was checked against the CLI's --help output. Commands from the OGL layer are marked as such and live in this repo's harness/ folder (harness/tools/ship.sh, harness/install.sh). The pentest gate is harness/security/cortex_pentest_gate.py.

Terms

• Instance: one runtime state folder, $CTX_ROOT = ~/.cortextos/<instance>. The default instance id is default. $CORTEX_HOME is the framework checkout (for example ~/cortextos).
• Org: a group of seats that share a knowledge base, tasks and approvals. Lives in the framework checkout at orgs/<org>/.
• Seat: one agent, in orgs/<org>/agents/<seat>/.
• Daemon: the Node process (dist/daemon.js) that keeps every seat's Claude Code session alive.
• pm2: the process manager that keeps the daemon and the dashboard running.

1. Prerequisites

Supported platforms: macOS and Linux. The framework also runs on Windows 10/11 with Task Scheduler for reboot persistence (scripts/install-windows-pm2-startup.ps1).

2. Install

2.1 Guided

npm install -g pm2
curl -fsSL https://raw.githubusercontent.com/grandamenium/cortextos/main/install.mjs | node
claude ~/cortextos
# inside Claude Code:
/onboarding

Or run the interactive wizard from a shell:

cortextos setup --instance <instance>

setup installs state folders, creates an org, configures seats and starts the daemon.

2.2 Manual

cortextos install --instance <instance>
cortextos init <org> --instance <instance>
cortextos add-agent boss --template orchestrator --org <org> --instance <instance>
cortextos add-agent analyst --template analyst --org <org> --instance <instance>

Put credentials in each seat's .env (orgs/<org>/agents/<seat>/.env):

BOT_TOKEN=<bot-token>
CHAT_ID=<chat-id>
ALLOWED_USER=<numeric-user-id>[,<numeric-user-id>]

Then generate the pm2 config and start:

cortextos ecosystem --instance <instance> --org <org>
pm2 start ecosystem.config.js && pm2 save && pm2 startup

2.3 Add the OGL layer

The OGL layer is seat files and hooks, not a framework fork. For each seat, harness/install.sh <seat-dir> --apply installs from this repo's harness/ folder:

The installer is a dry run unless you pass --apply. See harness/README.md for what it writes and how to remove it.

3. First boot

3.1 The architecture you just started

3.2 Check it is alive

cortextos status --instance <instance>
cortextos list-agents --instance <instance>
cortextos bus list-agents --format text
cortextos bus read-all-heartbeats --format text
cortextos doctor --instance <instance>

3.3 Onboard each seat

1. Send /start to the seat's bot, then any message.
2. If you still need the chat id, read it from the Bot API: curl -s "https://api.telegram.org/bot<TOKEN>/getUpdates?timeout=30" | jq '.result[-1].message.chat.id'.
3. Send /onboarding. The seat sets its identity, goals and crons, then writes a .onboarded flag in its state folder.

4. The instance flag

Every lifecycle command defaults to --instance default: install, setup, init, add-agent, start, stop, restart, enable, disable, doctor, dashboard, ecosystem. status and list-agents take --instance with no default.

If your fleet runs under another instance id and you leave the flag off, the CLI reads ~/.cortextos/default and reports "Daemon is not running" while the daemon is healthy. Do not run cortextos start in response; it can create orphan processes.

Rule: pass --instance <instance> on every lifecycle command, or use the instance id default for single-fleet installs.

5. Start, stop, restart

5.1 Rules before any restart

Seats also restart on their own: on crash, and on context rotation after max_session_seconds (default about 71 hours).

6. Talking to the fleet

Dispatching work:

cortextos bus create-task "<title>" --assignee <seat> --priority normal \
  --desc $'TASK: <what>\nFILES: <paths, including the working folder>\nBAR: <how done is verified>\nRETURN: <what to report>'
cortextos bus update-task <task_id> in_progress
cortextos bus complete-task <task_id> --result "<summary>"
cortextos bus log-event task task_completed info --meta '{"task_id":"<task_id>"}'

Approvals:

cortextos bus create-approval "<what>" <external-comms|financial|deployment|data-deletion|other> "<context>"
cortextos bus list-approvals
cortextos bus update-approval <approval-id> <approved|denied> "<note>"

7. Adding a seat

1. Create a bot with @BotFather. Move the token through a secure path (password manager or a file you create on the machine), never through chat.
2. Send /start to the bot, then any message, and read the chat id (section 3.3).
3. Create the seat:

   cortextos add-agent <seat> --template <orchestrator|analyst|agent|agent-codex> \
     --org <org> --instance <instance> \
     [--runtime claude-code|hermes|codex-app-server|opencode] [--disabled]

   The templates/ folder also holds agent-opencode, hermes and m2c1-worker. --template agent --runtime opencode maps to agent-opencode.
4. Write BOT_TOKEN, CHAT_ID and ALLOWED_USER in orgs/<org>/agents/<seat>/.env. Without ALLOWED_USER, Telegram stays off.
5. Enable: cortextos enable <seat> --instance <instance> --org <org>. For a headless seat, add --worker.
6. Write the seat's goals.json, then cortextos goals generate-md --agent <seat> --org <org>.
7. Send /onboarding to the new bot.

Short-lived helpers do not need a seat:

cortextos spawn-worker <name> --dir <path> --prompt "<task>" [--parent <seat>] [--model <model>]
cortextos list-workers
cortextos inject-worker <name> "<text>"
cortextos terminate-worker <name>

8. Crons

Storage: $CTX_ROOT/.cortextOS/state/agents/<seat>/crons.json, envelope { "updated_at": "<ISO>", "crons": [ ... ] }, written atomically (src/bus/crons.ts, src/bus/crons-schema.ts). The daemon owns dispatch and reloads the file across restarts.

Guidance:

• Prefer 5-field wall-clock expressions ("0 8 * * *"). An interval at or above the heartbeat length can starve on the scheduler.
• A 5-field expression for a one-time job recurs. Remove the cron when the job finishes.
• Do not use Claude Code's in-session CronCreate or /loop for anything that must survive a restart.
• Confirm a new cron by the artifact its first run produces, not by its presence in the list.

9. Logs and state

10. Changing the harness safely

10.1 What needs approval

10.2 Habits that keep changes reversible

11. CI and the ship chain

11.1 Continuous integration

The framework ships two GitHub Actions workflows in .github/workflows/:

• ci.yml: typecheck and build on push and pull request.
• leak-guard.yml: scans for operational leaks (secrets, private paths) on pull requests and pushes to main.

CI runs only on code pushed to GitHub. A local-only checkout gets the same checks from npm run build && npm test by hand.

11.2 Shipping a website

Rollback: on candidate failure, production is untouched. After exit 5 (live and wrong), promote the previous deployment again with vercel promote or re-point the alias.

11.3 Deploy rules

12. Troubleshooting quick table

Known limitations

• Lifecycle commands default to the default instance. Multi-instance installs must pass --instance every time.
• cortextos dashboard without --build runs a development server. Bind it to localhost or a private network.
• CI does not run on changes that stay in a local checkout.
• The ship wrapper's default deploy command targets Vercel. Other hosts need --deploy-cmd and their own promote step.
• The ship gate hook matches command patterns. A deploy run through a script with an unrelated name is not matched; route deploys through the wrapper.

Source files

• README.md
• CLAUDE.md
• package.json
• ecosystem.config.js
• install.mjs
• src/cli/
• src/bus/crons.ts
• src/bus/crons-schema.ts
• src/daemon/agent-manager.ts
• src/telegram/transcribe.ts
• scripts/install-whisper-model.sh
• scripts/install-windows-pm2-startup.ps1
• .github/workflows/ci.yml
• .github/workflows/leak-guard.yml
• templates/