Skip to content

DOCKER_README.md

Latest commit

 

History

History
306 lines (216 loc) · 11.6 KB

DOCKER_README.md

File metadata and controls

306 lines (216 loc) · 11.6 KB

Manifest

Docker pulls   GitHub stars   license   Discord

What is Manifest?

Manifest is a smart model router for personal AI agents like OpenClaw, Hermes, or anything speaking the OpenAI-compatible HTTP API. It sits between your agent and your LLM providers, scores each request, and routes it to the cheapest model that can handle it. Simple questions go to fast, cheap models. Hard problems go to expensive ones. You save money without thinking about it.

  • Route requests to the right model: cut costs up to 70%
  • Automatic fallbacks: if a model fails, the next one picks up
  • Set limits: don't exceed your budget
  • Self-hosted: your requests, your providers, your data

manifest-gh

Table of contents

Supported providers

Works with 300+ models across OpenAI, Anthropic, Google Gemini, DeepSeek, xAI, Mistral, Qwen, MiniMax, Kimi, Amazon Nova, Z.ai, OpenRouter, Ollama, and any provider with an OpenAI-compatible API. Connect with an API key, or reuse an existing paid subscription (ChatGPT Plus/Pro, Claude Max/Pro, GLM Coding Plan, etc.) where supported.

Manifest vs OpenRouter

Manifest OpenRouter
Architecture Your Manifest instance forwards to your providers Cloud proxy. All traffic goes through their servers
Cost Free 5% fee on every API call
Source code MIT, fully open Proprietary
Data privacy Self-hosted, no middleman Prompts and responses pass through a third party
Transparency Open scoring. You see why a model was chosen No visibility into routing decisions

Installation

Three paths, ordered from fastest to most hands-on. All three end in the same place: a running stack at http://localhost:3001 where you sign up. The first account you create becomes the admin. No demo credentials are pre-seeded.

Heads up on network binding. The bundled compose file binds port 3001 to 127.0.0.1 only, so the dashboard is reachable on the host machine but not over the LAN. See Custom port to expose it beyond localhost.

Option 1: Quickstart install script (recommended)

One command. The installer downloads the compose file, generates a secret, and brings up the stack. Give it about 30 seconds to boot.

