macOS (Homebrew)

For: Developers and IT engineers running Axemere Gateway locally on macOS.

Homebrew is the recommended install method for macOS developers evaluating or running the gateway locally. Only Apple Silicon (M1/M2/M3/M4, arm64) is supported via this path. Intel Mac users should use Docker instead.

Prerequisites
PostgreSQL Setup
Installation
Configuration
Start / Stop / Restart
Verify
Upgrade
Trusting the CA Certificate
See Also

Prerequisites

Apple Silicon Mac (M1 / M2 / M3 / M4)
Homebrew installed (/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)")
An external PostgreSQL 15+ instance (see below for a local option)

PostgreSQL Setup

PostgreSQL not included. The Homebrew formula installs only the gateway binary and a launchd plist for brew services. You must provision a PostgreSQL 15+ instance separately before starting the service.

brew install postgresql@16
brew services start postgresql@16  # starts now and persists across reboots

# postgresql@16 is keg-only -- add its bin to PATH so createuser/createdb are found
export PATH="/opt/homebrew/opt/postgresql@16/bin:$PATH"

# Wait for Postgres to be ready, then create the role and database
pg_isready -q && createuser -s mvgc_gateway && createdb -O mvgc_gateway mvgc_gateway

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

Installation

brew tap Axemere-LLC/tap
brew install mvgc-gateway

Configuration

Edit the config file installed at $(brew --prefix)/etc/mvgc/mvgc.yaml. Set database.url and gateway.admin_token at minimum:

nano $(brew --prefix)/etc/mvgc/mvgc.yaml

For a local Homebrew Postgres setup (role and database created above), use:

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

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

Alternatively, set environment variables before starting the service. Env vars always take precedence over the config file.

Proxy mode: If you set proxy_enabled: true, API keys are not injected automatically. You must also register credentials via PUT /v1/admin/credentials. The default add-ons already include select_credential rules for each provider (OpenAI, Anthropic, Gemini, Azure OpenAI, Cohere). See the Transparent Proxy Mode section of the Developer Integration Guide, and the select_credential policy rule reference in Policies.

Start / Stop / Restart

brew services start mvgc-gateway    # start now and persist across reboots
brew services stop mvgc-gateway     # stop now and remove from auto-start
brew services restart mvgc-gateway  # restart after a config change

brew services start registers the gateway with macOS launchd, so it starts automatically on every login -- no additional step required. It will also restart the process automatically if it crashes (keep_alive true in the launchd plist).

Use brew services run mvgc-gateway instead if you want to start the service for the current session only, without persisting across reboots.

Log output is written to:

File	Contents
`$(brew --prefix)/var/log/mvgc/gateway.log`	All structured application logs (Info, Warn, Error) -- request processing, policy decisions, credential resolution warnings, add-on loading
`$(brew --prefix)/var/log/mvgc/gateway-error.log`	Panics and crashes only -- this file is normally empty during healthy operation

Note: The gateway writes all structured logs (including error-level messages) to gateway.log as JSON via Go's slog package. The gateway-error.log file captures only unrecoverable failures (panics, fatal crashes). An empty gateway-error.log is expected and healthy.

Denied requests are not written to the log files. They are persisted as execution records in the database and exported via SIEM export if configured. Query denied requests using the dashboard API or directly from the execution_records table -- see Execution Record Fields.

The working directory for the service is $(brew --prefix)/var/mvgc/. This directory is created automatically by the formula's install step -- no manual setup required.

Verify

curl http://localhost:7080/healthz

Upgrade

brew upgrade mvgc-gateway
brew services restart mvgc-gateway

To pin the current version and skip auto-upgrades:

brew pin mvgc-gateway

Schema migrations run automatically on startup. See the Upgrading section in the overview for details on schema migrations and downgrade.

Trusting the CA Certificate

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

curl http://localhost:7080/v1/proxy/ca.crt > mvgc-proxy-ca.crt
sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain mvgc-proxy-ca.crt

This makes all apps using the macOS TLS stack (curl, Safari, most SDKs) trust the gateway's CA certificate automatically.