Configuration

ProtoMap Server reads its settings from self-hosted/.env. The installer writes it for you, and self-hosted/.env.example explains every setting. Keep the file private — it contains secrets.

After you change self-hosted/.env, apply it:

bash

docker compose --file self-hosted/compose.yaml up -d

Required Settings

Variable	Description
PROTOMAP_SETUP_KEY	At least 16 characters that create the owner’s account during first-run setup, while the server has no users. Generate one with openssl rand -hex 32.
PROTOMAP_SECRET_KEY	32 random bytes in hexadecimal that encrypt the secrets the server stores, such as AI provider API keys. Generate one with openssl rand -hex 32.
PROTOMAP_DATABASE_URL	The PostgreSQL connection URL: the bundled database or your own (see below).

Caution

Back up PROTOMAP_SECRET_KEY along with your database. Without it, the API keys ProtoMap stores cannot be read.

Database

Pick one of two options.

Option 1: Bundled PostgreSQL (recommended for trying ProtoMap). Docker Compose runs PostgreSQL for you:

self-hosted/.env

COMPOSE_PROFILES=postgres
POSTGRES_USER=protomap
POSTGRES_PASSWORD=<password>
POSTGRES_DB=protomap
PROTOMAP_DATABASE_URL=postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}

Change the user, password, and database before the first start of any deployment other than a local test. Use only ASCII letters, numbers, hyphens, periods, underscores, and tildes. An existing database volume keeps the credentials it was created with.

Option 2: Your own PostgreSQL (recommended for production). Use PostgreSQL 18 or newer, remove the bundled settings above, and set your database’s connection URL. The first start needs permission to create tables.

self-hosted/.env

PROTOMAP_DATABASE_URL=postgres://user:password@host:5432/database

HTTPS

By default, ProtoMap Server is reachable from other computers on your network over plain HTTP. For anything but a trial, put a proxy or load balancer that serves HTTPS in front of it, and set PROTOMAP_BIND_ADDRESS=127.0.0.1 so that only the proxy, on the same computer, can reach it. Then set PROTOMAP_PUBLIC_URL to the HTTPS address people open.

When the proxy reaches the stack from a public address, such as a cloud load balancer, list it in PROTOMAP_TRUSTED_PROXIES so ProtoMap believes the address and protocol it forwards.

Optional Settings

Variable	Default	Description
PROTOMAP_VERSION	latest	The release of the hounddogai/protomap image to run, such as 1.2.3.
PROTOMAP_PORT	3300	The published port.
PROTOMAP_BIND_ADDRESS	unset (every interface)	Set 127.0.0.1 to accept connections only from the Docker host, such as from a proxy on it that serves HTTPS.
PROTOMAP_PUBLIC_URL	the address setup ran at	The address people open ProtoMap at, which links in emails start with. Setting it here fixes it; otherwise server owners change it in the platform.
PROTOMAP_TRUSTED_PROXIES	private networks and the Docker host	Addresses or CIDR ranges, separated by spaces, of proxies whose forwarded headers to believe.
PROTOMAP_SMTP_URL	unset	The SMTP server that sends invitations and password resets, such as smtp://user:[email protected]:587.
PROTOMAP_SMTP_FROM	unset	Who those emails are from, such as ProtoMap <[email protected]>.
PROTOMAP_MODEL_CATALOG_URL	https://protomap.ai/model-catalog-v1.json	Where the server fetches the list of AI models it offers. Point it at a copy on your network, or set off to keep the bundled list.
PROTOMAP_API_DOCS	off	Set on to serve the API reference at /api/docs to anyone who reaches the server.

self-hosted/.env.example also covers settings for larger deployments, such as memory, database connections, and how many chat responses run at once.

Server Settings

The owner created during first-run setup is the first server owner. Server owners can see and join every organization on the server, and manage these settings in the platform under Settings › Server:

Section	What it holds
Address	The address people open ProtoMap at. Links in emails and the single sign-on Redirect URI start with it.
Email	The SMTP server that sends invitations and password resets: host, security (STARTTLS, TLS, or none), port, credentials, and sender. Send Test Email checks it.
Limits	Limits on repositories, private scans, storage, and queries. You can raise them, never below their defaults.
Server Owners	Add other server owners by the email of an existing account, or remove them.

A setting fixed in self-hosted/.env, such as PROTOMAP_PUBLIC_URL or PROTOMAP_SMTP_URL, takes precedence and cannot be changed in the platform.

Note

Without email, invitations and password resets are links that Owners and Admins copy and hand to people themselves.