iowap-node

IOWAP Node Framework — Build your own node in the IOWAP ecosystem

THIS IS THE REPO YOU WANT if you want to run a node. Clone this, configure your capabilities, and join the network.

The node framework provides everything you need to register, heartbeat, claim tasks, and run handlers. Nodes are the workers — they advertise what they can do and execute tasks when matched.

Quick Start (Linux)

One-liner — installs the Python package from PyPI into a dedicated venv (systemd user unit, registration; re-runs offer update / override / uninstall). IOWAP_SOURCE=git switches to a checkout-based dev install.

curl -fsSL https://raw.githubusercontent.com/iowap-org/iowap-node/main/install.sh | bash

From PyPI (manual, any platform):

pip install "iowap-node"          # import namespace: nodes
node-cli mcp install              # optional: the MCP toolkit (own venv)

From source (dev):

git clone https://github.com/iowap-org/iowap-node.git
cd iowap-node
pip install -e .
cp relay_config.json.example ~/.relay/relay_config.json
# edit ~/.relay/relay_config.json
node-cli node register
node-cli capabilities publish default

Updates: node-cli update check (node + MCP toolkit) and node-cli update apply — PyPI-first with the GitHub release as fallback.

What You Can Build

A node is just a process that:

1. Heartbeats its capabilities to a relay server (what can I do?)
2. Claims tasks that match its capabilities (I'll take this)
3. Runs handlers — scripts or programs — to execute the work
4. Completes tasks with results

Your capabilities are defined in a node.yaml:

node_name: "my-notifier"
node_description: "Sends push notifications"
capabilities:
  notification.send:
    description: "Send a push notification to my phone"
    type: script
    input_schema:
      fields:
        - name: title
          type: string
          required: true
          description: "Notification title"
        - name: body
          type: string
          required: true
          description: "Notification body"
        - name: priority
          type: string
          required: false
          description: "low / normal / high"

Just write a handler script that reads the JSON handler envelope from stdin, calls your push service, and writes the result to stdout. Your schema fields arrive NESTED under the input key of the envelope — not at the top level:

{"task_id": "...", "capability": "notification.send", "input": {"title": "...", "body": "...", "priority": "normal"}}

That is the frozen T-005b Envelope-Contract (handler_runner._build_stdin_payload); stdout is normalized back into the Response Envelope ({"status": "completed", "result": {...}}). That's it — the node framework handles the rest.

Components

CLI Reference

node-cli register                  # Register with a relay server
node-cli capabilities server       # List server-known capabilities
node-cli capabilities publish      # Publish your capabilities
node-cli task submit <capability>  # Submit a task
node-cli task wait <id>            # Wait for task completion
node-cli node list                 # List registered nodes
node-cli node info <id>            # Node details
node-cli daemon                    # Start the daemon (foreground)
node-cli bridge upload <file>      # Upload via bridge route
node-cli bridge download <url>     # Download via bridge route

Docker

A base Docker image is available for containerized nodes:

docker pull ghcr.io/iowap-org/iowap-node:latest

See docker/nodes/base/ for the Dockerfile.

Docs

Full documentation in iowap-org/iowap-docs:

• getting-started.md — first steps
• node/setup.md — node setup
• node/cli.md — full CLI reference
• node/capabilities.md — capability definitions
• federation/concept.md — cross-relay federation

License

MIT — see LICENSE.