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

npx blacklake init               # connect to cloud, or start local
npx blacklake login / logout     # auth with console.blacklake.systems
npx blacklake serve              # local API + dashboard + SQLite
npx blacklake run workflow.ts    # durable workflow runtime
npx blacklake policy simulate    # replay a draft policy

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.

JSPM

blacklake

Package Exports

Readme

blacklake

Install

SDK

Durable workflows

CLI

blx — shell capture path

Surface-only idioms — keep your existing engine

Migrating from the old packages

Links