Local Development

Prerequisites

Tool	Version	Check
Python	3.11+	python3 --version
Git	any	git --version
Docker	24+	docker --version
Docker Compose	v2+	docker compose version

Optional but recommended:

Tool	Purpose
uv	Fast Python package manager (replaces pip)
just	Command runner (like make but simpler)

Clone and install

git clone git@github.com:tappass/tappass.git
cd tappass

python3 -m venv .venv
source .venv/bin/activate

pip install -e ".[all,dev]"

This installs TapPass in editable mode with all optional dependencies and dev tools (pytest, ruff, mypy).

Environment setup

cp .env.example .env

Edit .env and add your OpenAI API key:

OPENAI_API_KEY=sk-...

All other variables have sensible defaults for local development.

Start the server

tappass up

The server starts on http://localhost:9620. The first run creates:

• A default governance pipeline (standard preset)
• A SQLite database (no PostgreSQL needed for dev)
• An admin API key (printed to console)

Run with Docker (full stack)

To test with the production stack locally (PostgreSQL, Redis, OPA, SPIRE):

cd deploy
cp .env.example .env.dev
# Edit .env.dev with your keys

docker compose -f docker-compose.dev.yml up -d

This starts all 7 services. Check health:

curl http://localhost:9620/health/ready

Run tests

# All tests
pytest tests/ -x -q

# Specific test file
pytest tests/test_pipeline.py -x -q

# With coverage
pytest tests/ --cov=tappass --cov-report=term-missing

# Only fast tests (skip integration)
pytest tests/ -x -q -m "not integration"

Test structure

tests/
├── test_pipeline.py         # Pipeline step tests
├── test_gateway.py          # HTTP endpoint tests
├── test_sdk.py              # SDK client tests
├── test_flags.py            # Governance flag tests
├── test_identity.py         # Auth/token tests
├── test_policy.py           # OPA integration tests
├── test_audit.py            # Audit trail tests
├── test_sandbox.py          # Sandbox/trust tier tests
├── conftest.py              # Shared fixtures
└── fixtures/                # Test data (prompts, configs)

Linting and formatting

# Lint
ruff check tappass/ tests/

# Format
ruff format tappass/ tests/

# Type check
mypy tappass/ --ignore-missing-imports

Making changes

Typical workflow

1. Create a branch: git checkout -b feat/my-feature
2. Make your changes
3. Run tests: pytest tests/ -x -q
4. Run linting: ruff check tappass/
5. Commit with a descriptive message
6. Push and create a PR

Adding a pipeline step

1. Create the step in tappass/pipeline/steps/
2. Register it in tappass/pipeline/registry.py
3. Add it to the appropriate preset in tappass/config/policies/rego/data.json
4. Write tests in tests/test_pipeline.py
5. Document in docs/site-docs/server/pipeline/steps.md

Adding an API endpoint

1. Create the route in tappass/gateway/routes/
2. Add request/response models in tappass/gateway/models/
3. Register in tappass/gateway/app.py
4. Write tests in tests/test_gateway.py
5. Document in docs/site-docs/server/api/

Modifying the SDK

1. SDK source is in sdks/python/tappass/
2. Changes must remain backward-compatible
3. Run SDK tests: pytest tests/test_sdk.py -x -q
4. Update docs in docs/site-docs/sdk/

Useful commands

Command	What it does
tappass up	Start server (interactive setup on first run)
tappass down	Stop server
tappass status	Check server health
tappass agents list	List registered agents
tappass agents add <name>	Register an agent, get API key
tappass assess	Run security assessment on current host
tappass quickstart	Start + register demo agent + print code

Debugging

Enable debug logging

TAPPASS_LOG_LEVEL=DEBUG tappass up

This prints every pipeline step execution, policy decision, and audit event.

Inspect a specific request

Every request gets a request_id in the response headers:

curl -v http://localhost:9620/v1/chat/completions \
  -H "Authorization: Bearer tp_..." \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"test"}]}'

Look for X-Request-Id in the response headers, then check logs for that ID.

Common issues

Problem	Fix
ModuleNotFoundError: tappass	Activate your venv: source .venv/bin/activate
Port 9620 in use	Kill the old process: lsof -ti :9620 | xargs kill
Tests fail with “OPA not reachable”	Start OPA: docker run -d -p 8181:8181 openpolicyagent/opa:1.14.0 run --server
OPENAI_API_KEY not set	Add it to your .env file
Database migration errors	Delete tappass.db and restart (dev only)