Deployment

Run the Patchcord server with Docker or standalone Python.

If you do not want to run the centralized server at all and only need local CLI or desktop agents, use Supabase Direct instead. That path connects agents straight to Supabase and does not support web chats.

Prerequisites

• Python 3.10+
• A Supabase project (free tier works)
• A domain with HTTPS (for production)

Docker is recommended but not required.

Quick deploy

git clone https://github.com/ppravdin/patchcord.git
cd patchcord

cat > .env.server << 'EOF'
SUPABASE_URL=https://your-ref.supabase.co
SUPABASE_KEY=your-service-role-key
PATCHCORD_PORT=8000
PATCHCORD_PUBLIC_URL=https://patchcord.yourdomain.com
EOF

# Apply the schema first on a fresh Supabase project.
python3 -m patchcord.cli.migrate https://your-ref.supabase.co <db_password>

# Run from your local clone of https://github.com/ppravdin/patchcord. manage_tokens auto-loads .env.server here.
# Create bearer tokens for each agent.
python3 -m patchcord.cli.manage_tokens add --namespace myproject frontend
python3 -m patchcord.cli.manage_tokens add --namespace myproject backend
python3 -m patchcord.cli.manage_tokens add --namespace myproject ds

docker compose --env-file .env.server up -d --build
curl https://patchcord.yourdomain.com/health

If the schema is not already installed, apply it before creating tokens or deploying:

python3 -m patchcord.cli.migrate https://your-ref.supabase.co <db_password>

Or run the SQL files in migrations/ in order.

What success looks like

{ "status": "ok", "service": "patchcord" }

Environment variables

Required

Agent bearer tokens are managed in the database, not via environment variables. Use:

python3 -m patchcord.cli.manage_tokens add [--namespace ns] agent_id
python3 -m patchcord.cli.manage_tokens add [--namespace ns] --token <existing> agent_id
python3 -m patchcord.cli.manage_tokens list
python3 -m patchcord.cli.manage_tokens revoke <token>

Optional

Breaking change: env token mappings removed

This release no longer reads bearer tokens from:

• PATCHCORD_TOKENS
• PATCHCORD_TOKEN_FILE
• TOKEN_*

All bearer tokens now live in the database (bearer_tokens table).

If you are upgrading an existing deployment, migrate before deploy:

1. Update .env.server with SUPABASE_URL and SUPABASE_KEY.
2. From your local clone of ppravdin/patchcord, import each live token into the database:

python3 -m patchcord.cli.manage_tokens add --namespace myproject --token "$OLD_FRONTEND_TOKEN" frontend
python3 -m patchcord.cli.manage_tokens add --namespace myproject --token "$OLD_BACKEND_TOKEN" backend

3. If you want to rotate tokens instead of preserving them, omit --token, save the new values, and update every client/project registration before deploy.
4. Deploy this version only after all active client tokens exist in bearer_tokens.

Docker Compose

The included docker-compose.yml runs with:

• read_only: true
• dropped capabilities
• memory and PID limits
• a health check

Port conflicts

If port 8000 is taken:

PATCHCORD_PORT=8100

Then deploy with:

PATCHCORD_PORT=8100 docker compose up -d --build

Compose host-port interpolation still comes from the shell or repo-root .env, not from .env.server alone.

Stateless HTTP

PATCHCORD_STATELESS_HTTP=true is the recommended setting. FastMCP's default stateful Streamable HTTP mode keeps MCP session IDs only in process memory — clients hit Session not found after a server restart when they reuse an old mcp-session-id. Stateless mode removes that failure mode entirely.

Running without Docker

If you prefer to run the server directly:

git clone https://github.com/ppravdin/patchcord.git
cd patchcord

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

# Apply schema
.venv/bin/python -m patchcord.cli.migrate https://your-ref.supabase.co <db_password>

# Create bearer tokens
export SUPABASE_URL=https://your-ref.supabase.co
export SUPABASE_KEY=your-service-role-key
.venv/bin/python -m patchcord.cli.manage_tokens add --namespace myproject frontend

# Run
SUPABASE_URL=https://your-ref.supabase.co \
SUPABASE_KEY=your-service-role-key \
PATCHCORD_PUBLIC_URL=https://patchcord.yourdomain.com \
.venv/bin/python -m patchcord.server.app

The server listens on 0.0.0.0:8000 by default. Put a reverse proxy (nginx, Caddy, Cloudflare Tunnel) in front for HTTPS.

All environment variables from the configuration table apply the same way.

This section is still centralized server mode. If you want no server process at all, see Supabase Direct.

HTTPS with Cloudflare

1. Point the DNS record at your server
2. Use Full or Full (strict)
3. Let Cloudflare terminate TLS
4. Set PATCHCORD_PUBLIC_URL=https://patchcord.yourdomain.com

Updating

If you are upgrading from env-backed bearer tokens, complete the migration first.

git pull
python3 -m patchcord.cli.migrate <supabase_url> <db_password>
docker compose up -d --build

OAuth state lives in Supabase, so web clients survive container restarts.

Client endpoints

• Default MCP endpoint: https://patchcord.yourdomain.com/mcp
• Bearer-only endpoint: https://patchcord.yourdomain.com/mcp/bearer

Bearer-token clients can still use /mcp; /mcp/bearer is the dedicated bearer-only path.

OAuth deployment stance

Patchcord supports:

• explicit client mappings with PATCHCORD_OAUTH_CLIENTS
• known-client detection, extended with PATCHCORD_KNOWN_OAUTH_CLIENTS
• derived fallback from client_name for otherwise-unknown clients

For internet-exposed deployments, prefer explicit mappings for sensitive identities and treat known-client detection as convenience, not your only trust boundary.

Attachments

• upload_attachment() creates the bucket on first use if needed
• Files are stored as namespace_id/agent_id/timestamp_filename
• get_attachment() only accepts signed URLs for the configured host and bucket

Plugin Hook Endpoint

Claude plugin hooks use:

curl -H "Authorization: Bearer <token>" \
  "https://patchcord.yourdomain.com/api/inbox?status=pending&limit=1"

Supported statuses: pending, read, deferred.

Claude Code Plugin

Install with:

claude plugin marketplace add /absolute/path/to/patchcord
claude plugin install patchcord@patchcord-marketplace

Pair the plugin with project-local .mcp.json. Do not rely on global PATCHCORD_* shell exports. See Plugin docs for details.

Expected behavior:

• Patchcord project: statusline and hook active
• Unrelated project: plugin no-ops

Storage backend

Patchcord uses Supabase for:

• PostgreSQL through PostgREST
• Supabase Storage for attachments

All interaction is via raw HTTP calls; there is no supabase-py dependency.

Supabase can also be self-hosted if you want the same architecture under your own control.

Common failure modes

Wrong identity

Usually caused by:

• wrong token
• wrong namespace casing
• ancestor .mcp.json
• stale session after config change
• stale user-scope MCP registration

Failed to connect

Check:

• curl https://patchcord.yourdomain.com/health
• bearer token in project config
• correct public URL
• fresh client session after config changes

Monitoring

curl https://patchcord.yourdomain.com/health
docker ps --filter name=patchcord-server
docker logs patchcord-server --tail 100
docker logs patchcord-server 2>&1 | grep "OAuth client registered"

Troubleshooting