walkthrough.md

Blacknode Beginner Walkthrough

This is the click-by-click path for trying every main Blacknode feature. Start with the no-key steps first, then add NVIDIA NIM, MCP, or Docker when the local workflow is working.

What You Need

Tool	Version	Why
Python	3.11+	Runs the workflow runtime, CLI, editor backend, and MCP server.
Node.js	20.19+ or 22.12+	Runs the visual editor.
npm	Ships with Node.js	Installs editor dependencies.
Docker	Optional	Runs the Compose stack and local NIM containers.
NVIDIA API key	Optional	Runs hosted NVIDIA NIM model calls.

1. Open the Project Folder

Open a terminal in the Blacknode repository.

Windows:

cd path\to\Blacknode

macOS/Linux:

cd path/to/Blacknode

2. Install Blacknode

Run this once. It installs the Python package, the blacknode command, and MCP support.

Windows:

pip install -e ".[mcp]"
cd editor-server
pip install -r requirements.txt
cd ..\editor
npm install
cd ..

macOS/Linux:

pip install -e ".[mcp]"
cd editor-server
pip install -r requirements.txt
cd ../editor
npm install
cd ..

What this does:

• pip install -e ".[mcp]" creates the blacknode terminal command from pyproject.toml.
• editor-server dependencies run the local backend on port 7777.
• editor dependencies run the browser UI on port 3000.

3. Check the Local Setup

Run:

blacknode doctor

Expected result:

• Green [OK] means that part is ready.
• Red [NOT OK] means install or fix that required part.
• Yellow [WARN] Editor server: not running is normal before starting the editor.
• The final line should say Required checks passed.

4. Run the First Workflow Without the Browser

Run:

blacknode demo

Expected result:

Blacknode demo OK
Result: Hello World

Now validate, run, and export the same workflow:

Windows:

blacknode validate templates\text-pipeline.json
blacknode run templates\text-pipeline.json
blacknode export-python templates\text-pipeline.json --output workflow.py
blacknode import-python workflow.py --output imported.workflow.json
python workflow.py

macOS/Linux:

blacknode validate templates/text-pipeline.json
blacknode run templates/text-pipeline.json
blacknode export-python templates/text-pipeline.json --output workflow.py
blacknode import-python workflow.py --output imported.workflow.json
python workflow.py

Expected result:

• validate returns "ok": true.
• run returns a JSON result with "value": "Hello World".
• import-python recreates workflow JSON from the exported Python file.
• python workflow.py prints Hello World.

5. Start the Visual Editor

Windows:

start.bat

macOS/Linux:

chmod +x start.sh
./start.sh

Expected result:

• Backend starts at http://127.0.0.1:7777.
• Editor starts at http://localhost:3000.
• Browser opens automatically when possible.
• If an old Blacknode editor is already on port 3000, the launcher restarts it and keeps the same URL.

If the browser does not open, open this manually:

http://localhost:3000

6. Load and Run a Template in the Editor

In the browser:

1. Look at the left sidebar.
2. Click the Templates tab.
3. Click Text Pipeline.
4. Click the Output node on the canvas.
5. In the right Properties panel, click Cook.

Expected result:

• The Output node shows Hello World.
• A small live cook status appears while the graph runs.
• The run is saved in the Runs tab.

7. Build the Same Workflow by Hand

In the editor:

1. Click Clear in the top bar.
2. Right-click the empty canvas.
3. Search for Text.
4. Click Text or press Enter.
5. Click the new Text node and set value to Hello.
6. Add a second Text node and set value to World.
7. Add a Concat node.
8. Add an Output node.
9. Drag from the first Text value handle to Concat a.
10. Drag from the second Text value handle to Concat b.
11. Drag from Concat value to Output value.
12. Click Organize in the top bar.
13. Click Cook on the Output node.

Expected result:

• The graph lays out cleanly.
• The Output node shows Hello World.
• The connection handles stay color-coded by type.

Useful edit controls:

• Press Ctrl+Z to undo.
• Select a line and press Delete or Backspace to remove it.
• Double-click a line to remove it immediately.
• Hold Alt while dragging a node to clone it.
• Press Ctrl+C and Ctrl+V to copy and paste selected nodes.

8. Save, Reopen, Duplicate, and Insert Workflows

In the left sidebar:

1. Click the Workflows tab.
2. Type a name such as Hello World Test.
3. Click Save.
4. Click the saved workflow row to reopen it in a tab.
5. Right-click the saved workflow row to see Insert, Rename, Duplicate, and Delete.

Expected result:

