Simplify quickstart guide

concepts/performance.mdx

@@ -0,0 +1,35 @@
+---
+title: Performance
+description: Agent Control adds negligible latency to your AI agents. See benchmark results across real-world scenarios.
+icon: "gauge-high"
+---
+
+Agent Control is designed to stay out of your agent's critical path. The evaluation pipeline runs as a lightweight sidecar check — your agent sends a request to the Agent Control server, gets back a pass/fail decision, and continues. The entire round-trip typically completes in under 40 ms at the median, even with multiple controls active.
+
+This matters because AI agents already carry the latency cost of LLM inference (often hundreds of milliseconds to seconds per call). Adding safety controls shouldn't double that budget. Agent Control's architecture ensures it doesn't:
+
+- **Server-side evaluators execute in-process** — built-in evaluators (regex, list, JSON, SQL) run directly inside the Agent Control server with no external network calls, keeping evaluation time minimal.
+- **Controls scale linearly** — going from 1 control to 50 controls adds roughly 27 ms to the median evaluation time. You can layer comprehensive safety coverage without compounding latency.
+- **Agent initialization is fast** — registering or updating an agent with its tool steps completes in under 20 ms at the median, so cold starts and re-registrations don't stall your application.
+
+## Benchmark Results
+
+The following benchmarks were run on a local development environment to give you a directional sense of Agent Control's overhead. They are not production sizing guidance — your results will vary based on hardware, network topology, and evaluator complexity.
+
+| Endpoint | Scenario | RPS | p50 | p99 |
+|----------|----------|-----|-----|-----|
+| Agent init | Agent with 3 tool steps | 509 | 19 ms | 54 ms |
+| Evaluation | 1 control, 500-char content | 437 | 36 ms | 61 ms |
+| Evaluation | 10 controls, 500-char content | 349 | 35 ms | 66 ms |
+| Evaluation | 50 controls, 500-char content | 199 | 63 ms | 91 ms |
+| Controls refresh | 5-50 controls per agent | 273-392 | 20-27 ms | 27-61 ms |
+
+### Key takeaways
+
+- **All built-in evaluators perform similarly** — regex, list, JSON, and SQL evaluators all land within 40-46 ms p50 at 1 control. Choosing the right evaluator for your use case won't introduce a latency penalty.
+- **Agent init handles create and update identically** — the server uses a create-or-update operation, so there's no performance difference between first registration and subsequent updates.
+- **Zero errors under load** — all scenarios completed with a 0% error rate across the full benchmark duration.
+
+### Test environment
+
+Benchmarks were run on an Apple M5 with 16 GB RAM using Docker Compose (`postgres:16` + `agent-control`). Each scenario ran for 2 minutes with 5 concurrent users for latency measurements (p50, p99) and 10-20 concurrent users for throughput (RPS). RPS represents completed requests per second.

core/quickstart.mdx

@@ -186,22 +186,9 @@ Now, run your agent code.
 
 **🎉 Done!** Your agent now blocks SSN patterns automatically.
 
-> [**!NOTE**]
-> **Authentication Note:** Authentication is disabled by default in the server .env (`AGENT_CONTROL_API_KEY_ENABLED=false`). If you enable it, this setup script needs an admin API key because it creates a control and attaches it to an agent. `agents.register_agent()` accepts a regular or admin key, but `controls.create_control()` and `agents.add_agent_control()` require a key listed in `AGENT_CONTROL_ADMIN_API_KEYS`.
->
-> In the example .env, the placeholders are:
->
-> - **Regular API key(s):** `AGENT_CONTROL_API_KEYS` (e.g., "my-ui-key")
-> - **Admin API key(s):** `AGENT_CONTROL_ADMIN_API_KEYS` (e.g., "my-admin-key")
->
-> **Replace these defaults before any shared or production deployment.**
-
-**With authentication enabled:**
-
-```bash
-curl -L https://raw.githubusercontent.com/agentcontrol/agent-control/refs/heads/main/docker-compose.yml | AGENT_CONTROL_API_KEY_ENABLED=true AGENT_CONTROL_API_KEYS="my-ui-key" AGENT_CONTROL_ADMIN_API_KEYS="my-admin-key" AGENT_CONTROL_SESSION_SECRET="some-long-random-string" CORS_ORIGINS="http://localhost:4000" docker compose -f - up -d
-```
-
+<Note>
+Authentication is disabled by default for local development. When you're ready to deploy, see the [Enable Authentication](/how-to/enable-authentication) guide.
+</Note>
 
 ### What Is Happening Under the Hood
 
@@ -228,112 +215,14 @@ Key Benefits:
 
 - ✅ View analytics and control execution in the dashboard
 
