Axemere.ai

Docker and Podman

For: Developers and IT engineers running Axemere Gateway in Docker or Podman containers.

IT Setup Overview | PostgreSQL Setup | Linux (Debian/Ubuntu) | Linux (RHEL/Fedora) | macOS | Docker/Podman | Kubernetes | Windows (WSL2) | Cloud

Multi-arch images (linux/amd64 + linux/arm64) are published to GHCR on every release:

ghcr.io/axemere-llc/mvgc-gateway:<version>
ghcr.io/axemere-llc/mvgc-console:<version>

The Docker Compose files (docker-compose.yaml and docker-compose.postgres.yaml) include both the gateway and console services. After docker compose up, the console dashboard is available at http://localhost:7091.

Table of Contents

Quick Start with Bundled Postgres

docker-compose.postgres.yaml starts a Postgres 16 container alongside the gateway -- no separate database required. docker-compose.yaml is a gateway-only variant for environments where you already have a PostgreSQL 15+ instance; set DATABASE_URL in .env to point at it.

# Download compose file and env template
curl -fsSL https://github.com/Axemere-LLC/mvgc-releases/releases/latest/download/docker-compose.postgres.yaml \
  -o docker-compose.yaml
curl -fsSL https://github.com/Axemere-LLC/mvgc-releases/releases/latest/download/default.env.example \
  -o .env

# Edit .env -- set MVGC_ADMIN_TOKEN at minimum (and optionally your AI provider keys)

# Starts gateway + Postgres 16 -- no separate DB setup required
docker compose up -d

Gateway Only (Bring Your Own Postgres)

If you already have a Postgres 15+ instance, use the gateway-only compose file instead of docker run:

curl -fsSL https://github.com/Axemere-LLC/mvgc-releases/releases/latest/download/docker-compose.yaml \
  -o docker-compose.yaml
curl -fsSL https://github.com/Axemere-LLC/mvgc-releases/releases/latest/download/default.env.example \
  -o .env

# Set DATABASE_URL and MVGC_ADMIN_TOKEN in .env, then:
docker compose up -d

Manual Docker Run

docker pull ghcr.io/axemere-llc/mvgc-gateway:latest

docker run -d --name mvgc-gateway \
  -e DATABASE_URL=postgres://<db-user>:<db-password>@host.docker.internal:5432/<db-name>?sslmode=disable \
  -e MVGC_ADMIN_TOKEN=<your-secret-admin-token> \
  -p 7080:7080 \
  ghcr.io/axemere-llc/mvgc-gateway:latest

Running the Console

The Docker Compose files already include the console service. After docker compose up, the dashboard is at http://localhost:7091. No additional setup required.

To run the console standalone alongside an existing gateway:

docker run -d --name mvgc-console \
  -e CONSOLE_GATEWAY_URL=http://localhost:7080 \
  -p 7091:7091 \
  ghcr.io/axemere-llc/mvgc-console:latest

Set CONSOLE_PASSWORD to require login (default: no auth):

docker run -d --name mvgc-console \
  -e CONSOLE_GATEWAY_URL=http://localhost:7080 \
  -e CONSOLE_PASSWORD=<your-password> \
  -p 7091:7091 \
  ghcr.io/axemere-llc/mvgc-console:latest

Podman (Rootless)

podman pull ghcr.io/axemere-llc/mvgc-gateway:latest

podman run --userns=keep-id -d --name mvgc-gateway \
  -e DATABASE_URL=postgres://<db-user>:<db-password>@host.containers.internal:5432/<db-name>?sslmode=disable \
  -e MVGC_ADMIN_TOKEN=<your-secret-admin-token> \
  -p 7080:7080 \
  ghcr.io/axemere-llc/mvgc-gateway:latest

Both docker-compose.yaml and docker-compose.postgres.yaml are compatible with both docker compose and podman-compose without modification. To pin a specific version, replace latest with a release tag (e.g., v0.3.5) or image digest.

Using a YAML Config File with Docker / Podman

For deployments with many options, you can use a mvgc.yaml config file instead of passing each option as an environment variable. Download the template from the releases page and mount it into the container:

# Download the config template
curl -fsSL https://github.com/Axemere-LLC/mvgc-releases/releases/latest/download/mvgc.yaml \
  -o /etc/mvgc/mvgc.yaml

