Praetor Local Deploy

This is the fastest way to run the current Praetor app with Docker.

It uses the current monolithic FastAPI app that serves both:

• browser UI
• JSON API

Prerequisites

• Docker Engine or Docker Desktop running
• a local workspace/ directory
• optional:

- OPENAI_API_KEY for API mode

- host praetor-execd for subscription executor mode

Start

Recommended one-command local install:

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

The installer prints:

• App URL
• setup URL
• workspace path
• state path
• scripts/praetor.sh doctor
• scripts/praetor.sh backup
• scripts/praetor.sh configure-executor codex

Manual Docker start:

docker compose -f compose.app.yaml up --build

Then open:

• http://127.0.0.1:9741/app/praetor

Environment

Common environment variables:

• PRAETOR_APP_BIND_HOST
• PRAETOR_APP_PORT
• PRAETOR_WORKSPACE_DIR
• PRAETOR_DATA_DIR
• PRAETOR_SESSION_SECRET
• PRAETOR_SETUP_TOKEN
• OPENAI_API_KEY
• ANTHROPIC_API_KEY
• PRAETOR_BRIDGE_BASE_URL
• PRAETOR_BRIDGE_TOKEN

Example:

export OPENAI_API_KEY=...
export PRAETOR_SESSION_SECRET="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
export PRAETOR_SETUP_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
docker compose -f compose.app.yaml up --build

Production-style overlay

If you want Docker secrets instead of plain environment variables:

mkdir -p secrets
python -c 'import secrets; print(secrets.token_urlsafe(32))' > secrets/praetor_session_secret.txt
python -c 'import secrets; print(secrets.token_urlsafe(32))' > secrets/praetor_setup_token.txt
python -c 'import secrets; print(secrets.token_urlsafe(32))' > secrets/praetor_bridge_token.txt
printf 'sk-...' > secrets/openai_api_key.txt

docker compose -f compose.app.yaml -f compose.app.production.yaml up --build -d

The current app supports *_FILE environment variables for:

• PRAETOR_SESSION_SECRET_FILE
• PRAETOR_SETUP_TOKEN_FILE
• PRAETOR_BRIDGE_TOKEN_FILE
• OPENAI_API_KEY_FILE
• ANTHROPIC_API_KEY_FILE

Subscription executor mode

If you want to use existing host-side tools such as Codex or Claude Code:

1. install and log into Codex or Claude Code on the host

2. run scripts/praetor.sh configure-executor codex to create the host bridge config

3. run praetor-execd on the host

4. point the container at it:

export PRAETOR_BRIDGE_BASE_URL=http://host.docker.internal:9417
export PRAETOR_BRIDGE_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
docker compose -f compose.app.yaml up --build

Do not use Docker as the normal place to log into Codex. The default design keeps Codex credentials and browser/session state on the host, then lets Docker call the host bridge with a scoped token and workspace path mapping. Logging into Codex inside Docker is only useful for an advanced all-in-container deployment where you intentionally manage those credentials inside the container.

Non-Docker development path

Use this path when developing Praetor itself:

pixi install
pixi run app

Then open http://127.0.0.1:9741/app/praetor.

Use the same workspace rule as Docker: choose one user-visible workspace root and keep Praetor company files inside it.

Notes

• This is the practical local deployment path for the current implementation.
• The split web / api / worker stack is now available in compose.yaml.
• The monolithic app stack remains the simplest path for first local use.