Getting Started

This is the shortest path from an existing agent to a Blackbox-backed workflow.

1. Register A Workflow

In the Blackbox dashboard:

create or select your workspace
register a workflow
copy the Blackbox API key shown on that workflow card

That key is the credential your application will send on every compile and invoke request for that workflow.

2. Set `BLACKBOX_API_KEY` And `BLACKBOX_URL`

Expose both Blackbox environment variables to your runtime:


export BLACKBOX_API_KEY="bb_live_xxxxxxxxxxxxxxxx"
export BLACKBOX_URL="https://allocator.agentir.dev"

In production, store it the same way you store provider credentials: a secret manager, deployment secret, or CI secret.

BLACKBOX_API_KEY authenticates compile requests and is reused as the bearer token for runtime chat-completion requests for one workflow. BLACKBOX_URL tells your runtime and the managed compile workflow which Blackbox deployment to call.

3. Choose How To Add Workflow Structure

Blackbox needs compile-visible workflow structure. You have two ways to provide it:

use the dashboard annotation flow so Blackbox opens a PR against your repo
add the annotation library yourself

Choose one of:

4. Attach Providers In The Dashboard

After the workflow exists, add or select the providers that can serve the models used by your workflow and attach them to that workflow.

Blackbox keeps your model choice fixed at the node level. What it chooses is the provider that should serve that model for the current run.

5. Compile The Workflow

After annotation is in place, Blackbox compiles the workflow structure so it can reason about nodes, dependencies, and the critical path.

If you use the annotation PR flow, the PR can also add a managed compile workflow to your repository so future updates stay tied to source changes.

6. Route LLM Calls Through Blackbox

At invoke time, send:

requests to $BLACKBOX_URL/v1/chat/completions
Authorization: Bearer $BLACKBOX_API_KEY
one shared rid for the workflow run
node-name for the current node

Example:


curl -X POST "$BLACKBOX_URL/v1/chat/completions" \
  -H "content-type: application/json" \
  -H "Authorization: Bearer $BLACKBOX_API_KEY" \
  -H "rid: run-2026-05-25-001" \
  -H "node-name: summarizer" \
  -d '{
    "model": "claude-opus-4.7",
    "messages": [{"role":"user","content":"Summarize this ticket for escalation."}]
  }'

7. Keep `rid` Stable Across One Run

This is important.

All LLM calls that belong to the same workflow execution should share the same rid. That is how Blackbox reconstructs the workflow run instead of treating each call as an unrelated request.

Minimal Runtime Example


const apiKey = process.env.BLACKBOX_API_KEY;
const blackboxUrl = process.env.BLACKBOX_URL;
 
const response = await fetch(`${blackboxUrl}/v1/chat/completions`, {
  method: "POST",
  headers: {
    "content-type": "application/json",
    Authorization: `Bearer ${apiKey!}`,
    rid: runId,
    "node-name": nodeName,
  },
  body: JSON.stringify({
    model: "claude-opus-4.7",
    messages: [{ role: "user", content: prompt }],
  }),
});

What To Expect

Once your workflow is compiled and providers are attached:

Blackbox chooses the provider for each node
the workflow keeps its original shape and model intent
your routing policy moves out of ad hoc application logic and into Blackbox

If you want Blackbox to prepare the repo changes for you, continue to Annotation.

If you want to drive the repo changes yourself through Codex or Claude Code, continue to Agent Skills.