Installation

This page is for the operator standing up Upwarden. If you’re a developer who just needs to point a package manager at an existing Upwarden, see Quickstart.

What you need

Three datastores and one outbound dependency, all stable mature components:

Component	Used for	Notes
PostgreSQL 17+ with pgvector	Audit log, policy, scanner verdicts, embedding index	pgvector is required (the scanner does similarity search over package content embeddings).
Redis 7+	Per-request rate limiting, manifest cache, idempotency keys, fast-pass coordination	Cluster mode supported via REDIS_CLUSTER_MODE=true.
Object storage (GCS by default)	Tarball staging for the scanner	Configured via GCS_BUCKET + GCS_KEY_FILE.
Embedding endpoint	Vector embeddings for the similarity scanner	OpenAI-compatible API (EMBEDDING_ENDPOINT, EMBEDDING_MODEL, EMBEDDING_FORMAT).

A Stytch B2B account is optional — only the dashboard’s hosted-auth surface needs it. Self-hosters running with the admin-token bearer can skip it.

Run the container

Upwarden ships as a single image. The simplest path is docker compose:

git clone https://github.com/upwarden-io/upwarden.git
cd upwarden
cp .env.example .env
# Edit .env for DATABASE_URL, REDIS_URL, GCS_BUCKET, EMBEDDING_ENDPOINT, etc.
docker compose up -d

The compose file boots the engine + a local Postgres + a local Redis suitable for evaluation; replace those with managed services for production.

For Kubernetes the manifests in k8s/ are the reference — they’re the same ones Upwarden runs in production. Edit the image tag, the secret references, and the ingress hostnames to your environment.

First-boot checks

The engine runs bun run db:migrate automatically on container start; the migrations are forward-only and idempotent. To verify it came up:

curl -fsS https://npm.pkg.<your-domain>/healthz
# {"ok":true}

See Verify it’s working for the full three-step proof-it-blocks check.

Configuration reference

Every environment variable Upwarden reads is in the auto-generated reference. The variables you almost certainly need to set in production:

• DATABASE_URL, REDIS_URL — your managed datastores
• GCS_BUCKET (or GCS_KEY_FILE if running outside GCP) — scanner staging
• EMBEDDING_ENDPOINT + EMBEDDING_MODEL — your embedding provider
• SCANNER_ENABLED=true — the scanner is off by default for cold-start
• ADMIN_API_TOKEN — the admin bearer for the JSON admin API + the dashboard cookie
• STYTCH_* — only if you’re using the hosted dashboard auth path

What’s next

• Create your first key — mint a tenant + project + vk_ key for a developer.
• Quickstart — wire that key into a package manager.
• Verify it’s working — confirm the install + the block path.