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).

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({ ... });

Durable workflows

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.writeFile', {
      path: './report.md',
      content: data,
    });
  });
});

Run with:

npx blacklake run workflow.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)

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.

Planned (not yet implemented — tracked as BL-FND-3): init, login, logout, policy. Calling them today prints a "not yet implemented" message and exits non-zero rather than silently 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