Axemere.ai

macOS (Homebrew)

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

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

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.

Table of Contents

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 Proxy Mode Credential Setup section in the Network Operations Guide for a step-by-step walkthrough.

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:

FileContents
$(brew --prefix)/var/log/mvgc/gateway.logAll structured application logs (Info, Warn, Error) -- request processing, policy decisions, credential resolution warnings, add-on loading
$(brew --prefix)/var/log/mvgc/gateway-error.logPanics 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.

Console (Web Dashboard)

The console provides a browser-based dashboard for monitoring requests, managing policies, credentials, and provider integrations. It connects to the gateway's admin API.

Install

brew install mvgc-console

Configure and Start

Set the gateway URL before starting:

# Point the console at the running gateway
export CONSOLE_GATEWAY_URL=http://localhost:7080

# Optional: set a password to protect the dashboard (default: no auth)
export CONSOLE_PASSWORD=<your-console-password>

brew services start mvgc-console

Or persist the configuration by editing the service's launchd plist environment:

# The console reads CONSOLE_GATEWAY_URL and CONSOLE_PASSWORD from the launchd environment.
# Set them before starting the service, or configure them in the plist.
CONSOLE_GATEWAY_URL=http://localhost:7080 brew services start mvgc-console

The console listens on port 7091 by default.

open http://localhost:7091

Logs

$(brew --prefix)/var/log/mvgc/console.log

Upgrade

brew upgrade mvgc-console
brew services restart mvgc-console

Stop

brew services stop mvgc-console

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.

See Also