• Saved workflows appear in workflows/*.json.
• Clicking a workflow opens it as a tab.
• Insert drops a saved graph into the current canvas.

File import:

• Drag a Blacknode .json workflow onto the canvas to open it in a new tab.
• Drag a Blacknode-generated .py export, including LangGraph, onto the canvas to restore it as a visual workflow.

9. Inspect Run History and Replay

After any cook:

1. Click the Runs tab in the left sidebar.
2. Click the newest run row.
3. Look at status, duration, node count, model calls, and tool calls.
4. Use the replay controls to step or play through the execution.
5. Click Open workflow when a run has a saved workflow snapshot.

Expected result:

• The canvas highlights nodes as replay moves through events.
• Model calls and tool calls are counted.
• Successful runs show the returned value.
• Error runs show the error event and traceback.

Run records are written to:

editor-server/runs/

10. Add API Keys for Model Workflows

In the editor:

1. Add a Model node from the AI category or load an LLM template.
2. Pick a model from the dropdown.
3. Paste the provider API key into the key field.
4. Click the eye button to verify the key.
5. Press Enter or click away to save.

Provider keys:

Provider	Key
NVIDIA NIM	NVIDIA_API_KEY from https://build.nvidia.com
OpenAI	OPENAI_API_KEY from https://platform.openai.com/api-keys
Anthropic	ANTHROPIC_API_KEY from https://console.anthropic.com

Expected result:

• The key is saved in browser local storage for that provider.
• The editor sends the key to the local backend for model calls.
• The workflow result appears on the cooked node.

11. Try NVIDIA Planning Workflows Without an API Key

These templates prove the NVIDIA workflow surface before you call a hosted model.

Windows:

blacknode run templates\nvidia-ai-mission-control.json
blacknode run templates\nvidia-video-intelligence-mission-control.json
blacknode run templates\nvidia-local-nim-launch.json

macOS/Linux:

blacknode run templates/nvidia-ai-mission-control.json
blacknode run templates/nvidia-video-intelligence-mission-control.json
blacknode run templates/nvidia-local-nim-launch.json

Expected result:

• NVIDIA AI Mission Control returns a workflow plan and local readiness information.
• NVIDIA Video Intelligence Mission Control returns a video workflow plan for folder input, Cosmos/VLM understanding, NeMo Retriever indexing, NIM/Nemotron QA, deployment routing, and final report output.
• NVIDIA Local NIM Launch returns a Docker command and endpoint path.

In the editor:

1. Open Templates.
2. Click NVIDIA Video Intelligence Mission Control or NVIDIA AI Mission Control.
3. Click Cook on the Output node.
4. Open Runs and inspect the recorded execution.

12. Run Hosted NVIDIA NIM

Set a key in the editor Model node, or set it in the terminal before starting the backend.

Windows:

$env:NVIDIA_API_KEY="your-key"
start.bat

macOS/Linux:

export NVIDIA_API_KEY="your-key"
./start.sh

In the editor:

1. Open Templates.
2. Click NVIDIA NIM or NVIDIA NIM MCP Demo.
3. Click the Model node and confirm the NVIDIA model.
4. Click Cook on the Output node.
5. Open Runs and check model-call timing.
6. Open NVIDIA NIM Benchmark when you want repeated calls and latency metrics.

Expected result:

• The graph routes through NVIDIA NIM.
• The Output node shows the model response.
• The Runs panel records model-call events.
• The benchmark template returns text, latency, and metrics for the endpoint.

13. Generate a Local NIM Launch Command

Use this when you want the local NVIDIA NIM story.

In the editor:

1. Open Templates.
2. Click NVIDIA Local NIM Launch.
3. Click Cook on the Output node.
4. Copy the Docker command from the result.
5. Run that command in a separate terminal when you are ready to start the NIM container.
6. Use the shown endpoint in NIMHealthCheck, NIMAgent, or NIMBenchmark.
7. Open NVIDIA NIM Benchmark and set the endpoint to the local NIM URL when you want local latency metrics.

Expected result:

• Blacknode gives the command and endpoint wiring.
• The local endpoint can be checked before model calls are routed to it.

14. Connect an Agent Through MCP

Install MCP support first:

pip install -e ".[mcp]"

Start the MCP server:

blacknode mcp

Add this to an MCP client config:

{
  "mcpServers": {
    "blacknode": {
      "command": "blacknode",
      "args": ["mcp"]
    }
  }
}

Restart the MCP client, then ask:

Using the blacknode MCP tools, list the available node types, show the schema
for Text, Concat, and Output, then create a workflow that concatenates "Hello"
and " World", validates it, runs it, and exports it as Python.

Expected result:

• The agent lists node types.
• The agent creates a typed workflow.
• Validation passes.
• Running the workflow returns Hello World.
• Export returns runnable Python.

15. Connect AI-Q or NeMo Agent Toolkit With Streamable HTTP

Start Blacknode MCP over HTTP:

blacknode mcp --transport streamable-http --host 127.0.0.1 --port 9901 --path /mcp

Endpoint:

http://127.0.0.1:9901/mcp

Use that endpoint in MCP clients that support streamable HTTP.

Expected result:

• The same Blacknode tool surface is available over HTTP.
• AI-Q, NeMo Agent Toolkit, or another MCP client can use Blacknode as the visual workflow editor.

16. Run the Docker Compose Stack

Use this for the self-hosted demo path.

Windows:

.\docker-up.ps1

macOS/Linux:

docker compose up --build

Open:

http://127.0.0.1:3000

Services:

Service	Port	Purpose
editor	3000	Browser editor.
editor-server	7777	Backend, workflow store, run store, cook API.
blacknode-mcp	9901	Streamable HTTP MCP server at /mcp.

To add NVIDIA credentials:

Windows:

Copy-Item .env.example .env

macOS/Linux:

cp .env.example .env

Edit .env, set NVIDIA_API_KEY, then run:

.\docker-up.ps1

17. Create a Custom Node

In the editor:

1. Click the Script tab in the left sidebar.
2. Paste this code:

from blacknode.node import node

@node(inputs=["text:Text", "n:Int"], outputs=["result:Text"])
def FirstNWords(ctx: dict) -> dict:
    words = ctx.get("text", "").split()
    n = int(ctx.get("n", 10))
    return {"result": " ".join(words[:n])}

3. Click Run or press Ctrl+Enter to register it immediately.
4. Set a file name and click Save to keep it in custom-nodes/.
5. Open the node palette and find the new node in its category.
6. Add it to the canvas and cook it like any other node.

Expected result:

• The custom node appears without restarting the server.
• Saved custom nodes auto-load on the next Blacknode start.
• Its typed inputs and outputs can connect to compatible handles.

18. Try Tool and Agent Templates

In the editor:

1. Open Templates.
2. Click Python Tool Agent.
3. Inspect PythonFn, ToolBox, and AgentLoop.
4. Click Cook on the Output node.

For a no-model tool test:

1. Open Templates.
2. Click Subnet Tool Call.
3. Click Cook on the Output node.

Expected result:

• PythonFn exposes Python code as a callable tool.
• ToolBox collects one or more tools.
• ToolCall tests a tool directly with a dictionary of arguments.
• SubnetAsTool turns a visual subgraph into a callable tool.

19. Share a Workflow

Before sharing a workflow:

Windows:

blacknode validate workflows\your-workflow.json
blacknode export-python workflows\your-workflow.json --output exported_workflow.py
python exported_workflow.py

macOS/Linux:

blacknode validate workflows/your-workflow.json
blacknode export-python workflows/your-workflow.json --output exported_workflow.py
python exported_workflow.py

Expected result:

• Validation passes.
• Exported Python runs.
• The workflow JSON can be copied, committed, or promoted into templates/.

Troubleshooting

blacknode command not found

Run:

pip install -e ".[mcp]"

Then close and reopen the terminal. The command is created by the package entry point:

blacknode = "blacknode.cli:main"

Port 3000 is busy

Run the launcher again:

start.bat

or:

./start.sh

The launcher restarts an old Blacknode editor on port 3000. If another app is using the port, close that app or start it on a different port.

Editor server is not green

Start the backend manually:

cd editor-server
python server.py

Then refresh:

http://localhost:3000

Model calls do not run

Check that the matching key is saved in the Model node or set in the environment:

NVIDIA_API_KEY
OPENAI_API_KEY
ANTHROPIC_API_KEY

Feature Checklist

Use this as the demo checklist:

Feature	Where to try it
Local environment check	blacknode doctor
No-key workflow run	blacknode demo
Visual graph editing	Editor canvas
Templates	Templates tab
Save/reopen workflows	Workflows tab
Run replay	Runs tab
Python export	blacknode export-python
API keys and provider routing	Model node
NVIDIA NIM workflows	NVIDIA templates
NVIDIA video mission control	NVIDIA Video Intelligence Mission Control template
Local NIM command generation	NVIDIA Local NIM Launch template
Agent-controlled workflow building	blacknode mcp
AI-Q / NeMo MCP HTTP path	blacknode mcp --transport streamable-http ...
Docker deployment	.\docker-up.ps1 on Windows, docker compose up --build elsewhere
Custom nodes	Script tab
Tool workflows	Python Tool Agent and Subnet Tool templates