blacklake

blacklake

AI control infrastructure and analytics. The unified BlackLake package (Surface SDK, Depth SDK, CLI, durable workflow runtime, and the blx shell wrapper) in one install.

For the canonical definition of what each piece does, see the product contract.

Install

npm i blacklake

That single install gives you the SDK (import { govern, BlackLake, workflow, step } from 'blacklake'), the CLI (blacklake, alias bl), and the shell wrapper (blx).

Quick start (local)

No account, no cloud, no Docker:

npx blacklake serve

Boots the API, a dashboard, and a local SQLite database, and opens the dashboard in your browser. Leave it running and open a second terminal.

BlackLake denies by default: a brand-new workspace has no agents, tools, or policies yet, so govern() has nothing to say yes to. Register an agent and a tool once, by name (govern() resolves by name, not id, so there's nothing to copy out of the response):

curl -s -X POST http://localhost:3100/v1/agents \
  -H 'content-type: application/json' \
  -d '{"name":"hello-agent","environment":"development","risk_classification":"low"}' > /dev/null

curl -s -X POST http://localhost:3100/v1/tools \
  -H 'content-type: application/json' \
  -d '{"name":"hello.tool","risk_classification":"low"}' > /dev/null

Now ask BlackLake for a decision:

BLACKLAKE_API_URL=http://localhost:3100 npx blacklake govern \
  --agent-name hello-agent --tool-name hello.tool --tool-action test

decision: deny
evaluation_id: eval_...
reason: Tool 'hello.tool' is not bound to agent 'hello-agent'. Every agent must be explicitly allowed to use a tool before it can be governed — bind it via bl.agents.bindTool(agentId, toolId) or in the Agents page of the console.

That deny is correct, not a bug: deny-by-default is the point. Bind the tool and add an allow policy in the dashboard that just opened (http://localhost:3200) to see decision: allow on the next call.

Prefer the hosted console over local mode? npx blacklake login --key bl_... stores your key in ~/.blacklake/config.json so govern/blx/doctor pick it up automatically, no env var needed in every shell.

SDK

import { govern } from 'blacklake';

const decision = await govern({
  apiKey: process.env.BLACKLAKE_API_KEY,
  agent: 'expense-bot',
  tool: 'stripe.refund',
  action: { amount: 4200 },
});

if (decision.decision === 'allow') {
  // proceed with the call
}

For hot paths, instantiate the client once:

import { BlackLake } from 'blacklake';

const bl = new BlackLake({ apiKey: process.env.BLACKLAKE_API_KEY });
const decision = await bl.govern({ ... });

Timeouts and retries

Every request has a 60s timeout (timeoutMs) and retries up to 2 additional times on a retriable failure (maxRetries), both configurable:

const bl = new BlackLake({
  apiKey: process.env.BLACKLAKE_API_KEY,
  timeoutMs: 10_000, // per attempt, not per call. See note below
  maxRetries: 1,
});

timeoutMs bounds a single fetch attempt, not the whole call. With retries enabled, worst-case wall time for one logical call is up to (maxRetries + 1) * timeoutMs plus backoff between attempts. Lower both together if you need a hard ceiling on total latency.

Mutating calls (POST/PATCH/PUT/DELETE) are automatically sent with a generated Idempotency-Key so retries (including after a client-side timeout, which does not prove the server never processed the request) can't double-execute a side effect; the server returns the original response for a repeated key instead of re-running it. GET requests always retry on a retriable failure since they have no side effects.

Durable workflows

Prerequisites for this exact snippet: npx blacklake serve running (or BLACKLAKE_API_KEY set for the hosted console instead), a filesystem MCP server registered in ~/.blacklake/mcp-config.json (so ctx.tool() has something to call), and ANTHROPIC_API_KEY set (ctx.llm() calls Anthropic).

import { workflow, step } from 'blacklake';

export default workflow('research', async (ctx) => {
  const data = await step(ctx, 'gather', async () => {
    return await ctx.llm('anthropic:claude-sonnet-4-6', {
      prompt: 'Find recent papers on AI governance',
    });
  });

  await step(ctx, 'save', async () => {
    await ctx.tool('filesystem.write_file', {
      path: './report.md',
      content: data,
    });
  });
});

Run with:

npx blacklake run workflow.ts

A fuller runnable version of this workflow, with governance receipts and crash recovery, is in examples/depth-research-report.ts.

CLI

Implemented commands:

npx blacklake serve              # local API + dashboard + SQLite (Surface)
npx blacklake run workflow.ts    # durable workflow runtime (Depth)
npx blacklake govern [flags]     # one-off govern() call from the shell: quick policy probe
npx blacklake mcp                # MCP stdio bridge for AI tool integration
npx blacklake shell <cmd...>     # gate any shell command on a governed decision (alias of blx)
npx blacklake blx <cmd...>       # same as above
npx blacklake demo <name>        # scaffold a runnable demo workspace
npx blacklake doctor             # preflight checks (config, key, connectivity)
npx blacklake login [--key ...]  # store an API key, cloud or self-hosted (prompts if --key is omitted)
npx blacklake logout              # clear the stored API key
npx blacklake init                # set up local mode, print a doctor summary and next steps

blacklake govern mirrors bl.govern() from the SDK, taking --agent-name, --tool-name, --tool-action, --input '<json>', --engine, --workflow-id, --run-id, and --json to suppress prose output. Auth comes from BLACKLAKE_API_KEY (cloud) or none (local mode); BLACKLAKE_API_URL overrides the base URL. Use it to probe policies from a terminal without writing a script.

blacklake shell is the same code path as blx: kept as an alias so the verb reads naturally when someone scans --help.

blacklake login/logout write to (and clear) the same ~/.blacklake/config.json that serve uses for local mode, so a cloud login and local mode don't fight over a second config file. blacklake init is the "first command a new user runs": it seeds local mode and prints next steps without starting the server, useful if you want config in place before scripting around it.

Not yet a CLI command (tracked as BL-FND-3): policy. Calling it exits 0 and points at the console/SDK instead of doing nothing.

blx: shell capture path

blx ships in the same package as a bin alias:

blx git push
blx terraform apply
blx gcloud run deploy

See the blx docs for custom classifiers and the cookbook.

Surface-only idioms: keep your existing engine

Already on Temporal, Inngest, BullMQ, GitHub Actions, or plain HTTP? Wrap each consequential step with withGovernance() and let Surface handle policy, approvals, cost, and signed receipts:

import { BlackLake, withGovernance } from 'blacklake';

const bl = new BlackLake({ apiKey: process.env.BLACKLAKE_API_KEY });

const result = await withGovernance(
  bl,
  {
    agent: 'support-bot',
    tool: 'stripe.refund',
    action: { amount_cents: 4200 },
    externalSystem: 'temporal',
    context: {
      engine: { engine: 'temporal', workflow_id: 'wf', run_id: 'r', step_id: 'refund', attempt: 1 },
    },
  },
  async () => stripe.refunds.create({ payment_intent: 'pi_3Nq8X', amount: 4200 }),
);

Runnable examples for Temporal, Inngest, and Express ship in examples/. See the examples README for the pattern.

Migrating from the old packages

@blacklake-systems/surface-cli, @blacklake-systems/surface-sdk, @blacklake-systems/depth-cli, @blacklake-systems/depth-sdk, and the standalone blx package all collapse into this one. See the migration doc for sed-style search-and-replace examples.

Links

• Docs: https://www.blacklake.systems/docs
• Product contract: https://www.blacklake.systems/docs/product-contract
• Console: https://console.blacklake.systems
• Why AI control & analytics: https://www.blacklake.systems/why-ai-control
• Manifesto: https://www.blacklake.systems/manifesto