Getting Started

This guide takes you from zero to a running AIControl instance with a verified installation. Estimated time: 30–45 minutes.

Buy a plan (Business/Enterprise only — skip for Community)

1. Community is free and needs no plan. Business ($999/year), Enterprise ($1,999/year) and the $1, 90-day Enterprise trial are all self-serve: choose a plan on the pricing page and pay with Stripe Checkout.
2. You will receive an email with your activation code, and the pull credential for the licensed API image, within 24 hours of checkout. Treat both like passwords. Lost the code? See Lost activation code.
3. Once your instance is running (Step 4 below), open Dashboard → Billing and enter the code once.
4. Your instance verifies the code itself — licensing makes no network call. Business and Enterprise codes are valid for 395 days (one year plus 30 days' grace); when you renew, you'll get a new code by email to enter the same way. Trial codes are valid for 90 days.

Prerequisites

A Slack workspace is optional but required for the human review (HITL) workflow.

Step 1 — Install Docker

If Docker is not already installed:

Linux:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker
docker compose version   # confirm v2+

macOS / Windows: Install Docker Desktop — Docker Compose v2 is included, no separate install needed.

macOS only: if git clone prompts for Xcode tools, run xcode-select --install, click Install in the dialog, then re-run clone.

Step 2 — Clone and install

git clone https://github.com/alpaaai/aicontrol-oss
cd aicontrol-oss
bash install.sh

Do not create .env yourself first. install.sh generates it when it is missing, with random secrets, and skips generation when a .env already exists. The interactive prompts are: PostgreSQL password, JWT signing key (both auto-generated if you press Enter), Slack bot token, signing secret and review channel (Enter to skip), and LLM provider, model and API key. With no LLM API key it sets LLM_MOCK_ENABLED=true, so AI-native features return mock output until you set a key. The file is written with mode 600.

install.sh does: generate .env if missing → pull images → start Postgres → run migrations → start the api and frontend services. If you will reach the dashboard at a hostname other than localhost, set AICONTROL_API_URL, FRONTEND_BASE_URL and CORS_ORIGINS in .env (see Operations). It does not seed any data or issue a token.

Step 3 — Check the install

docker compose -f docker-compose.yml -f docker-compose.app.yml ps
curl http://localhost:8001/health

All three containers (postgres, api, frontend) should report healthy, and /health should return "status":"ok" and "database":"ok". If anything fails, run bash diagnose.sh and include the output in your support request.

Step 4 — First-run setup wizard

Open http://localhost:3000. On first launch, AIControl detects no users exist and redirects to the setup wizard automatically.

Step 4a — Organization details

• Enter your Organization name (e.g. "Acme Corp")
• Choose your Timezone from the dropdown (used for all dashboard timestamp displays)
• Click Next

Step 4b — Root administrator account

• Enter your Full name, Email address, and a Password (minimum 8 characters)
• Click Create account

On success, you are logged in as the root administrator and redirected to the dashboard Overview page, which offers to activate a starting policy set (Standard or Strict; you can skip it).

Login from here on: Open http://localhost:3000/login, enter your email and password.

If you bought a plan, this is the point to enter the activation code.

Step 5 — Issue an admin API token

The dashboard login does not work with curl or the CLI scripts. They use a machine API token. Issue an admin one:

docker compose -f docker-compose.yml -f docker-compose.app.yml \
  exec api python scripts/public/issue_token.py --role admin --desc "admin"

The token is printed once. Save it, then export it for the examples below:

export AICONTROL_ADMIN_TOKEN=<token from the output>

You can also create tokens on the dashboard's Tokens page (http://localhost:3000/tokens). See Operations → Token lifecycle.

Step 6 — Register a downstream server and make your first governed call

Register a server (any MCP server you already have, or a placeholder URL for a dry run — the gateway fails closed with a clear JSON-RPC error if it's unreachable, so a bad URL here is safe to try):

curl -X POST http://localhost:8001/mcp-servers \
  -H "Authorization: Bearer $AICONTROL_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-first-server", "base_url": "https://your-mcp-server.internal/mcp"}'
# -> {"id": "<server_id>", "status": "pending_review", ...}

New registrations start in pending_review. Activate it:

curl -X PATCH http://localhost:8001/mcp-servers/<server_id> \
  -H "Authorization: Bearer $AICONTROL_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}'

The dashboard's MCP Servers page does the same: register the server, then click Approve.

Register an agent and issue its agent-scoped token in one step (gateway calls reject admin tokens and unscoped agent tokens — see Integration). --name, --owner and --tools (the agent's approved tools, comma-separated) are all required:

docker compose -f docker-compose.yml -f docker-compose.app.yml \
  exec -e AICONTROL_ADMIN_TOKEN="$AICONTROL_ADMIN_TOKEN" api \
  python scripts/public/onboard_agent.py \
  --name "my-first-agent" --owner "my-team" --tools "read_file"

Copy the AICONTROL_TOKEN and AGENT_ID values from the output. The Agents page on the dashboard has a Register agent dialog that does the same and shows the token once.

New agents start in observe mode. Policies are evaluated and every decision is logged, but nothing is blocked. Switch an agent to enforcement when you are ready: curl -X PUT http://localhost:8001/agents/<agent_id> -H "Authorization: Bearer $AICONTROL_ADMIN_TOKEN" -H "Content-Type: application/json" -d '{"governance_mode": "govern"}'

Call the gateway with the agent token from that output:

curl -X POST http://localhost:8001/mcp/<server_id>/call_tool \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "params": {
      "name": "read_file",
      "arguments": {"path": "/data/report.csv"},
      "session_id": "11111111-1111-1111-1111-111111111111",
      "sequence_number": 1
    }
  }'

