Quickstart - Poindexter

This walkthrough takes a clean machine to a running Poindexter pipeline. It covers the four checkpoints that matter — bootstrap, Docker stack up, health verified, and a first task generated. For the long-form version with every verification command, see operations/local-development-setup.

Poindexter is built and tested against Windows 11 + WSL2 + Docker Desktop with an NVIDIA GPU. macOS and Linux should work — the steps are identical — but the image-gen server expects CUDA, so on machines without an NVIDIA card the image-generation step degrades to placeholders. Everything else is platform neutral.

The full stack pulls about 21 GB of LLM weights on first run and the image-gen server expects roughly 16 GB of VRAM to run alongside Ollama. If you’re on a smaller card, stop the image-gen container and let Pexels fill the image slot.

Prerequisites

Tool	Version	Required
Docker Desktop	4.26+	Yes
Ollama	0.1.40+	Yes
Python	3.13+	Yes
Node.js	22+	Frontend only
GPU	8 GB VRAM+	Recommended

Steps

Clone and bootstrap

Install the Python package, then run the bootstrap CLI. The wizard writes ~/.poindexter/bootstrap.toml (database URL plus the few machine secrets Docker needs) and provisions the initial OAuth client.

Windows (Git Bash)
macOS / Linux

git clone https://github.com/Glad-Labs/poindexter.git
cd poindexter
pip install -e src/cofounder_agent
poindexter setup --auto

git clone https://github.com/Glad-Labs/poindexter.git
cd poindexter
pip install -e src/cofounder_agent
poindexter setup --auto

--auto spins up a local Docker Postgres with a generated password. To point at an existing Postgres, run poindexter setup --db-url postgresql://... instead.

Pull AI models

Ollama serves the writer and reviewer LLMs plus the embedding model. The pulls below total about 21 GB — they only happen once.

ollama pull gemma3:27b        # QA reviews + fallback critic (16 GB)
ollama pull qwen3:8b          # fast tasks: SEO, image decisions (5 GB)
ollama pull nomic-embed-text  # embeddings (274 MB)

For better writing quality, pull a larger writer model too:

ollama pull qwen3:30b         # 18 GB

Bring the stack up

The launcher reads bootstrap.toml, exports the values as env vars for the Compose file, and starts the worker, brain daemon, Postgres, Grafana, image-gen server, Prefect, Langfuse, GlitchTip, and the observability stack.

Windows (Git Bash)
macOS / Linux

bash scripts/start-stack.sh up -d

bash scripts/start-stack.sh up -d

First boot takes a few minutes — Docker pulls all the images, Postgres runs the baseline migration, and the worker waits for Ollama to warm up.

Verify health

Three quick checks confirm the stack is healthy.

# Worker — expect "status": "healthy"
curl http://localhost:8002/api/health

Open Grafana at http://localhost:3000 and load the Mission Control dashboard. The default credentials are printed during poindexter setup. Every panel should report green or “no data yet” — never red.Open Prefect at http://localhost:4200 and confirm the content_generation deployment is registered.

If /api/health returns a non-healthy component, check docker logs poindexter-worker and consult operations/troubleshooting before moving on.

Trigger a first task

Mint a JWT for the CLI OAuth client provisioned during setup, then POST a topic. The pipeline pulls the task through pending → in_progress → awaiting_approval in a few minutes.

JWT=$(poindexter auth mint-token \
  --client-id <pdx_xxx> --client-secret <secret>)

curl -X POST http://localhost:8002/api/tasks \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"topic": "Why Docker changed everything", "category": "technology"}'

Follow along live:

docker logs -f poindexter-worker

When the task lands in awaiting_approval, approve it from the CLI:

poindexter tasks approve <task_id>

Architecture overview

The kernel/module/capability structure, the LangGraph pipeline, the six QA rails — how the parts fit.

Operations runbooks

Day-2 work: troubleshooting, incident response, backups, secret rotation.

CLI reference

Every poindexter subcommand with flags and examples.

Extend with plugins

Add a Stage, Reviewer, Publishing Adapter, Tap, or Module.

​Prerequisites

​Steps

​Next

Architecture overview

Operations runbooks

CLI reference

Extend with plugins

Prerequisites

Steps

Next