Quickstart: Linux

Axemere Gateway sits between your applications and AI providers (OpenAI, Anthropic, etc.), enforcing policies, tracking attribution, and recording every request. This guide gets you running on Linux in about 10 minutes using Docker Compose.

Choose Your Setup Method

Pick the method that best fits how you want to use the gateway:

Jump to: Method 1 | Method 2 -- Recommended | Method 3

Table of Contents

• Prerequisites
• Steps
  • Step 1: Download and Configure
  • Step 2: Start the Gateway
  • Step 3: Verify Credentials
• Methods
  • Method 1: Base URL Replacement
  • Method 2: System Proxy
  • Method 3: Explicit Gateway API
• View Records and Metrics
• Load a Custom Policy
• Alternative: Debian Package Install
• Console Dashboard
• Using the Managed Gateway
• Next Steps
• Cleanup

Prerequisites

• Docker Engine 24+ with the Compose plugin (Docker Desktop 4.x also works)
• curl and jq for testing (jq is optional but recommended)
• An OpenAI or Anthropic API key to store in the gateway. You can skip this and test with a policy denial instead.

Steps

Step 1: Download and Configure

Download the Docker Compose file and env template from the latest release:

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 and set all values in one pass -- admin token and your AI provider API keys:

MVGC_ADMIN_TOKEN=<your-admin-token>   # use: openssl rand -hex 32
POSTGRES_PASSWORD=mvgcpassword        # change for production

# AI provider API keys -- add any providers you want to use
OPENAI_API_KEY=sk-...
# ANTHROPIC_API_KEY=sk-ant-...

Step 2: Start the Gateway

docker compose up -d

This starts:

• The Axemere Gateway on port 7080
• A Postgres 16 instance (data stored in a Docker volume)

Wait a few seconds for the database to initialize. The gateway waits for Postgres to pass its health check before starting. Verify the gateway is healthy:

curl -s http://localhost:7080/healthz | jq .

Expected response (after a few seconds; during the first 10s you may see {"status":"starting"}):

{"status":"ok", "version":"...", "node_id":"node-local-dev", ...}

Step 3: Verify Credentials

The gateway seeds credential records for all major providers automatically on first start (OpenAI, Anthropic, Gemini, Azure OpenAI, Cohere). Each credential maps a name like cred-openai to the env var you set in Step 1. No manual registration needed.

Configure the CLI and verify:

mvgc config set-url http://localhost:7080
mvgc config set-token <your-admin-token>
mvgc credentials list

You should see cred-openai, cred-anthropic, and the other providers listed.

If you edit the credentials file inside the container to add a provider or change settings, reload without restarting:

mvgc credentials reload

Methods

Method 1: Base URL Replacement

Point your existing AI SDK at the gateway by overriding its base URL. The gateway resolves the provider from the /proxy/{provider}/ path prefix and forwards the request using the API key you registered above.

Set the provider-specific base URL variable before running your application:

# OpenAI
export OPENAI_BASE_URL=http://localhost:7080/proxy/openai
export OPENAI_API_KEY=unused   # gateway uses its stored key; value ignored

# Anthropic
export ANTHROPIC_BASE_URL=http://localhost:7080/proxy/anthropic
export ANTHROPIC_API_KEY=unused

# Gemini
export GOOGLE_API_BASE=http://localhost:7080/proxy/gemini

# Cohere
export CO_API_URL=http://localhost:7080/proxy/cohere

No .env or config change is needed in the Docker Compose setup. The gateway reads the /proxy/{provider}/ prefix to identify the upstream provider automatically. Supported path-prefix providers: openai, anthropic, gemini, cohere. Azure OpenAI requires the X-MVGC-Target-Host header instead (no fixed upstream hostname).

Your application runs unchanged. The gateway intercepts each call, applies policy, and forwards it with the stored credential.

Tip: for transparent multi-provider coverage with no code changes, use Method 2.

Method 2: System Proxy

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.

Configure your system to route all AI provider traffic through the gateway automatically. No code changes required in any application.

Step A: Enable MITM for HTTPS

Most AI APIs use HTTPS. To inspect and govern HTTPS traffic, enable MITM mode. Add to .env:

MVGC_PROXY_MITM_ENABLED=true
MVGC_MANAGED_DOMAINS=api.openai.com,api.anthropic.com,generativelanguage.googleapis.com,api.cohere.ai

Restart:

docker compose restart gateway

Step B: Install the CA Certificate

Download and install the gateway's CA certificate so the system trusts its TLS interception:

# Download
curl -o /tmp/mvgc-proxy-ca.crt http://localhost:7080/v1/proxy/ca.crt

# Debian/Ubuntu
sudo cp /tmp/mvgc-proxy-ca.crt /usr/local/share/ca-certificates/mvgc-proxy-ca.crt
sudo update-ca-certificates

