</p>

Praetor

![CI](https://github.com/chaochungkuo/praetor/actions/workflows/ci.yml)

![Docker Build](https://github.com/chaochungkuo/praetor/actions/workflows/docker-build.yml)

![CodeQL](https://github.com/chaochungkuo/praetor/actions/workflows/codeql.yml)

![Pages](https://chaochungkuo.github.io/praetor/)

![OpenSSF Scorecard](https://securityscorecards.dev/viewer/?uri=github.com/chaochungkuo/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:

Release readiness:

pixi install
pixi run release-readiness

This writes docs/RELEASE_READINESS_REPORT.md.

Documentation

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.