Quickstart

ProxifAI is one Go binary plus PostgreSQL. The fastest path is docker compose up, which gets you a fully wired deployment — server, embedded NATS, Envoy proxy, OCI registry, and a Postgres — on http://localhost:3000.

Docker Compose (recommended)

git clone https://github.com/proxifai/proxifai-oss.git
cd proxifai-oss
docker network create proxifai-net   # one-time, used by agent containers
docker compose up -d

Open http://localhost:3000 and log in with admin@localhost / admin.

What’s running:

Service	Port	Role
proxifai	3000 (HTTP), 8082 (WS-TCP bridge)	The single Go binary — API, embedded SPA, embedded NATS
envoy	8080	Public proxy in front of agent containers; xDS-controlled
registry	5000	OCI image registry mirror used by pipelines
postgres	(internal)	Postgres 16; data persists in the pg-data volume

Tear it down with docker compose down. Volumes (pg-data, proxifai-data, registry-data) survive — wipe them with -v to start fresh.

Single-binary release

For a non-Docker host:

# Linux amd64; pick the right asset for your OS/arch
curl -L https://github.com/proxifai/proxifai-oss/releases/latest/download/proxifai-linux-amd64.tar.gz \
  | tar xz

export DATABASE_URL=postgres://user:pass@localhost:5432/proxifai
export JWT_SECRET=$(openssl rand -hex 32)
./proxifai

Required: a Postgres 16 reachable via DATABASE_URL, plus a Docker daemon (for spawning agent containers). Everything else — embedded NATS, the React SPA, Git protocol, OCI registry — is in the binary.

The companion pfai CLI ships separately (releases page for the pfai-* assets) — see CLI → Install.

Build from source

# Requires Go 1.25+, Bun, Docker, PostgreSQL 16
git clone https://github.com/proxifai/proxifai-oss.git
cd proxifai-oss

make install                    # Go modules + frontend deps via bun
make build                      # full build, web embedded into binary
                                # outputs ./bin/proxifai and ./bin/pfai

# Either run via make (starts postgres in docker for you):
make run

# …or run directly with your own Postgres:
DATABASE_URL=postgres://… ./bin/proxifai

For frontend + backend hot reload during development:

make dev                        # Postgres + Go backend on :3000 + Vite on :5173

The Vite dev server proxies API calls to the Go backend, so you point your browser at :5173 and edits to web/ reload instantly.

What you actually get

After login, the seed runs on first boot (db.SeedAdminUser and friends in cmd/proxifai/main.go):

• One organization — default, your active org
• One admin user — admin@localhost (override via ADMIN_EMAIL/ADMIN_PASSWORD)
• Default agents — claude-code, cursor, opencode, copilot, aider, gemini-cli (configured to consume their respective images)
• Example workflows — including the AI Chat system workflow and the summarizer
• Built-in event types — the 17-event catalog for trigger rules
• A handful of demo issues, sprints, and projects when DEV_MODE=true

You can clear demo data from Settings → General → Reset workspace once you’re ready to start fresh.

Common environment overrides

Variable	Default	When to set
DATABASE_URL	required (set by compose)	Always
JWT_SECRET	auto-generated on first boot	Production — use a long, persistent secret
PORT	3000	Behind a reverse proxy on a different port
BASE_URL	http://localhost:<PORT>	Redirects + Git clone URLs need a public hostname
BASE_DOMAIN	localhost	Subdomain routing target for agent ports ({id}-{port}.<BASE_DOMAIN>)
RUNTIME_TYPE	docker	kubernetes (Enterprise build), noop (tests)
DEV_MODE	unset	true enables demo seed data
ADMIN_EMAIL, ADMIN_PASSWORD	admin / admin	Override the seeded admin
OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET	unset	Enable SSO via Keycloak/Okta/etc.
KB_ENABLED	false	Enable the knowledge base (also requires Qdrant + Meilisearch + TEI)

Next steps