# RHEL/Fedora/CentOS
sudo cp /tmp/mvgc-proxy-ca.crt /etc/pki/ca-trust/source/anchors/mvgc-proxy-ca.crt
sudo update-ca-trust

Individual applications that manage their own CA store (like Firefox) need the certificate added separately in their settings.

Step C: Configure the System Proxy

Use the PAC file served by the gateway. This routes only AI provider domains through the proxy and sends everything else directly.

Option A: GNOME (GUI)

1. Open Settings -- Network
2. Under Network Proxy, select Automatic
3. Enter the URL: http://localhost:7080/v1/proxy/proxy.pac
4. Click Apply

Option B: KDE Plasma (GUI)

1. Open System Settings -- Network -- Proxy
2. Select Use proxy configuration URL
3. Enter: http://localhost:7080/v1/proxy/proxy.pac
4. Click Apply

Option C: Environment variables (terminal and CLI tools)

Most Linux command-line tools and AI SDKs respect the standard proxy environment variables. Add these to ~/.bashrc or ~/.zshrc:

export http_proxy=http://localhost:7080
export https_proxy=http://localhost:7080
export HTTP_PROXY=http://localhost:7080
export HTTPS_PROXY=http://localhost:7080
# Exclude the gateway itself from proxying
export no_proxy=localhost,127.0.0.1
export NO_PROXY=localhost,127.0.0.1

Then reload your shell:

source ~/.bashrc

Port note: Environment variable proxy (HTTPS_PROXY=:7080) routes requests through the developer listener; those requests are tagged traffic_class: developer. Options A and B (PAC file) route through the ambient listener on port 7081 and are tagged traffic_class: ambient. The distinction determines how records are classified in the console.

Step D: Enable Port 7081 (PAC file options only)

If you configured Options A or B (PAC file), the PAC file routes traffic to port 7081: a dedicated listener that tags all PAC-routed requests as traffic_class: ambient. Port 7081 is not bound by default.

Add pac_proxy_addr to .env or the gateway config file:

MVGC_PAC_PROXY_ADDR=:7081

Or in mvgc.yaml:

gateway:
  pac_proxy_addr: ":7081"

Restart:

docker compose restart gateway

Confirm port 7081 is listening:

curl -s http://localhost:7081/healthz | jq .status

Skip this step if you are only using Option C (environment variables); that path uses port 7080 and does not require port 7081.

Step E: Verify

Make an AI API call from the terminal. The gateway intercepts it automatically:

curl -s https://api.openai.com/v1/models \
  -H "Authorization: Bearer unused"

Check gateway metrics to confirm requests are flowing through:

curl -s http://localhost:7080/metrics | grep mvgc_requests_total

Disabling the System Proxy

Remove or unset the proxy environment variables, or reset the GNOME/KDE proxy setting to None.

Method 3: Explicit Gateway API

Call the gateway's native API directly. This gives you full control over attribution (project, customer, account labels) and unlocks all governance features.

Register a workload:

CLI:

cat > wl-quickstart.yaml << 'EOF'
workload_id: wl-quickstart
org_id: org-quickstart
name: Quickstart Workload
default_attribution:
  project_id: proj-quickstart
allowed_connection_types:
  - direct_api
EOF

mvgc workloads create --file wl-quickstart.yaml

API:

export MVGC_ADMIN_TOKEN="<your-admin-token>"

curl -s -X PUT http://localhost:7080/v1/admin/workloads \
  -H "MVGC-Admin-Token: $MVGC_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workload_id": "wl-quickstart",
    "org_id": "org-quickstart",
    "name": "Quickstart Workload",
    "default_attribution": {
      "project_id": "proj-quickstart"
    },
    "allowed_connection_types": ["direct_api"]
  }' | jq .

Submit a request:

curl -s -X POST http://localhost:7080/v1/actions:execute \
  -H "Content-Type: application/json" \
  -d '{
    "schema": "mvgc.action_request.v2",
    "org_id": "org-quickstart",
    "workload_id": "wl-quickstart",
    "action": {
      "type": "ai.infer",
      "method": "POST",
      "target_host": "api.openai.com",
      "target_path": "/v1/chat/completions",
      "params": {
        "model": "gpt-4o-mini",
        "messages": [{"role": "user", "content": "Say hello in one sentence."}],
        "max_tokens": 50
      }
    },
    "attribution": {
      "project_id": "proj-quickstart"
    }
  }' | jq .

Test a policy denial (no API key needed):

curl -s -X POST http://localhost:7080/v1/actions:execute \
  -H "Content-Type: application/json" \
  -d '{
    "schema": "mvgc.action_request.v2",
    "org_id": "org-quickstart",
    "workload_id": "wl-quickstart",
    "action": {
      "type": "ai.infer",
      "method": "POST",
      "target_host": "api.example-blocked.com",
      "params": {"model": "test"}
    },
    "attribution": {"project_id": "proj-quickstart"}
  }' | jq .