# Edit the template (set database.url and gateway.admin_token at minimum)
nano /etc/mvgc/mvgc.yaml

# Mount it into the container
docker run -d --name mvgc-gateway \
  -v /etc/mvgc/mvgc.yaml:/etc/mvgc/mvgc.yaml:ro \
  -e MVGC_CONFIG=/etc/mvgc/mvgc.yaml \
  -p 7080:7080 \
  ghcr.io/axemere-llc/mvgc-gateway:latest

Environment variables always take precedence, so you can mount a base config file and override specific values with -e flags.

Customising Policy Files

The image ships with default policy files baked in at /configs/policies/, including the skeleton bundle.yaml, the add-on catalog in available/, and 7 active symlinks in addons/. When running standalone (no volume mount), the gateway uses these defaults immediately. To enable an add-on like claude-cli-proxy, run mvgc-gateway addon enable claude-cli-proxy inside the container and restart. If you need to supply your own policies, there are three options:

Option 1 -- Replace all policies with a directory mount:

docker run -d --name mvgc-gateway \
  -v /your/policies:/configs/policies:ro \
  -e MVGC_ADMIN_TOKEN=<your-secret-admin-token> \
  -p 7080:7080 \
  ghcr.io/axemere-llc/mvgc-gateway:latest

Option 2 -- Override a single policy file, keep the rest:

docker run -d --name mvgc-gateway \
  -v /your/bundle.yaml:/configs/policies/bundle.yaml:ro \
  -e MVGC_ADMIN_TOKEN=<your-secret-admin-token> \
  -p 7080:7080 \
  ghcr.io/axemere-llc/mvgc-gateway:latest

Option 3 -- Point to a completely different path:

docker run -d --name mvgc-gateway \
  -v /your/policies:/etc/mvgc/policies:ro \
  -e MVGC_POLICIES_DIR=/etc/mvgc/policies \
  -e MVGC_ADMIN_TOKEN=<your-secret-admin-token> \
  -p 7080:7080 \
  ghcr.io/axemere-llc/mvgc-gateway:latest

The three options above apply when running the container directly via docker run. The customer-facing compose files (docker-compose.yaml and docker-compose.postgres.yaml) do not mount a host ./configs directory -- the image's baked-in policy files at /configs/ are used as-is.

Record Log Persistence

To persist the execution record log across container restarts, mount a host volume and set the log path:

docker run -d --name mvgc-gateway \
  -v /host/path/for/records:/var/log/mvgc-records \
  -e MVGC_RECORD_LOG_FILE=/var/log/mvgc-records/records.jsonl \
  ...

Trusting the CA Certificate

Self-hosted deployments only. SSL MITM transparent proxy is available for self-hosted gateways. It is not yet available for the Managed Gateway (Axemere-hosted); support is planned for a future release.

When using SSL MITM proxy mode with Docker or Podman containers, mount the CA cert as a ConfigMap or volume and set SSL_CERT_FILE (or the equivalent env var for the runtime) to the mounted path.

For containers that need to make HTTPS calls through the proxy:

# Retrieve the CA cert from the gateway
curl http://localhost:7080/v1/proxy/ca.crt > mvgc-proxy-ca.crt

# Mount it into the client container
docker run -d --name my-app \
  -v $(pwd)/mvgc-proxy-ca.crt:/etc/ssl/certs/mvgc-proxy-ca.crt:ro \
  -e SSL_CERT_FILE=/etc/ssl/certs/mvgc-proxy-ca.crt \
  -e HTTPS_PROXY=http://mvgc-gateway:7080 \
  my-app:latest

Most AI SDK clients respect the system CA bundle or SSL_CERT_FILE.

For macOS and Linux desktop trust store setup, see the platform-specific guides: macOS, Linux (Debian/Ubuntu), Linux (RHEL/Fedora).

Configuring HTTP clients to use the proxy

Set HTTPS_PROXY to point at the gateway. Most HTTP client libraries (curl, Python requests, Node.js node-fetch, Go's http.DefaultTransport) respect this env var automatically:

export HTTPS_PROXY=http://localhost:7080

Replace localhost with your gateway container name (mvgc-gateway) when configuring client containers in the same Compose network.

See Also