From first flow to full automation.

01 / INSTALLATION

Choose the package for where Knodr will run.

Knodr supports Windows x64, Linux x64, and Apple silicon macOS. Desktop packages include the visual app, CLI, and MCP server; headless packages contain the self-contained CLI and MCP server for terminals and CI.

01A / WINDOWS X64

Install Knodr on Windows

The standard setup installs the desktop app, knodr.exe CLI, MCP server, and Windows UI-automation component for the current user. It does not require a separate .NET runtime or administrator-wide install.

1. 01
   Download the setup

   Get Knodr-win-Setup.exe. The early build is unsigned; if SmartScreen appears, choose More info → Run anyway after confirming the file came from dl.knodr.com.

2. 02
   Run the installer

   Open the downloaded file, finish setup, then launch Knodr from the Start menu. The active release is stored under %LOCALAPPDATA%\Knodr\current.

3. 03
   Enable terminal access

   Add %LOCALAPPDATA%\Knodr\current to your user PATH, or invoke knodr.exe by its full path.

$ $env:Path += ";$env:LOCALAPPDATA\Knodr\current"
$ knodr --version
$ knodr doctor

For an unpacked install, download Knodr-win-Portable.zip, extract it to a permanent folder, and run Knodr.App.exe or .\knodr.exe there. The portable build does not configure PATH or automatic updates.

01B / LINUX X64

Install Knodr on Linux

Use the AppImage for the desktop app. For a headless CLI, install the Homebrew Formula or use install.sh on a machine without Homebrew. Every option is self-contained and does not require the .NET runtime.

Desktop AppImage

1. 01
   Download the app

   Get Knodr-linux.AppImage and keep it wherever you store applications.

2. 02
   Make it executable

   Run chmod +x Knodr-linux.AppImage. Install a FUSE 2 runtime if your distribution does not already provide one: libfuse2t64 on Ubuntu 24.04, or fuse/libfuse2 on many other distributions.

3. 03
   Launch it

   Run ./Knodr-linux.AppImage. If FUSE is unavailable, use ./Knodr-linux.AppImage --appimage-extract-and-run.

$ chmod +x Knodr-linux.AppImage
$ ./Knodr-linux.AppImage

Headless CLI and MCP server

The same Formula supports Linux x64 and Apple silicon macOS. Homebrew verifies the immutable release checksum, publishes knodr on PATH, and manages upgrades and removal.

$ brew install smurz/tap/knodr
$ knodr --version
$ knodr doctor

Without Homebrew: the per-user installer verifies the archive, stores immutable versions under ~/.local/share/knodr/, atomically updates the current symlink, and links ~/.local/bin/knodr. Do not run it with sudo.

