Axemere.ai

Linux: Debian and Ubuntu

For: IT and infrastructure teams installing Axemere Gateway on Debian or Ubuntu.

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

The APT repository is the recommended install method for bare-metal Debian and Ubuntu hosts. It enables apt upgrade to deliver new releases automatically.

Table of Contents

PostgreSQL Setup

PostgreSQL not included. This package installs only the gateway binary and systemd unit. You must provision a PostgreSQL 15+ instance separately before starting the service.

Generate a password first:

openssl rand -hex 16

Install PostgreSQL and create the database:

# 1. Install PostgreSQL
sudo apt install -y postgresql

# 2. Confirm the service is running
sudo systemctl enable --now postgresql
sudo systemctl status postgresql   # should show "active (running)"

# 3. Create the database user and database
sudo -u postgres psql <<'EOF'
CREATE USER mvgc_gateway WITH PASSWORD '<your-generated-password>';
CREATE DATABASE mvgc_gateway OWNER mvgc_gateway;
EOF

Your DATABASE_URL:

# Format: postgres://<user>[:<password>]@<host>[:<port>]/<database>?sslmode=<disable|require>
DATABASE_URL=postgres://mvgc_gateway:<your-generated-password>@localhost:5432/mvgc_gateway?sslmode=disable

See PostgreSQL Setup for Docker, cloud, and other options.

Installation

Primary: APT repository (recommended -- enables apt upgrade)

# 1. Add the signing key
curl -fsSL https://apt.axemere.ai/gpg.key \
  | sudo gpg --dearmor -o /etc/apt/keyrings/mvgc.gpg

# 2. Add the repository
echo "deb [signed-by=/etc/apt/keyrings/mvgc.gpg arch=$(dpkg --print-architecture)] \
  https://apt.axemere.ai stable main" \
  | sudo tee /etc/apt/sources.list.d/mvgc.list

# 3. Install
sudo apt update && sudo apt install mvgc-gateway

To upgrade to a new release later:

sudo apt update && sudo apt upgrade mvgc-gateway

Fallback: direct .deb download

For air-gapped or offline hosts without APT access, download and install the .deb directly.

Download the package to /tmp before installing. APT tries to read local .deb files as the unprivileged _apt user; files in your home directory are not readable by that user and trigger an "unsandboxed as root" notice. /tmp is world-readable and avoids this.

# Download to /tmp (adjust version and arch as needed)
curl -L -o /tmp/mvgc-gateway.deb \
  https://github.com/Axemere-LLC/mvgc-releases/releases/download/<version>/mvgc-gateway_<version>_linux_arm64.deb

# Install with dpkg (runs fully as root -- no sandbox warning)
sudo dpkg -i /tmp/mvgc-gateway.deb

The package installs:

PathContents
/usr/bin/mvgc-gatewayBinary
/lib/systemd/system/mvgc-gateway.servicesystemd unit
/etc/default/mvgc-gatewayEnvironment file (edit before first start)
/etc/mvgc/mvgc.yamlYAML config template (every option documented inline)
/etc/mvgc/policies/bundle.yamlSkeleton bundle (loaded on startup)
/etc/mvgc/policies/available/Add-on catalog (8 rule files, config|noreplace)
/etc/mvgc/policies/addons/Active add-ons (7 symlinks into available/)
/etc/mvgc/credentials/credentials.yamlCredential seed file (config|noreplace)
/etc/mvgc/workloads/workloads.yamlWorkload seed file (config|noreplace)
/var/lib/mvgc/Data directory (signing keys)
/var/log/mvgc/Log directory

The service runs as a mvgc system user created by systemd-sysusers during install.

Post-install Configuration

Configure the gateway using either the YAML config file or the environment file. Use the password you generated in the PostgreSQL Setup section above.

Option A -- YAML config file (recommended)

sudo nano /etc/mvgc/mvgc.yaml

Update these two fields at minimum (replace <your-generated-password> and <your-admin-token>):