-## Performance
-
-| Endpoint | Scenario | RPS | p50 | p99 |
-|----------|----------|-----|-----|-----|
-| Agent init | Agent with 3 tool steps | 509 | 19 ms | 54 ms |
-| Evaluation | 1 control, 500-char content | 437 | 36 ms | 61 ms |
-| Evaluation | 10 controls, 500-char content | 349 | 35 ms | 66 ms |
-| Evaluation | 50 controls, 500-char content | 199 | 63 ms | 91 ms |
-| Controls refresh | 5-50 controls per agent | 273-392 | 20-27 ms | 27-61 ms |
-
-- Agent init handles both create and update identically (create-or-update operation).
-- All four built-in evaluators (regex, list, JSON, SQL) perform within 40-46 ms p50 at 1 control.
-- Moving from 1 to 50 controls increased evaluation p50 by about 27 ms.
-- Local laptop benchmarks are directional and intended for developer reference. They are not production sizing guidance.
-
-_Performance tested on Apple M5 (16 GB RAM), Docker Compose (`postgres:16` + `agent-control`). 2 minutes per scenario, 5 concurrent users for latency (p50, p99), 10-20 for throughput (RPS). RPS = completed requests per second. All scenarios completed with 0% errors._
-
-## Configuration
-
-### Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `AGENT_CONTROL_URL` | `http://localhost:8000` | Server URL for SDK |
-| `AGENT_CONTROL_API_KEY` | — | API key for authentication (if enabled) |
-| `AGENT_CONTROL_DB_URL` | `postgresql+psycopg://agent_control:agent_control@localhost:5432/agent_control` | Server database URL (SQLite: `sqlite+aiosqlite:///./agent_control.db`) |
-| `GALILEO_API_KEY` | — | Required for Luna-2 AI evaluator |
-
-### Server Configuration
-
-The server supports additional environment variables:
-
-- `AGENT_CONTROL_API_KEY_ENABLED` - Enable API key authentication (default: `false`)
-- `AGENT_CONTROL_API_KEYS` - Valid API keys for runtime/read access when auth is enabled
-- `AGENT_CONTROL_ADMIN_API_KEYS` - Admin API keys required for control-plane mutations
-- `LOG_LEVEL` - Logging level (default: `INFO`)
-
-See  [Server Docs](/components/server) for complete server configuration.
-
----
-
-## Agent Control Components
-
-Agent Control is built as a monorepo with these components:
-
-- **[Server](/components/server)** - FastAPI server handling control evaluation, agent registration, and analytics
-- **[Engine](/components/engine)** - Evaluation engine that orchestrates control checks and applies actions
-- **[Models](/components/models)** - Shared data models and schemas used across all components
-- **[Evaluators](/components/evaluators)** - Built-in and AI-powered evaluators (regex, list, JSON, SQL, Luna-2)
-- **[UI](/components/ui)** - Next.js dashboard for managing controls, agents, and viewing analytics
-- **SDKs** - Python and TypeScript client libraries for integrating with your agents
-
----
-
-## Development
-
-### Directory Structure
-
-```text
-agent-control/
-├── sdks/python/     # Python SDK (agent-control)
-├── sdks/typescript/ # TypeScript SDK (generated)
-├── server/          # FastAPI server (agent-control-server)
-├── engine/          # Evaluation engine (agent-control-engine)
-├── models/          # Shared models (agent-control-models)
-├── evaluators/      # Evaluator implementations (agent-control-evaluators)
-├── ui/              # Next.js web dashboard
-├── scripts/         # Build scripts
-└── examples/        # Usage examples
-```
-
-### Makefile Commands
-
-The project uses a Makefile for common tasks:
-
-| Command | Description |
-|---------|-------------|
-| `make sync` | Install dependencies for all workspace packages |
-| `make test` | Run tests across all packages |
-| `make lint` | Run ruff linting |
-| `make lint-fix` | Run ruff with auto-fix |
-| `make typecheck` | Run mypy typechecking |
-| `make check` | Run all quality checks (test + lint + typecheck) |
-| `make server-run` | Start the server |
-| `make server-<target>` | Forward commands to server (e.g., `make server-alembic-upgrade`) |
-| `make sdk-<target>` | Forward commands to SDK (e.g., `make sdk-test`) |
-| `make engine-<target>` | Forward commands to engine (e.g., `make engine-test`) |
-
----
-
-## Next Steps
-
-- **Add more controls:** See [Controls](/concepts/controls#defining-controls) for examples and guidance
-
-- **Explore evaluators:** See [Evaluators](/concepts/evaluators/overview) or create custom evaluators. See [DeepEval example](/examples/deepeval) for custom evaluator examples
-
-- **Production setup:** Enable authentication — see the [Reference](/core/reference#authentication)
-
-- **Check examples:** See [Examples](/examples/overview) for real-world patterns
-
-> **💡 Pro Tip:** Start with simple regex controls, then graduate to AI-powered evaluators for complex safety checks.
-
 ## What’s Next
 
 <CardGroup cols={2}>
 
+  <Card title="UI Quickstart" icon="desktop" href="/core/ui-quickstart">
+    Manage agents and controls visually through the dashboard.
+  </Card>
+
   <Card title="Concepts" icon="lightbulb" href="/concepts">
     Learn about controls, selectors, evaluators, and actions.
   </Card>
@@ -342,4 +231,8 @@ The project uses a Makefile for common tasks:
     See working integration examples with LangChain, CrewAI, and more.
   </Card>
 
+  <Card title="Performance" icon="gauge-high" href="/concepts/performance">
+    See benchmark results showing Agent Control adds negligible latency.
+  </Card>
+
 </CardGroup>

docs.json

@@ -35,6 +35,7 @@
               "concepts/overview",
               "concepts/architecture",
               "concepts/controls",
+              "concepts/performance",
               {
                 "group": "Evaluators",
                 "pages": [
@@ -56,7 +57,8 @@
           {
             "group": "How-to Guides",
             "pages": [
-              "how-to/decorate-llm-tool-calls"
+              "how-to/decorate-llm-tool-calls",
+              "how-to/enable-authentication"
             ]
           },
           {

how-to/enable-authentication.mdx

@@ -0,0 +1,109 @@
+---
+title: Enable Authentication
+description: Secure your Agent Control server with API key authentication for shared and production deployments.
+icon: "lock"
+---
+
+Authentication is disabled by default so you can get started quickly in local development. Before sharing your server or deploying to production, enable API key authentication to protect the control plane from unauthorized access.
+
+## How It Works
+
+Agent Control uses a two-tier API key model:
+
+| Key type | Environment variable | What it can do |
+|----------|---------------------|----------------|
+| **Regular** | `AGENT_CONTROL_API_KEYS` | Register agents, evaluate controls, read controls and agents |
+| **Admin** | `AGENT_CONTROL_ADMIN_API_KEYS` | Everything above **plus** create/update/delete controls and manage agent-control associations |
+
+The `/health` endpoint is always public and requires no authentication.
+
+<Tip>
+Give your agent runtime a **regular** key. Reserve **admin** keys for setup scripts, CI pipelines, and the UI dashboard.
+</Tip>
+
+## Step-by-Step Setup
+
+<Steps>
+<Step title="Start the server with authentication enabled">
+
+Pass the authentication environment variables when starting the server:
+
+```bash
+curl -L https://raw.githubusercontent.com/agentcontrol/agent-control/refs/heads/main/docker-compose.yml \
+  | AGENT_CONTROL_API_KEY_ENABLED=true \
+    AGENT_CONTROL_API_KEYS="my-runtime-key" \
+    AGENT_CONTROL_ADMIN_API_KEYS="my-admin-key" \
+    AGENT_CONTROL_SESSION_SECRET="some-long-random-string" \
+    CORS_ORIGINS="http://localhost:4000" \
+    docker compose -f - up -d
+```
+
+<Warning>
+Replace the placeholder key values above with strong, unique secrets before any shared or production deployment.
+</Warning>
+
+</Step>
+
+<Step title="Pass the API key from the SDK">
+
+The SDK reads the `AGENT_CONTROL_API_KEY` environment variable by default, or you can pass it explicitly:
+
+```python
+from agent_control import AgentControlClient
+
+# Option 1: Environment variable (recommended)
+# export AGENT_CONTROL_API_KEY="my-runtime-key"
+async with AgentControlClient() as client:
+    await client.health_check()
+
+# Option 2: Explicit constructor argument
+async with AgentControlClient(api_key="my-runtime-key") as client:
+    await client.health_check()
+```
+
+</Step>
+
+<Step title="Use an admin key for control management">
+
+Operations that modify controls or agent-control associations require an admin key. This keeps your control plane locked down even if a runtime key is compromised.
+
+```python
+# setup.py — run with an admin key
+async with AgentControlClient(api_key="my-admin-key") as client:
+    await controls.create_control(client, name="block-ssn", data={...})
+    await agents.add_agent_control(client, agent_name="my-agent", control_id="...")
+```
+
+</Step>
+
+<Step title="Include the key in direct API calls">
+
+If calling the REST API directly, include the key in the `X-API-Key` header:
+
+```bash
+curl -H "X-API-Key: my-runtime-key" \
+  http://localhost:8000/api/v1/agents
+```
+
+</Step>
+</Steps>
+
+## Key Rotation
+
+Agent Control accepts multiple comma-separated keys per variable, making zero-downtime rotation straightforward:
+
+1. Add the new key alongside the old one: `AGENT_CONTROL_API_KEYS="old-key,new-key"`
+2. Redeploy the server
+3. Update all clients to use the new key
+4. Remove the old key: `AGENT_CONTROL_API_KEYS="new-key"`
+5. Redeploy again
+
+## Troubleshooting
+
+**401 Unauthorized** — check these in order:
+
+1. Authentication is enabled (`AGENT_CONTROL_API_KEY_ENABLED=true`)
+2. Your key is present in the correct variable (`AGENT_CONTROL_API_KEYS` for regular, `AGENT_CONTROL_ADMIN_API_KEYS` for admin operations)
+3. The `X-API-Key` header (or SDK `api_key` argument) matches exactly — no trailing whitespace or quotes
+
+See the [Authentication reference](/core/reference#authentication) for the full configuration table.