Skip to content
BLACKLAKE
Sign up free
Quick start▾ docs nav

Getting Started

Start governing AI actions in under 5 minutes — cloud or local.

BlackLake is AI Control Infrastructure and Analytics. Sign up at console.blacklake.systems to route AI agents, coding tools, MCP clients, automation actors, SDK calls, and durable workflow steps through shared policies, approvals, budgets, analytics, exports, and signed receipts. Or run the same control layer locally with no cloud account.

Cloud is the fastest path to your first receipt. You get shared controls, approval email delivery, the coverage and risk dashboards, and receipt verification from any device — with no infrastructure to run.

Not sure which path is right? See the cloud-vs-self-hosted decision guide for a one-minute read on when each fits.

Cloud path — sign up and connect in 5 minutes#

Step 1 — Sign up#

Go to console.blacklake.systems/signup and create a workspace. Copy the API key shown once at signup — you'll need it in Step 3.

Step 2 — Connect your AI tool via MCP#

Add BlackLake to your tool's MCP configuration. In .mcp.json (Claude Code) or equivalent:

{
  "mcpServers": {
    "blacklake": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://api.blacklake.systems/mcp/o/YOUR_ORG_SLUG",
        "--header",
        "Authorization: Bearer YOUR_API_KEY"
      ]
    }
  }
}

Replace YOUR_ORG_SLUG with the slug shown in your workspace settings and YOUR_API_KEY with the key from Step 1. Restart your AI tool.

Step 3 — Watch your first evaluation appear#

Use your AI tool normally. Every tool call flows through BlackLake and appears in the Evaluations page in real time. If the first call shows default_deny, that means no policy matched — proceed to Step 4.

Step 4 — Write a policy#

Go to Policies → Create policy. For example, to require approval before any file writes:

  1. Name: approve-file-writes
  2. Priority: 10
  3. Outcome: Approval Required
  4. Agent selector: pick your filesystem agent from the dropdown
  5. Click Create policy

Approvals appear in Approvals. Approve or reject — each decision returns a signed receipt.

Step 5 — Verify your first receipt#

Open the Verify page. Paste the evaluation ID and decision token from any evaluation. The response confirms the outcome is authentic and binds the cost if a cost record is attached.

Run locally instead#

Prefer to evaluate on your machine before a team rollout? The same control layer runs locally with SQLite — no cloud account required.

npx blacklake serve

What happens:

  • Creates ~/.blacklake/ with a SQLite database and config
  • Starts the API on http://localhost:3100
  • Starts the dashboard on http://localhost:3200
  • Opens the dashboard in your browser

Then follow Steps 3–5 above, pointing your tool at the local MCP bridge instead:

{
  "blacklake": {
    "command": "node",
    "args": ["~/.blacklake/mcp-bridge.mjs"]
  }
}

Add MCP servers (local)#

Edit ~/.blacklake/mcp-config.json:

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "policy": "allow"
    }
  }
}
PolicyWhat happens
"allow"All tool calls are permitted
"deny"All tool calls are blocked
"ask"All tool calls require human approval in the dashboard

Restart BlackLake after editing the config (Ctrl-C then npx blacklake serve).

Capture LLM cost#

Path A — proxy your provider SDK through BlackLake. Token counts and dollar cost are captured automatically for Anthropic direct, OpenAI direct, and Ollama.

# Cloud
export ANTHROPIC_BASE_URL=https://api.blacklake.systems/proxy/anthropic

# Local
export ANTHROPIC_BASE_URL=http://localhost:3100/proxy/anthropic

Path B — attribute cost from your code. For Bedrock, Vertex, Foundry, Gemini, or any call BlackLake doesn't see on the wire:

await bl.cost.record({
  evaluation_id: result.evaluation_id,
  provider: 'bedrock',
  model: 'anthropic.claude-sonnet-4-6',
  input_tokens: 1820,
  output_tokens: 412,
});

Open Usage (cloud) or http://localhost:3200/usage (local) to see breakdowns by model, agent, tool, capture path, and user.

Set a budget#

Budgets deny at govern() time — before the spend — and fire webhooks at soft thresholds.

In the console, open Budgets → New budget and pick a scope:

  • Workspace — total monthly cap across every governed call
  • Agent — per-agent cap
  • Tool — per-tool cap
  • User — per-user cap (useful for shared dev workspaces)

Enter a soft limit and a hard limit. The soft limit fires budget.threshold_crossed webhook alerts at 50%, 80%, and 100% of the soft value — these thresholds are hardcoded today (an alert_at_percent field is on the roadmap, not shipped). The hard limit denies: the next govern() call from that scope returns decision: "deny" with a reason naming the budget.

The period field accepts day, week, month, or per_task — the underlying enum is the short form (not daily / monthly).

Mobile approvals (cloud only)#

  1. Verify your email. Push notifications only run for verified addresses.
  2. Open Settings → Mobile notifications. Click Enable push.
  3. iOS only — install to home screen. Safari on iPhone requires the page to be installed as a Home Screen app to deliver push notifications.

Approvals arrive as system notifications. Tapping opens a magic-link decision page — approve or reject in one tap.

Cloud quickstart — OAuth upstreams#

For upstreams that use OAuth 2.1 (Atlassian, Linear, Sentry, Notion, Slack), use the cloud console — it handles the OAuth handshake, token storage, and refresh. The local install cannot complete OAuth flows that require a public callback URL.

  1. Register the upstream under MCP → Upstreams → Add upstream.
  2. Set up OAuth. Click Set up OAuth on the upstream row.
  3. Connect. Click Connect and grant permissions in the popup.
  4. Mint a user-scoped key. Go to Settings → API keys → Generate key → User-scoped. User-scoped keys are required for OAuth upstreams.
  5. Point your MCP client at https://api.blacklake.systems/mcp/u/YOUR_UPSTREAM with your user-scoped key in the Authorization header.

Next steps#