Expected response (HTTP 403):

{
  "decision": "deny",
  "reason": "...",
  "request_id": "..."
}

View Records and Metrics

Every request creates an execution record regardless of which method you use:

curl -s "http://localhost:7080/v1/reports/usage?project_id=proj-quickstart" | jq .
curl -s "http://localhost:7080/v1/reports/spend?project_id=proj-quickstart" | jq .
curl -s http://localhost:7080/metrics | grep mvgc_requests_total

Load a Custom Policy

Push a policy bundle that allows only api.openai.com:

curl -s -X PUT http://localhost:7080/v1/admin/policies \
  -H "MVGC-Admin-Token: $MVGC_ADMIN_TOKEN" \
  -H "Content-Type: application/yaml" \
  --data-binary @- << 'EOF'
schema: mvgc.policy_bundle.v1
bundle_id: bundle-quickstart
version: 1.0.0
defaults:
  decision: deny
evaluation:
  order: [identity, targets, credentials, budgets, risk]
  stop_on: [deny, require_approval]
  merge_strategy: first_match
inline_rules:
  identity:
    - id: identity.allow.proxy
      priority: 100
      when:
        field: context.connection_type
        in: [connect_proxy, sdk_redirect, direct_api]
      effect:
        decision: allow
  targets:
    - id: targets.allow.openai
      priority: 100
      when:
        field: context.action.target_host
        equals: "api.openai.com"
      effect:
        decision: allow
    - id: targets.deny.others
      priority: 50
      when:
        field: context.action.target_host
        exists: true
      effect:
        decision: deny
        reason: "target host not in allowlist"
EOF

Alternative: Debian Package Install

If you prefer a native install over Docker, use the APT repository on Debian or Ubuntu:

# 1. Add the signing key
curl -fsSL https://raw.githubusercontent.com/Axemere-LLC/mvgc-apt/main/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://raw.githubusercontent.com/Axemere-LLC/mvgc-apt/main stable main" \
  | sudo tee /etc/apt/sources.list.d/mvgc.list

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

Provision PostgreSQL separately:

sudo apt install -y postgresql
sudo systemctl enable --now postgresql

openssl rand -hex 16   # use as password below

sudo -u postgres psql <<'EOF'
CREATE USER mvgc_gateway WITH PASSWORD '<your-generated-password>';
CREATE DATABASE mvgc_gateway OWNER mvgc_gateway;
EOF

Configure and start:

sudo nano /etc/mvgc/mvgc.yaml
# Set database.url and gateway.admin_token

sudo systemctl enable --now mvgc-gateway
curl -s http://localhost:7080/healthz | jq .

See the Linux (Debian/Ubuntu) deployment guide for the full post-install configuration walkthrough.

Console Dashboard

The console provides a browser-based dashboard for monitoring requests, managing policies, credentials, and provider integrations. The Docker Compose deployment already includes the console service. If you used docker compose up in Step 2, the console is already running:

open http://localhost:7091

To run the console standalone (e.g., alongside a .deb install), use Docker:

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

Using the Managed Gateway

If your organization uses Axemere's managed gateway service, you do not need to install or configure anything locally. Requests are sent directly to the managed endpoint.

Prerequisites:

• An API key from your organization admin (created via OrgService.CreateAPIKey)

Endpoint: https://us.gw.axemere.ai

Authentication: Include your API key as a Bearer token in every request.

Example:

curl -s -X POST https://us.gw.axemere.ai/v1/actions:execute \
  -H "Authorization: Bearer mvgc_k_<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "schema": "mvgc.action_request.v2",
    "workload_id": "my-app",
    "action": {
      "type": "ai.infer",
      "method": "POST",
      "target_host": "api.openai.com",
      "params": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello"}]}
    }
  }'

TLS is provided by the managed endpoint -- no client certificates needed. The org_id is derived from your API key automatically.

See the Managed Gateway Guide for the full reference including policy overlays, metering, and troubleshooting.

Next Steps

Cleanup

Docker Compose:

docker compose down -v   # stops containers and removes the Postgres volume

Remove proxy environment variables from ~/.bashrc or ~/.zshrc if you added them.

Remove the CA certificate if you installed it:

# Debian/Ubuntu
sudo rm /usr/local/share/ca-certificates/mvgc-proxy-ca.crt
sudo update-ca-certificates --fresh

# RHEL/Fedora
sudo rm /etc/pki/ca-trust/source/anchors/mvgc-proxy-ca.crt
sudo update-ca-trust

Debian package:

sudo systemctl stop mvgc-gateway
sudo apt remove mvgc-gateway