If the downstream server is unreachable (expected, for a placeholder URL), you'll get back a JSON-RPC error rather than a result — that's the gateway's fail-closed behavior, not a failure of this step:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {"code": -32000, "message": "Downstream MCP server unreachable"}
}

Either way, check the dashboard's Audit log — the call is recorded regardless of outcome.

Enterprise trial

Self-service: click "Start $1 Enterprise trial for 90 days" on the pricing page, enter your email, and complete the $1 Stripe checkout. You will receive an email with the activation code within 24 hours — enter it on Dashboard → Billing. Enterprise sections unlock immediately, no restart or frontend rebuild required (the licensed API image is still required, see below). The trial reverts to Community when its code expires after 90 days unless you upgrade first: Dashboard → Billing → Upgrade to Business or Upgrade to Enterprise opens the Stripe Payment Link for that plan. After payment you will receive a new activation code by email; enter it on Dashboard → Billing to switch plans.

Licensed API image (Business, Enterprise and trial)

Community installs run the public ghcr.io/alpaaai/aicontrol-community image. Business, Enterprise and trial plans run the licensed image, ghcr.io/alpaaai/aicontrol-api. The activation code switches licensed features on, but the code for compliance reports, natural-language policy authoring and simulation, policy drift detection and SIEM export ships only in the licensed image; those endpoints do not exist in the community image. Slack HITL notifications, the Reviews queue, session view and CSV export are in both images and unlock with the code. The dashboard image is the same for every plan.

1. Log in to the registry with the pull credential you received with your activation code:
   bashCopy

   docker login ghcr.io

2. Add this line to .env:
   Copy

   AICONTROL_API_IMAGE=ghcr.io/alpaaai/aicontrol-api

3. Pull and restart:
   bashCopy

   docker compose -f docker-compose.yml -f docker-compose.app.yml pull
   docker compose -f docker-compose.yml -f docker-compose.app.yml up -d

Lost activation code

Email support@aictl.io from the address you used at checkout and we'll resend your code.

Business/Enterprise walkthrough — install to first policy

A Business or Enterprise customer's experience differs from Community in exactly two places — licensing and the API image — and is otherwise identical:

1. Buy a plan. Checkout on the pricing page → activation-code email within 24 hours. This happens before or after install; order doesn't matter.
2. Install and bootstrap. Same as Community: Steps 1–5 above. install.sh never asks for an activation code. To run the licensed image, follow Licensed API image.
3. Run the setup wizard (Step 4) and log in as root administrator, same as Community.
4. Enter the activation code. Open Dashboard → Billing and submit the code from Step 1. This calls PUT /settings/license-activation (admin-only), which verifies the code locally before storing it — an invalid or expired code is rejected and nothing is saved. On success, Business/Enterprise sections unlock immediately: no restart, no frontend rebuild. See Buy a plan above for how long a code is valid and how renewal works.
5. Register a downstream server and onboard an agent — identical to Step 6 above; licensing has no effect on the gateway registration or agent onboarding flow.
6. Create policies — identical to the Policies flow. Business/Enterprise additionally get the in-dashboard HITL review queue and Slack notifications for review-effect policies (Community collapses review to deny), and Enterprise additionally gets natural-language policy authoring with simulate-before-activate.

Token management

Issue an agent token (scoped to one registered agent — this is the kind the gateway accepts):

docker compose -f docker-compose.yml -f docker-compose.app.yml \
  exec api python scripts/public/issue_token.py \
  --role agent --agent-id <agent_uuid> --desc "agent-name"

Revoke a token:

docker compose -f docker-compose.yml -f docker-compose.app.yml \
  exec api python scripts/public/revoke_token.py --id TOKEN_UUID

Or use the Tokens page in the dashboard (/tokens).

Updating AIControl

docker compose -f docker-compose.yml -f docker-compose.app.yml pull
docker compose -f docker-compose.yml -f docker-compose.app.yml up -d
curl http://localhost:8001/health

The api container applies pending migrations when it starts, so no separate alembic step is needed. To manage migrations yourself, set RUN_MIGRATIONS=false in .env. See Operations.

Troubleshooting

Run the diagnostic collector and share the output with support:

bash diagnose.sh

Next steps

• Integration — register a server and connect your agent's MCP client
• Policies — create and manage governance policies
• Operations — token lifecycle, monitoring, production notes