Skip to content
ProtoMap Docs by HoundDog.ai

Self-Hosted Server

ProtoMap Server runs the full ProtoMap platform — the web app, the API, and the background worker — inside your own environment. It is distributed as the hounddogai/protomap Docker image and runs with Docker Compose. Your scans, and the code snippets they hold, stay on your network.

The services of a scanned repository, and how they call each other

What Runs

Section titled “What Runs”
Service Role
proxy Serves the platform and the API on one address. The only service that publishes a port.
server The API and the platform. Applies database migrations when it starts.
worker Background jobs, such as building a new version of the shared graph after scans upload.
postgres The bundled PostgreSQL database, for trial installations. Production uses your own database.

Requirements

Section titled “Requirements”
  • Docker with Compose 2.23.1 or newer
  • At least 4 GB of RAM and 20 GB of disk space
  • git and curl

Installation

Section titled “Installation”

Clone the public hounddogai/protomap repository and run the installer:

bash
git clone https://github.com/hounddogai/protomap.git
cd protomap
./self-hosted/scripts/install.sh

Run the commands on this page, and on the other self-hosting pages, from protomap, the root of the clone.

The installer asks you to choose an installation type:

  1. Trial — the quickest way to try ProtoMap. PostgreSQL runs as a bundled container, and the CLI on this computer is logged in for you.
  2. Production — connects ProtoMap to your own PostgreSQL 18 (or newer) database. You enter its connection URL, in the form postgres://USER:PASSWORD@HOST:PORT/DATABASE.

It also asks for the port to serve ProtoMap on (3300 by default). Then it writes your settings, with generated secrets, to self-hosted/.env, starts the stack, and installs the ProtoMap CLI.

First-Run Setup

Section titled “First-Run Setup”

When the installation finishes:

  1. Open the address the installer prints, such as http://localhost:3300, or this computer’s address from another computer.
  2. Enter the one-time setup key the installer prints. If you missed it, it is PROTOMAP_SETUP_KEY in self-hosted/.env.
  3. Create your organization and its owner account.

Setup then walks you through connecting an AI provider for the assistant and installing the CLI. You become the server owner, who manages server-wide settings.

Run Your First Scan

Section titled “Run Your First Scan”

In Trial mode, the CLI is already logged in as the owner, so you can scan a repository right away:

bash
protomap scan /path/to/repository

In Production mode, log in first:

bash
protomap login --server=http://<your server>:3300
protomap scan /path/to/repository

If the installer said the CLI is not on your PATH yet, open a new terminal first. See Scanning for what a scan reads and who sees it.

Next Steps

Section titled “Next Steps”