database:
  # Format: postgres://<user>[:<password>]@<host>[:<port>]/<database>?sslmode=<disable|require>
  url: "postgres://mvgc_gateway:<your-generated-password>@localhost:5432/mvgc_gateway?sslmode=disable"

gateway:
  admin_token: "<your-admin-token>"

Option B -- environment file

sudo nano /etc/default/mvgc-gateway

Add these two lines:

# Format: postgres://<user>[:<password>]@<host>[:<port>]/<database>?sslmode=<disable|require>
DATABASE_URL=postgres://mvgc_gateway:<your-generated-password>@localhost:5432/mvgc_gateway?sslmode=disable
MVGC_ADMIN_TOKEN=<your-admin-token>

The package pre-configures MVGC_CONFIG=/etc/mvgc/mvgc.yaml in /etc/default/mvgc-gateway, so the systemd service picks up /etc/mvgc/mvgc.yaml automatically. You can still set individual environment variables in /etc/default/mvgc-gateway to override specific values without touching the YAML file. Environment variables always take precedence over the YAML config file.

Credentials and workloads

The package installs seed files at /etc/mvgc/credentials/credentials.yaml and /etc/mvgc/workloads/workloads.yaml. These files are loaded once on first start to populate the database. After that, the gateway reads from the database -- editing the YAML files alone has no effect.

To apply changes from the YAML file after first start, use the reload endpoint (upserts all credentials from the directory, overwriting existing database records):

curl -s -X POST http://localhost:7080/v1/admin/credentials/reload \
  -H "MVGC-Admin-Token: <your-admin-token>"

So the workflow for switching to inline credentials is:

  1. Edit /etc/mvgc/credentials/credentials.yaml (change mode: alias to mode: inline, put key in secret_ref)
  2. Call the reload endpoint above -- no restart needed

To update a single credential without touching the file, use the individual PUT endpoint:

curl -s -X PUT http://localhost:7080/v1/admin/credentials/cred-openai \
  -H "MVGC-Admin-Token: <your-admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"provider":"openai","mode":"inline","billing_owner":"customer","secret_ref":"sk-your-key"}'

Policy files

The package installs the skeleton bundle.yaml, the full add-on catalog in /etc/mvgc/policies/available/, and 7 default active symlinks in /etc/mvgc/policies/addons/. To enable or disable an add-on, use mvgc-gateway addon enable <name> or mvgc-gateway addon disable <name> and then restart the service. See the Policy Add-Ons section for the full catalog.

Execution records

The append-only record log defaults to /tmp/mvgc-records.jsonl for development installs. For production, set MVGC_RECORD_LOG_FILE=/var/log/mvgc/records.jsonl in /etc/default/mvgc-gateway. The /var/log/mvgc/ directory is created by the package.

Start / Stop / Restart

sudo systemctl enable --now mvgc-gateway   # start and persist across reboots
sudo systemctl stop mvgc-gateway           # stop
sudo systemctl restart mvgc-gateway        # restart after a config change

Verify

curl http://localhost:7080/healthz

Trusting the CA Certificate

When using SSL MITM proxy mode, install the gateway's CA certificate into the Ubuntu/Debian system trust store:

curl http://localhost:7080/v1/proxy/ca.crt > mvgc-proxy-ca.crt
sudo cp mvgc-proxy-ca.crt /usr/local/share/ca-certificates/mvgc-proxy-ca.crt
sudo update-ca-certificates

This makes all system tools (curl, wget, Python requests, Go HTTP clients) trust the gateway's CA certificate automatically.

Upgrading

sudo apt update && sudo apt upgrade mvgc-gateway
sudo systemctl restart mvgc-gateway

Schema migrations run automatically on startup. Take a Postgres backup before upgrading. See the Upgrading section in the overview for details on schema migrations and downgrade.

Console Dashboard

The web console is not available as a .deb package. On Linux, run it via Docker:

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

If you use the Docker Compose deployment, the console service is already included in docker-compose.yaml; no additional setup needed.

See Also