Getting Started

Depth is the durable workflow layer inside BlackLake. Surface is the control plane and analytics layer. The blacklake package ships both: Surface SDK, Depth SDK, CLI, workflow runtime, and blx shell wrapper. Surface evaluates consequential Depth steps against your policies and budgets before they execute, routes approvals, records cost, and signs receipts; Depth workflows hit the same ledger as agents, coding tools, MCP clients, automation actors, and SDK calls. Run Surface either in the hosted console at console.blacklake.systems or locally via npx blacklake serve; the npm package runs Depth workflows locally and connects them to whichever Surface control plane you use.

Prerequisites#

Node.js 20 or later
An Anthropic, OpenAI, or Ollama endpoint (for LLM steps)

Installation#

Install the blacklake package once — it ships the SDK, CLI, and workflow runtime in one:

npm install -g blacklake

Or run directly with npx:

npx blacklake run workflow.ts

To use the workflow primitives as a library in your own project:

npm install blacklake

Set your API key#

For Anthropic models:

export ANTHROPIC_API_KEY=sk-ant-...

For OpenAI models:

export OPENAI_API_KEY=sk-...

Ollama requires no API key — it runs locally on http://localhost:11434.

Write your first workflow#

Create a file called hello.ts:

import { workflow, step } from 'blacklake';

export default workflow('hello', async (ctx) => {
  const greeting = await step(ctx, 'generate-greeting', async () => {
    return await ctx.llm('anthropic:claude-sonnet-4-6', {
      prompt: 'Write a single sentence welcoming someone to durable AI workflows.',
    });
  });

  console.log('\n  Result:', greeting);
  return { greeting };
});

Run the workflow#

blacklake run hello.ts

Output:

  depth · hello

  Starting run run_abc123

  ✓ generate-greeting
  Total cost: $0.0003

  Result: Welcome to durable AI workflows...

Re-running a workflow#

Each blacklake run invocation resolves to one of two things:

Resume a paused run. If a previous run is still running or paused (e.g. waiting on an approval signal), Depth picks it up and replays its completed steps from the database — no LLM calls re-issued for steps that already succeeded:
```
  depth · hello

  Resuming run run_abc123

  ↩ generate-greeting (replayed)
  Total cost: $0.0000
```
Start a fresh run. If the previous run already completed (or there's no previous run), blacklake run creates a new run_… id from scratch. Completed runs are immutable — re-running a completed workflow does not re-use its step outputs. Use blacklake depth list to see every run for a workflow, and blacklake depth status <run_id> to inspect any of them.

If you need to replay or re-execute a specific completed run for debugging, run it with a fresh file or use the SDK directly to construct the workflow against the run id you want.

Pass input to a workflow#

blacklake run hello.ts --input '{"topic": "governance"}'

Input is available as the second argument to your workflow function:

export default workflow('hello', async (ctx, input: { topic: string }) => {
  const greeting = await step(ctx, 'generate-greeting', async () => {
    return await ctx.llm('anthropic:claude-sonnet-4-6', {
      prompt: `Write a single sentence about ${input.topic}.`,
    });
  });
  return { greeting };
});

See run history#

blacklake depth list
blacklake depth status <run_id>

The Depth runtime is bundled into the blacklake CLI — there is no standalone depth binary. blacklake run <file> executes a workflow; blacklake depth list and blacklake depth status inspect run history.