$ ( set -eu; f=$(mktemp); trap 'rm -f "$f"' EXIT INT TERM; curl -fSL https://dl.knodr.com/install.sh -o "$f"; sh "$f" )
$ export PATH="$HOME/.local/bin:$PATH"
$ knodr --version
$ knodr doctor

If ~/.local/bin is not already on PATH, add the export to your shell profile. The installer refuses to overwrite an unmanaged file or symlink named knodr at that location.

01C / MACOS · APPLE SILICON

Install Knodr on macOS

The macOS package supports Apple silicon Macs and includes the desktop app, CLI, MCP server, Keychain integration, scoped processes, and the Accessibility-based automation component. Intel Macs are not supported yet.

1. 01
   Download the package

   Get Knodr-osx-Setup.pkg and open it. For an unpacked app, use the portable ZIP instead.

2. 02
   Approve the first launch

   The early build is unsigned and not notarized. If Gatekeeper blocks it, open System Settings → Privacy & Security and choose Open Anyway for Knodr.

3. 03
   Allow automation when needed

   Before using ui.automate or MCP UI inspection, enable the bundled Knodr automation component under Privacy & Security → Accessibility.

Terminal-only install

The Homebrew Formula installs the self-contained Apple silicon CLI, verifies its SHA-256 checksum, and publishes it on PATH:

$ brew install smurz/tap/knodr
$ knodr --version
$ knodr doctor

Upgrade with brew upgrade knodr and remove it with brew uninstall knodr. The Linux install.sh intentionally rejects macOS.

01D / CI RUNNERS

Connect Knodr to CI

For an ephemeral Linux x64 runner, extract the headless tarball, add its directory to PATH, validate the committed flow, and run it. The binary is self-contained: hosted Ubuntu needs no .NET runtime, desktop packages, libsecret, or keyring.

- uses: actions/checkout@v6

- name: Install knodr CLI
  run: |
    mkdir -p "$HOME/.local/knodr"
    curl -fSL https://dl.knodr.com/knodr-linux-x64.tar.gz | tar xz -C "$HOME/.local/knodr"
    echo "$HOME/.local/knodr" >> "$GITHUB_PATH"

- name: Validate and run the flow
  env:
    KNODR_CREDENTIAL_OPENAI: ${{ secrets.OPENAI_API_KEY }}
  run: |
    knodr doctor flows/ci.knodrflow --deep --output-format json
    knodr validate flows/ci.knodrflow
    knodr run flows/ci.knodrflow --timeout 15m --output-format json

knodr_flow:
  image: debian:bookworm-slim
  variables:
    KNODR_CREDENTIAL_OPENAI: $OPENAI_API_KEY
  before_script:
    - apt-get update && apt-get install -y --no-install-recommends ca-certificates curl tar
    - mkdir -p /opt/knodr
    - curl -fSL https://dl.knodr.com/knodr-linux-x64.tar.gz | tar xz -C /opt/knodr
    - export PATH="/opt/knodr:$PATH"
  script:
    - knodr doctor flows/ci.knodrflow --deep --output-format json
    - knodr validate flows/ci.knodrflow
    - knodr run flows/ci.knodrflow --timeout 15m --output-format json

CI requirements and secrets

• Use KNODR_CREDENTIAL_<UPPER_SNAKE_NAME> for protected CI secrets; never commit a secret or pass it through --var.
• The stable tarball URL follows the latest release. For reproducible jobs, pin an immutable artifact such as https://dl.knodr.com/knodr-<version>-linux-x64.tar.gz.
• If a flow uses agent.cli, install its agent command in the job and use API keys rather than interactive login. If it uses Python, ensure the python command exists; minimal Debian/Ubuntu images may need python-is-python3.
• On a self-hosted Windows runner, install the standard or portable Windows bundle for the runner service account, add its directory to that account's PATH, and restart the runner service before executing knodr.

See the small CI flow tutorial for exit-code handling, or the multi-agent CI tutorial for complete GitHub Actions, GitLab CI, and self-hosted Windows examples with reports and SARIF.

02 / DESKTOP UI

Build and debug on the canvas

The desktop app is the quickest way to understand a flow. Its canvas is the graph; the palette adds work; and the inspector shows the selected node and the values produced by a run.

Plaintext project variables

Use Project → Configuration for non-sensitive values referenced as {{var.NAME}}. These values are saved in the flow, so they are suitable for flags, paths, and defaults—not credentials.

03 / SECRETS

Store references in flows, never secret values

Nodes that need credentials use a name such as openai-personal in their credentialRef field. Knodr resolves the value only when the node runs.

Add a secret

1. Open Settings → Secrets.
2. Enter a memorable name and the secret value, then select Save.
3. Enter that same name in the node's credentialRef field.

$ $env:KNODR_CREDENTIAL_OPENAI_PERSONAL = "your-api-key"
$ knodr run .\flows\assistant.knodrflow

04 / CLI

Validate, run, and automate from a terminal

The CLI is designed for local scripts and CI. Human-readable output is the default; add --output-format json when another program will consume the result.

Check a flow before running it

$ knodr validate .\flows\main.knodrflow
$ knodr doctor .\flows\main.knodrflow

Run with input and variables

$ knodr run .\flows\review.knodrflow `
    --input "Review the staged changes" `
    --var MODE=strict `
    --timeout 2m

$ Get-Content .\prompt.txt -Raw |
    knodr run .\flows\review.knodrflow --output-format json

--input, --input-file, or redirected stdin binds to a flow with exactly one Manual Input node. Repeat --var NAME=value for runtime overrides, or use --vars-file with a KEY=VALUE file.

Useful commands

05 / MCP

Give an agent the Knodr toolset

knodr mcp starts a local stdio MCP server. It exposes the node catalog, flow authoring and validation, run control and observability, plus node-level debugging. The --project directory is the base for relative flow paths and run history.

Register the server in an MCP client

Add a server entry to the configuration used by your MCP client. Use absolute paths so the client can start Knodr regardless of its working directory.

{
  "mcpServers": {
    "knodr": {
      "command": "C:\\Users\\you\\AppData\\Local\\Knodr\\current\\knodr.exe",
      "args": [
        "mcp",
        "--project",
        "C:\\work\\my-project"
      ]
    }
  }
}

Restart the MCP client after changing its configuration. If you use the portable build, point command at the extracted knodr.exe instead.

{
  "mcpServers": {
    "knodr": {
      "command": "/home/you/.local/share/knodr/current/knodr",
      "args": [
        "mcp",
        "--project",
        "/home/you/work/my-project"
      ]
    }
  }
}

On Linux, point command at ~/.local/share/knodr/current/knodr — the path install.sh maintains — or the knodr binary extracted from the AppImage.

Use the tools as a workflow

1. Discover: call list_nodes and get_node_schema before choosing node types and ports.
2. Author: scaffold a project or flow, then use add_node, set_node_params, and connect_nodes.
3. Check: call organize_flow and validate_flow. Fix validation errors before execution.
4. Run: call start_run, then poll get_run_status; use logs and snapshots when a run needs inspection.

Restrict execution when needed

Add --read-only to the MCP arguments to remove execution and node-debugging tools. Catalog, validation, and flow-authoring tools remain available, so use filesystem permissions as the boundary when the client must not edit flows.

06 / REFERENCE & TUTORIALS

Start small. Scale to production patterns.

Go from a two-node first flow to production-derived multi-agent systems. Every tutorial explains the runtime contract and includes a downloadable .knodrflow.