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. Start Blacknode

The launcher performs first-run setup automatically. It creates a project-local .venv, installs Blacknode and the editor dependencies, starts the backend and visual editor, and opens the browser. Later starts reuse the installed files.

Windows:

.\start.bat

macOS/Linux:

chmod +x start.sh
./start.sh

What this does:

• Creates .venv and installs the Python runtime, CLI, backend, and MCP support.
• Installs the visual editor dependencies under editor/node_modules.
• Starts the backend on port 7777 and the browser UI on port 3000.
• Opens http://localhost:3000 when possible.

First-run time depends on network speed and whether pip/npm packages are already cached. Later starts normally complete in less than one minute.

On the first launch of this Blacknode workspace, a welcome message opens the Packages tab. Use it to install the official packages needed by robotics, ROS 2, vision, CUDA, dataset, and training templates. Choose Continue with core graph when you want to begin with built-in nodes. Blacknode records the choice in .blacknode/onboarding.json; Packages stays available in the left sidebar.

The welcome message opens only after the backend confirms that onboarding has not been completed. A backend startup or connectivity error keeps the current canvas state and is reported through the service status instead.

3. Check the Local Setup

Keep Blacknode running. In a second terminal, activate its environment once; the remaining blacknode commands in this guide will then work directly.

Windows:

.\.venv\Scripts\Activate.ps1
blacknode doctor

macOS/Linux:

source .venv/bin/activate
blacknode doctor

If PowerShell blocks activation, call the executable directly:

.\.venv\Scripts\blacknode.exe doctor

Expected result:

• Green [OK] means that part is ready.
• Red [NOT OK] means install or fix that required part.
• The editor-server check should be green because the launcher is still running.
• 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. Open the Visual Editor

The launcher from step 2 keeps the backend and visual editor running. Return to the browser window it opened.

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 you stopped the launcher, run .\start.bat or ./start.sh again.

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. Use the Templates tab, which is open by default after onboarding.
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 run status appears while the graph cooks once.
• The run is saved in the Runs tab.

An Output node connected to a typed image or video port opens at the same large dashboard size used by robot monitoring nodes. Live camera frames and video controls stay inside the node.

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

Activate the project environment:

.\.venv\Scripts\Activate.ps1

or run the executable directly:

.\.venv\Scripts\blacknode.exe doctor

On macOS/Linux, run source .venv/bin/activate. 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 Reference

Use this table to locate each major feature after completing the walkthrough:

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