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. For Business or Enterprise, contact hello@aictl.io from the pricing page — pricing is tailored to your deployment, so a rep sends you a Stripe checkout link directly. Prefer to start self-service today? See Enterprise trial below — it's the same activation-code flow, initiated with a $1 charge instead of a sales conversation.
2. After checkout, you'll get an email with a one-time activation code.
3. Once your instance is running (Step 5 below), open Dashboard → Billing and enter the code once.
4. From then on, a daily background job on your instance calls billing.aictl.io to confirm your subscription is still active. That call sends only your activation code — no usage data, no audit log content, nothing else. If it can't reach billing.aictl.io, your license keeps working for 7 days before failing closed. Community-tier installs (no activation code entered) never make this call.

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 configure

git clone https://github.com/alpaaai/aicontrol
cd aicontrol
cp .env.example .env
# Edit .env: set POSTGRES_PASSWORD (required)
# Optional: SLACK_BOT_TOKEN

If you skip this step, install.sh detects the missing .env and runs its own interactive prompt instead (DB password, secret key, Slack tokens, LLM provider/model) — either path produces a working .env, but the prompts only appear when you haven't already created one.

Step 3 — Run the installer

bash install.sh

install.sh does: pull images → start Postgres → run migrations → start the api and frontend services. It does not seed any data or issue a token — that happens in Step 4.

Step 4 — First run

bash scripts/quickstart.sh

Seeds demo agents, policies, and an admin token into .env (via scripts/seed_demo.sh), prints your admin token and the dashboard/API URLs, runs a lending scenario so the audit log is populated on arrival, then opens the dashboard in your browser.

Save the admin token shown on screen — it is also written to .env.

Step 5 — First-run setup wizard

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

Step 5a — Organisation details

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

Step 5b — 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.

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

Admin API access: Machine API tokens (issued by scripts/quickstart.sh in Step 4) work with the API directly — they do not use the dashboard login flow. Use AICONTROL_TOKEN from .env for curl/httpx calls. See Operations → Token lifecycle.

Step 6 — Verify installation

bash verify.sh

All checks should pass. If any fail: bash diagnose.sh and include the output in your support request.

Step 7 — 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_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_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}'

Issue an agent-scoped token (gateway calls reject admin tokens and unscoped agent tokens — see Integration):

docker compose -f docker-compose.yml -f docker-compose.app.yml \
  exec api python scripts/onboard_agent.py --name "my-first-agent" --desc "getting started"

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 a $1, 90-day Enterprise trial" on the pricing page, enter your email, and complete the $1 Stripe checkout. You'll get an activation-code email immediately — enter it on Dashboard → Billing. Enterprise sections unlock immediately, no restart or frontend rebuild required. The trial reverts to Community automatically after 90 days unless you upgrade first (Dashboard → Billing → Upgrade, or contact hello@aictl.io).

Business/Enterprise walkthrough — install to first policy

A Business or Enterprise customer's experience differs from Community in exactly one place — licensing — and is otherwise identical:

1. Buy a plan. Checkout on the pricing page → activation-code email. This happens before or after install; order doesn't matter.
2. Install and bootstrap. Same as Community: bash install.sh, then bash scripts/quickstart.sh (Steps 1–6 above). There's no separate installer path or extra prompt for a paid plan — install.sh never asks for an activation code.
3. Run the setup wizard (Step 5) 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 validates the code against billing.aictl.io before storing it — an invalid code is rejected and nothing is saved. On success, Business/Enterprise sections unlock immediately: no restart, no frontend rebuild. From then on, a daily background job re-syncs your plan and status from billing.aictl.io (see Buy a plan above for the fail-closed grace period).
5. Register a downstream server and onboard an agent — identical to Step 7 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 a token:

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

Revoke a token:

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

Or use the Tokens tab in the dashboard.

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
docker compose -f docker-compose.yml -f docker-compose.app.yml exec api alembic upgrade head

Migrations are backward-compatible. Running alembic upgrade head after each update is safe and required.

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