Praetor

Praetor is a local-first AI company operating system for solo founders and small teams.

Stop managing a flat crowd of AI agents. Run work through one AI CEO. Praetor turns founder intent into projects, missions, agent teams, visible workspace files, meetings, decisions, review cycles, and owner approval checkpoints.

Praetor is early software. It is useful for local evaluation and development, but it is not a hosted enterprise system and it does not claim full autonomy.

Documentation

• User Manual: installation, first-run setup, runtime choices, workspace use, approvals, connectors, backup, and troubleshooting.
• Internal Design and Maintainer Docs: product decisions, architecture, UI principles, security specs, roadmap, and implementation references.

What Praetor Does

• AI company model: CEO, managers, specialist agents, reporting lines, and responsibility chains.
• Project dashboard: project portfolio, health, progress, stage board, timeline, usage, cost, and decision ledger.
• Mission workspace: real local folders for Projects/, Missions/, Wiki/, Decisions/, and Archive/ so users can inspect files directly.
• Agent organization console: agent org chart, active sections, blockers, manager/coworker evaluation input, and improvement history.
• Meetings and decisions: AI meetings have owners, proposals, discussion, dissent, decisions, linked files, and action items.
• Codex and browser controls: each executor task uses a fresh section; browser usage has first-use authorization and durable QA evidence.
• Release readiness: smoke matrix, route gate, frontend build checks, app smoke, packaging smoke, and generated readiness report.

Quickstart

Use this path when testing Praetor from the GitHub page on a fresh machine.

Requirements

• Docker Desktop or Docker Engine
• Git
• macOS, Linux, or Windows with WSL 2

Start Docker before running the installer.

Fresh Install From GitHub

Install and start Praetor locally:

curl -fsSL https://raw.githubusercontent.com/chaochungkuo/praetor/main/scripts/install.sh | sh

Then open the setup URL printed in your terminal.

The installer prints the App URL, workspace path, doctor command, backup command, and executor setup command. The default local app URL is:

http://127.0.0.1:9741/app/praetor

The default one-line install creates:

• app source at ~/.praetor/praetor
• private app state at ~/.praetor/data
• visible company workspace at ~/praetor-workspace
• local Docker app at http://127.0.0.1:9741
• one-time setup token for first-run onboarding

Clean Reinstall

Use this when you want to delete the existing local Praetor company and start again with a new owner account, password, settings, memory, and workspace.

If the current install is still working, run:

~/.praetor/praetor/scripts/praetor.sh uninstall --purge

This removes:

~/.praetor/praetor
~/.praetor/data
~/praetor-workspace

If the old script is broken or missing, remove the local install manually:

docker compose -f ~/.praetor/praetor/compose.app.yaml down --remove-orphans || true
rm -rf ~/.praetor
rm -rf ~/praetor-workspace

Then run the fresh install command again:

curl -fsSL https://raw.githubusercontent.com/chaochungkuo/praetor/main/scripts/install.sh | sh

First-Run Setup

Open the setup URL printed by the installer and complete onboarding:

1. Confirm the local app URL.
2. Choose the visible company workspace folder.
3. Choose an AI runtime: dry-run demo, API key, or local Codex bridge.
4. Review the starter AI company org chart and approval boundaries.
5. Create the owner login and start the first mission.

Recommended first test settings:

• Workspace: keep the default ~/praetor-workspace unless you intentionally want a different local folder.
• Runtime: choose Dry-run demo provider if you do not want to enter an API key during the first test.
• Runtime with API: choose OpenAI, Anthropic, or an OpenAI-compatible gateway only if you already have a key ready.
• Runtime with Codex: choose Local subscription executor later, after the host Codex bridge is configured.
• Approval boundaries: keep sensitive actions approval-gated during the first install: deleting files, overwriting important files, external communication, spending money, shell commands, credentials, security, runtime, and workspace permission changes.

Owner account guidance:

• The owner account is local to this Praetor install.
• Clean reinstall with uninstall --purge deletes the old owner account and password hash.
• Use a password manager and create a new password for this local install.
• The current minimum password length is 10 characters; 16+ characters is recommended.
• Do not reuse a password from another service.

If you do not have an API key ready, choose Dry-run demo provider during onboarding. It produces deterministic local demo outputs without contacting an external model provider. Switch later to OpenAI, Anthropic, an OpenAI-compatible gateway, or a local subscription executor.

Verify The Install

After onboarding, run:

~/.praetor/praetor/scripts/praetor.sh doctor
~/.praetor/praetor/scripts/praetor.sh validate-install --json

Confirm that the visible workspace exists:

ls ~/praetor-workspace

The company workspace should contain or later generate these folders:

Projects/
Missions/
Wiki/
Decisions/
Archive/

Send a first CEO message from the terminal:

~/.praetor/praetor/scripts/praetor.sh ceo ask "What should I review first after installation?"

Install Choices

Most users should use the Docker quickstart above. It keeps the app local, repeatable, and easy to update.

Use Local Codex bridge only if you already use Codex CLI on the host with a ChatGPT subscription. Keep Codex logged in on the host; Praetor talks to it through a scoped loopback bridge.

Use the source developer path only when changing Praetor itself:

pixi install
pixi run app-serve

