Skip to content

Install the Open-Source Stack

After this page you have the full Preloop control plane — API, console, MCP firewall, and model gateway — running on your own machine or server under the Apache 2.0 license, with the first user created and public signup closed.

Prefer not to run anything?

Preloop Cloud is the hosted service with the same core features — see the Quick Start. Both paths use the same CLI and console.

Prerequisites

  • Docker with the Compose v2 plugin (the installer checks and tells you exactly what is wrong — see Troubleshooting)
  • macOS or Linux

1. Install and start the stack

curl -fsSL https://preloop.ai/install/oss | sh

https://preloop.ai/install/oss redirects to the latest release's install script (curl -L follows it; -fsSL already includes -L). The installer:

  1. Downloads the release Docker Compose file into ~/.preloop-oss and generates a .env with a SECRET_KEY and database password.
  2. Asks for your public URL (default http://localhost:3000). Give it an https:// URL on a public hostname and it terminates TLS for you with an nginx + certbot overlay (Let's Encrypt). PRELOOP_SKIP_TLS=1 if you terminate TLS yourself.
  3. Asks for SMTP settings — needed for approval emails, invitations, and password resets. Skippable (PRELOOP_SKIP_SMTP=1).
  4. Pulls images and starts the stack. Output is quiet; the full log is at ~/.preloop-oss/install.log.
  5. Offers to create the first user, then closes public registration (REGISTRATION_ENABLED=false) so a freshly exposed instance is never open to whoever finds it first. The user is created before registration closes — a failure leaves signup open rather than locking you out.

Default local ports:

  • Console: http://localhost:3000
  • API: http://localhost:8000
  • Model gateway: http://localhost:8001

If you skipped first-user creation, open the console and register — registration is open by default on a fresh database. Invite teammates from the console afterwards.

Unattended installs

Every prompt has an environment variable, so the whole install can run non-interactively:

curl -fsSL https://preloop.ai/install/oss | \
  PRELOOP_URL=https://preloop.example.com \
  PRELOOP_TLS_EMAIL=ops@example.com \
  PRELOOP_ADMIN_USERNAME=admin \
  PRELOOP_ADMIN_EMAIL=admin@example.com \
  PRELOOP_ADMIN_PASSWORD='a-strong-password' \
  PRELOOP_DISABLE_TELEMETRY=true \
  sh
Variable Purpose
PRELOOP_VERSION Pin a release instead of latest
PRELOOP_URL Public origin (enables the TLS overlay when https:// on a public hostname)
PRELOOP_TLS_EMAIL, PRELOOP_TLS_STAGING=1, PRELOOP_SKIP_TLS=1 Certificate options
PRELOOP_ADMIN_USERNAME / PRELOOP_ADMIN_EMAIL / PRELOOP_ADMIN_PASSWORD Unattended first-user creation (email is validated up front; the run fails fast on a malformed address)
PRELOOP_SKIP_ADMIN=1 Skip first-user creation, leave signups open
SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, SMTP_FROM, PRELOOP_SKIP_SMTP=1 Mail settings
PRELOOP_DISABLE_TELEMETRY=true No daily version check-in — set on every test/CI install
INSTALL_DIR Override ~/.preloop-oss

2. Connect the CLI to your instance

curl -fsSL https://preloop.ai/install/cli | sh
preloop login --url http://localhost:8000
preloop agents discover

The CLI stores the instance URL in ~/.preloop/config.yaml, so every later command targets your deployment. You can also set it per-command: PRELOOP_URL=http://localhost:8000 preloop login.

Managing the stack

cd ~/.preloop-oss

docker compose ps       # status
docker compose logs -f  # logs
docker compose down     # stop
docker compose up -d    # start again

Re-running the installer upgrades in place and preserves your configuration — see Upgrading Preloop for the full semantics (pre-upgrade database dumps land in ~/.preloop-oss/backups/).

Next steps

Editions

Preloop (open source, this page) is free forever. Preloop Cloud is the hosted service at preloop.ai. Preloop Enterprise adds RBAC and team management, budget policies, and FinOps workflows for self-hosted deployments — contact sales@preloop.ai.