Local Development

Local Dev Stack

Full stack in one command.

Docker Compose orchestrates all services. Or run the API directly with uvicorn for faster iteration.

Cache / Queue

Redis

:6379

reads

←

Main API

Constellation

:3007

calls

←

Clients

CLI / Browser

constellation CLI
HTTP / MCP

Docs Site

Docusaurus

:3008

independent service

Docker Compose orchestrates Redis + Constellation API + Docs

---

What & Why

There are two ways to run Octopus locally:

Mode	Command	Best for
Full Docker Compose	make start	Mirrors production; recommended default
Direct uvicorn	make dev-api	Faster iteration, no Docker overhead

Both modes use the same .env file and connect to the same Redis instance (Docker-managed or local).

---

Setup Guide

Step 1 — Clone and install

git clone <repo-url> octopus
cd octopus
cp .env.example .env
uv sync

uv sync at the workspace root installs all three workspace packages (constellation, CLI, docs tooling) into a shared virtual environment.

Step 2 — Configure .env

$EDITOR .env

At minimum, set these required variables before starting any service:

Variable	Description
REDIS_URL	Redis connection string — redis://localhost:6379 for local Docker
JWT_SECRET	Shared secret for signing JWTs (or use JWT_PUBLIC_KEY for RS256)
CONSTELLATION_SERVER_URL	Base URL the CLI sends requests to — http://localhost:3007

See the full env vars reference below for per-integration variables.

Step 3 — Start services

make start
# or equivalently:
docker-compose up -d

This starts Redis, the Constellation API, and the Docs site in detached mode. Tail logs at any time with:

make logs

Step 4 — Verify the API

curl http://localhost:3007/health

Expected response:

{"status": "ok"}

If the API is not responding, check logs with make logs and ensure all required env vars are set.

Step 5 — Test the CLI

constellation --help

The CLI reads CONSTELLATION_SERVER_URL from .env (or the environment). If you see a connection error, confirm the API is running and CONSTELLATION_SERVER_URL=http://localhost:3007 is set.

To install the CLI in editable mode for local development:

make dev-cli
# equivalent to: uv pip install -e apps/cli

Step 6 — Open the docs site

Navigate to http://localhost:3008 in your browser. The Docusaurus dev server supports hot reload — edits to .mdx files are reflected immediately.

To build the docs site statically:

make build-docs
# or: cd apps/docs && npm run build

---

Make Commands Cheatsheet

Makefile Reference

40+ commands — the ones you'll actually use

Setup

make installuv sync all workspace packages

make migraterun DB migrations

make dev-cliinstall CLI in editable mode

Services

make startdocker-compose up -d

make stopdocker-compose down

make logstail all service logs

make shellbash into constellation container

Development

make dev-apirun API via uvicorn directly

make build-docsbuild Docusaurus static site

Testing

make testrun integration tests

Code Quality

make lintruff check

make formatruff format

make typecheckpyright static analysis

---

Reference

Env Vars Reference

Core (Required)

Variable	Required	Description	Example
REDIS_URL	Yes	Redis connection string	redis://localhost:6379
JWT_SECRET	Yes*	Shared secret for HS256 JWT signing	supersecretkey
JWT_PUBLIC_KEY	Yes*	RS256 public key (alternative to JWT_SECRET)	PEM-encoded public key
CONSTELLATION_SERVER_URL	Yes (CLI)	Base URL the CLI targets	http://localhost:3007

*Either JWT_SECRET or JWT_PUBLIC_KEY must be set.

GitHub

Variable	Required	Description	Example
GITHUB_CLIENT_ID	Yes	OAuth App client ID	Iv1.abc123
GITHUB_CLIENT_SECRET	Yes	OAuth App client secret	abc123def456

Jira

Variable	Required	Description	Example
JIRA_CLIENT_ID	Yes	Atlassian OAuth 2.0 client ID	abc123
JIRA_CLIENT_SECRET	Yes	Atlassian OAuth 2.0 client secret	secret123
JIRA_CLOUD_URL	Yes	Your Jira Cloud base URL	https://yourorg.atlassian.net

Slack

Variable	Required	Description	Example
SLACK_CLIENT_ID	Yes	Slack app client ID	123456.789012
SLACK_CLIENT_SECRET	Yes	Slack app client secret	abc123def456
SLACK_SIGNING_SECRET	Yes	Used to verify Slack webhook payloads	abc123

Google (Gmail, Calendar, Drive)

Variable	Required	Description	Example
GOOGLE_CLIENT_ID	Yes	Google OAuth 2.0 client ID	12345.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET	Yes	Google OAuth 2.0 client secret	GOCSPX-abc123

Microsoft 365

Variable	Required	Description	Example
MICROSOFT_TENANT_ID	Yes	Azure AD tenant ID	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
MICROSOFT_CLIENT_ID	Yes	Azure app (client) ID	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
MICROSOFT_CLIENT_SECRET	Yes	Azure app client secret	abc~123DEF

---

Port Reference

Port	Service	Notes
3007	Constellation API	Main HTTP API, health check at /health
3008	Docs site	Docusaurus dev server with hot reload
6379	Redis	Persistent volume mounted at ./data/redis

---

Direct uvicorn (no Docker)

Use make dev-api or run directly for rapid iteration without Docker:

# Run the Constellation API directly
uv run python -m uvicorn apps.constellation.app.main:app --port 3007 --reload

# Or via make
make dev-api

Ensure Redis is accessible at REDIS_URL before starting — you can still use the Docker-managed Redis while running the API outside Docker:

docker-compose up -d redis
make dev-api

Run the CLI from source in editable mode:

make dev-cli
uv run constellation --help