bash <(curl -sSL https://raw.githubusercontent.com/mnfst/manifest/main/docker/install.sh)
Prefer to review the script before running it?

Download the script:

curl -sSLO https://raw.githubusercontent.com/mnfst/manifest/main/docker/install.sh

Review it (optional):

less install.sh

Run it:

bash install.sh

Useful flags: --dir <path> to install elsewhere, --dry-run to preview, --yes to skip the confirmation prompt.

Option 2: Docker Compose (manual)

Same underlying flow as the install script, but you drive it yourself so you can edit the config before booting the stack.

  1. Download the compose file and the env template into the same directory:
curl -O https://raw.githubusercontent.com/mnfst/manifest/main/docker/docker-compose.yml
curl -O https://raw.githubusercontent.com/mnfst/manifest/main/docker/.env.example
cp .env.example .env
  1. Open .env in your editor and set BETTER_AUTH_SECRET to a random string. You can generate one with:
openssl rand -hex 32

(Optional: to use a stronger database password, set BOTH POSTGRES_PASSWORD and DATABASE_URL in .env, they must agree, and any special characters in the password need to be percent-encoded in the URL.)

  1. Start the stack:
docker compose up -d

Give it about 30 seconds to boot.

  1. Open http://localhost:3001 and sign up. The first account you create becomes the admin.

To stop:

docker compose down       # keeps data
docker compose down -v    # deletes everything

Option 3: Docker Run (bring your own PostgreSQL)

If you already have PostgreSQL running, replace user, pass, and host with your actual database credentials, then run this in your terminal:

macOS / Linux (bash, zsh) 
docker run -d \
  -p 3001:3001 \
  -e DATABASE_URL=postgresql://user:pass@host:5432/manifest \
  -e BETTER_AUTH_SECRET=$(openssl rand -hex 32) \
  -e BETTER_AUTH_URL=http://localhost:3001 \
  -e AUTO_MIGRATE=true \
  manifestdotbuild/manifest
Windows (PowerShell) 
$secret = -join ((48..57 + 97..122) | Get-Random -Count 64 | ForEach-Object { [char]$_ })

docker run -d `
  -p 3001:3001 `
  -e DATABASE_URL=postgresql://user:pass@host:5432/manifest `
  -e BETTER_AUTH_SECRET=$secret `
  -e BETTER_AUTH_URL=http://localhost:3001 `
  -e AUTO_MIGRATE=true `
  manifestdotbuild/manifest
Windows (CMD)

Generate a 64-character hex secret with any tool you trust, then:

docker run -d ^
  -p 3001:3001 ^
  -e DATABASE_URL=postgresql://user:pass@host:5432/manifest ^
  -e BETTER_AUTH_SECRET=<your-64-char-secret> ^
  -e BETTER_AUTH_URL=http://localhost:3001 ^
  -e AUTO_MIGRATE=true ^
  manifestdotbuild/manifest

AUTO_MIGRATE=true runs database migrations on first boot. Then open http://localhost:3001 and sign up. The first account you create becomes the admin.

Verifying the image signature

Published images are signed with cosign keyless signing (Sigstore). Verify before pulling:

cosign verify manifestdotbuild/manifest:<version> \
  --certificate-identity-regexp="^https://github.com/mnfst/manifest/" \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com"

Custom port

If port 3001 is taken, change both the mapping and BETTER_AUTH_URL:

docker run -d \
  -p 8080:3001 \
  -e BETTER_AUTH_URL=http://localhost:8080 \
  ...

Or in docker-compose.yml:

ports:
  - '127.0.0.1:8080:3001'

…and in .env:

BETTER_AUTH_URL=http://localhost:8080

Exposing on the LAN

By default the compose file binds port 3001 to 127.0.0.1 only. The dashboard is reachable from the host but not from other machines on the network. To expose it on the LAN:

  1. Edit docker-compose.yml and change the ports line from "127.0.0.1:3001:3001" to "3001:3001".
  2. In .env, set BETTER_AUTH_URL to the host you'll reach the dashboard on, e.g. http://192.168.1.20:3001 or https://manifest.mydomain.com. This MUST match the URL in the browser or Better Auth will reject the login with "Invalid origin".
  3. docker compose up -d to apply.

If you see "Invalid origin" on the login page, BETTER_AUTH_URL doesn't match the URL you're accessing the dashboard on. The host matters as much as the port.

Image tags

Every release is published with the following tags:

  • {major}.{minor}.{patch} - fully pinned (e.g. 5.46.0)
  • {major}.{minor} - latest patch within a minor (e.g. 5.46)
  • {major} - latest minor+patch within a major (e.g. 5)
  • latest - latest stable release
  • sha-<short> - exact commit for rollback

Images are built for both linux/amd64 and linux/arm64.

Upgrading

Manifest ships a new image on every release. To upgrade an existing compose install:

docker compose pull
docker compose up -d

Database migrations run automatically on boot, no manual steps. Your data in the pgdata volume is preserved across upgrades. Pin to a specific major version (e.g. manifestdotbuild/manifest:5) in docker-compose.yml if you want control over when major upgrades happen.

Backup & persistence

All state lives in the pgdata named volume mounted at /var/lib/postgresql/data in the postgres service. Nothing else in the Manifest container is stateful.

Back up (from the host, with the stack running):

docker compose exec -T postgres pg_dump -U manifest manifest > manifest-backup-$(date +%F).sql

Restore into a fresh stack:

docker compose up -d postgres
cat manifest-backup-2026-04-12.sql | docker compose exec -T postgres psql -U manifest manifest
docker compose up -d

To list / remove the volume manually:

docker volume ls | grep pgdata
docker compose down -v    # ⚠  destroys all data

Environment variables

Variable Required Default Description
DATABASE_URL Yes -- PostgreSQL connection string
BETTER_AUTH_SECRET Yes -- Session signing secret (min 32 chars)
BETTER_AUTH_URL No http://localhost:3001 Public URL. Set this when using a custom port
PORT No 3001 Internal server port
NODE_ENV No production Set development for auto-migrations
SEED_DATA No false Seed demo data on startup

Full env var reference: github.com/mnfst/manifest

Links

License

MIT
⚡