DocsGetting StartedQuickstart (5 Minutes)

Quickstart (5 Minutes)

Go from zero to your first policy-governed, masked API response in under 5 minutes.

Auvis sits as a policy enforcement gateway between client applications and your upstream services or streaming topics. In this guide, you will run Auvis locally, configure a masking policy, and verify governed responses.

Prerequisites

  • Go 1.22+ (for CLI/binary path) OR Docker & Docker Compose (for container path)
  • curl and jq for sending test HTTP requests

Option A: Go CLI Path (1 Minute)

Step 1: Install Auvis CLI

BASH
# Option 1: Instant Go Install
go install github.com/Auvis-Labs/auvis/cmd/auvis@latest

# Option 2: Build from Source
git clone https://github.com/Auvis-Labs/auvis.git
cd auvis
go build -o auvis ./cmd/auvis

Step 2: Start the Mock Upstream Server

Auvis includes a built-in mock upstream server in test-cmd for testing:

BASH
# In a separate terminal tab:
cd test-cmd
go run main.go
# Starts mock upstream listening on http://localhost:8000

Step 3: Scaffold Your Project

BASH
auvis init
# Creates: auvis.yaml, .env, policies/example.yaml

Open the generated .env and set your upstream URL:

BASH
AUVIS_UPSTREAM_URL=http://localhost:8000
AUVIS_ENV=development
AUVIS_SALT=change-me-use-openssl-rand-hex-32

Then export your environment:

BASH
export $(grep -v '^#' .env | xargs)

Step 4: Define a Policy (policies/analyst_mask.yaml)

Create a YAML policy in policies/analyst_mask.yaml:

YAML
policies:
  - name: analyst-mask-policy
    match:
      roles: [analyst]
      resource: /users
    rules:
      - field: "email"
        action: mask
      - field: "phone"
        action: mask
      - field: "ssn"
        action: remove
    compliance_tags: ["GDPR"]

Step 5: Start Auvis Gateway

BASH
auvis dev

Expected startup output:

TEXT
time=... level=INFO msg="AUVIS_ENV detected" AUVIS_ENV=development
time=... level=INFO msg="Gateway environment" AUVIS_ENV=development ungoverned_phi_posture=warn port=8082 upstream=http://localhost:8000

Step 6: Test Governed Output with curl

Send a request through Auvis specifying the analyst role:

BASH
curl -s -H "X-User-ID: usr_101" \
        -H "X-User-Role: analyst" \
        http://localhost:8082/users | jq .

Expected Governed Output:

JSON
[
  {
    "id": "usr_101",
    "name": "Jane Doe",
    "email": "***@example.com",
    "phone": "***-***-4567",
    "date_of_birth": "**-**-1990",
    "account_status": "active"
  }
]

Option B: Docker Container Path (2 Minutes)

Step 1: Launch Stack via Compose

BASH
git clone https://github.com/Auvis-Labs/auvis.git
cd auvis
docker compose up -d

This spins up:

  • Auvis Gateway on port 8082
  • PostgreSQL + pgvector on port 5432

Step 2: Check Gateway Health

BASH
curl -i http://localhost:8082/healthz
# Returns HTTP 200 OK

Step 3: Test Governance

BASH
curl -s -H "X-User-ID: usr_101" \
        -H "X-User-Role: analyst" \
        http://localhost:8082/users | jq .

Step 7: Inspect Audit Trail

Every request passing through Auvis generates a structured audit log entry in audit.jsonl:

BASH
auvis logs --limit 1
JSON
{
  "timestamp": "2026-10-30T14:22:10Z",
  "request_id": "req-17845937576289",
  "user_id": "usr_101",
  "user_role": "analyst",
  "resource": "/users",
  "method": "GET",
  "upstream_status": 200,
  "policies_applied": ["analyst-mask-policy"],
  "fields_masked": ["email", "phone"],
  "fields_removed": ["ssn"]
}

Next Steps

PreviousOverviewNext Live Healthcare Demo