See docs/DEVELOPER_SETUP.md for the full developer workflow.

Workspace Visibility

Praetor is local-first. Company files live in the workspace root you choose during setup, and you can inspect them directly in Finder, File Explorer, or a terminal. The default root is:

~/praetor-workspace

Inside it, Praetor keeps durable company files under Projects/, Missions/, Wiki/, Decisions/, and Archive/. The File System Steward is responsible for naming hygiene, placement, missing-file checks, and archive suggestions.

Try The Demo Mission

Use the Missions page to paste this founder brief into the mission plan preview:

Prepare this repository for an open-source v0.1 release. Review the current repository, produce a release readiness report, update the project status, identify trust/security gaps, and recommend the next three contributor-friendly issues.

Praetor will preview the mission plan before creating it. The matching JSON payload is also available at:

examples/demo-mission-template.json

A static sample workspace is included at:

examples/praetor-release-workspace

Inspect it to see the intended file model: company memory in Wiki/, project outputs in Projects/, and mission evidence in Missions/.

Optional: Use A Local Subscription Executor Instead Of An API Key

If you already use Codex CLI with a ChatGPT subscription or Claude Code with a Claude subscription, connect a local executor bridge with:

~/.praetor/praetor/scripts/praetor.sh configure-executor codex

Use configure-executor claude_code for Claude Code. Then open Runtime, choose Local subscription executor, select the executor, and click Test connection. This keeps ChatGPT or Claude authentication inside the local CLI; Praetor only talks to a local praetor-execd bridge.

For normal local Docker use, do not log into Codex or Claude Code inside the container. Keep the executor authenticated on the host and let Praetor call it through the scoped host bridge.

Safer Manual Install

If you prefer to inspect the installer before running it:

curl -fsSLO https://raw.githubusercontent.com/chaochungkuo/praetor/main/scripts/install.sh
less install.sh
bash install.sh

Update

~/.praetor/praetor/scripts/praetor.sh update

Local Operator CLI

After installation, use one command surface for day-to-day local operations:

~/.praetor/praetor/scripts/praetor.sh doctor
~/.praetor/praetor/scripts/praetor.sh doctor --json
~/.praetor/praetor/scripts/praetor.sh doctor --repair
~/.praetor/praetor/scripts/praetor.sh validate-install --json
~/.praetor/praetor/scripts/praetor.sh onboard
~/.praetor/praetor/scripts/praetor.sh status
~/.praetor/praetor/scripts/praetor.sh run
~/.praetor/praetor/scripts/praetor.sh stop
~/.praetor/praetor/scripts/praetor.sh logs --follow
~/.praetor/praetor/scripts/praetor.sh reset-setup-token
~/.praetor/praetor/scripts/praetor.sh configure-executor codex
~/.praetor/praetor/scripts/praetor.sh connectors list
~/.praetor/praetor/scripts/praetor.sh connectors setup telegram
~/.praetor/praetor/scripts/praetor.sh connectors pair telegram
~/.praetor/praetor/scripts/praetor.sh connectors test telegram
~/.praetor/praetor/scripts/praetor.sh ceo ask "What should I review next?"
~/.praetor/praetor/scripts/praetor.sh backup

Uninstall

Remove the app but keep your data and workspace:

~/.praetor/praetor/scripts/praetor.sh uninstall

Remove the app, local state, and workspace:

~/.praetor/praetor/scripts/praetor.sh uninstall --purge

Praetor runs locally by default. It does not expose the app publicly unless you change the bind host or deploy it yourself.

Optional Telegram CEO Access

Praetor can connect a Telegram bot as an owner-only mobile channel for CEO chat, briefings, and approval notifications. Configure it from Settings -> CEO Connectors after first-run onboarding, or use the terminal connector commands.

Short version:

1. Create a Telegram bot with @BotFather.
2. Paste the bot token and a long webhook secret into Praetor Settings, or run praetor.sh connectors setup telegram.
3. Expose Praetor over HTTPS and set Telegram's webhook to https://YOUR_DOMAIN/integrations/telegram/webhook.
4. Generate a pairing code in Praetor or run praetor.sh connectors pair telegram, then send /link CODE to your bot from your Telegram account.

See docs/TELEGRAM_SETUP.md for the exact commands and safety notes.

For Developers

Developer setup, Pixi commands, smoke tests, bridge development, and source workflows live in:

• docs/DEVELOPER_SETUP.md
• docs/ADVANCED_DEPLOYMENT.md
• docs/INSTALL_CHECKLIST.md
• docs/QA_SMOKE_MATRIX.md

Release readiness:

pixi install
pixi run release-readiness

This writes docs/RELEASE_READINESS_REPORT.md.

Documentation

• GitHub Pages documentation site
• Public security review
• Privacy boundaries
• Install and recovery
• CEO external entry
• CEO connector backlog
• Backup and restore
• QA smoke matrix
• Release readiness report
• Current development roadmap
• Roadmap

Current Status

Praetor is still an active build-stage repo, not a finished consumer release. The current local evaluation path is now wired end-to-end: installer, onboarding, workspace files, dashboard, agent organization, meetings, Codex / browser controls, and release readiness checks all have working code paths and smoke coverage. The next practical step is a real fresh-machine install test with manual UI screenshots attached to the release readiness report.