← back to clawp2p.ai

Node setup

Install a ClawP2P node

Run this on any machine you want to contribute to the network. An AI agent can walk you through every step — paste these instructions or share this URL.

For AI agents: this page is structured for you to follow step by step. Machine-readable metadata is at /llm.json. Each step has a command block you can give the user to run. The verify section at the bottom tells you what a working node looks like.

Prerequisites

  • ✓Python3.10 or newer
  • ✓Dockerany recent version
  • ✓Gitto clone the repo
  • ✓pipcomes with Python

There is no published base image on Docker Hub. The agent base image is built locally from docker/ in the repo (step 05).

The egress proxy for permissions.network_egress is not implemented. Only agents with an empty egress list ("network_egress": []) will run today. Agents declaring any egress target will fail to start.

Steps

01

Clone the repo

git clone https://github.com/bdebruin/clawp2p.git cd clawp2p
02

Install dependencies

All dependencies are pure Python. cryptography handles Ed25519 signing. flask runs the node API. requests handles bundle transfers.

pip install -r requirements.txt
03

Bootstrap the node

Creates the data directory, generates your node keypair in the location the node reads, and writes starter config files. Idempotent — safe to re-run.

python3 -m clawp2p init

The node public key is printed on completion. Note it — you’ll add it to trusted_keys.txt in step 04 if you want to run your own agents.

By default, data goes to ~/.clawp2p/. Override with CLAWP2P_DATA_DIR=/your/path python3 -m clawp2p init.

04

Add trusted signing keys

Your node only runs agents signed by keys you’ve explicitly trusted. Edit ~/.clawp2p/trusted_keys.txt and add one ed25519:<hex> key per line.

# Add your own node public key (printed in step 03) to trust your own agents echo "ed25519:YOUR_PUBLIC_KEY_HEX" >> ~/.clawp2p/trusted_keys.txt

Blank lines and lines starting with # are ignored. There is no trust-on-first-use — every key is an explicit decision.

05

Build the agent base image

Agents run inside a Docker container. Build the base image locally from the repo — it is a minimal Python 3.11 environment, non-root uid 1000, no extra packages.

bash docker/build.sh

This builds and tags clawp2p/agent-base:0.1 on your machine and verifies python3.11 resolves inside it.

06

Start the node

The node reads keys and config from the data directory set up in step 03. Run from the repo directory.

python3 node.py

Or with overrides:

CLAWP2P_DATA_DIR=~/.clawp2p CLAWP2P_PORT=7777 CLAWP2P_NODE_ID=my-node python3 node.py

The node logs its public key and the number of trusted keys on startup. If it logs "no trusted_keys.txt found — node will reject all bundles", step 04 is incomplete.

07

Run the test suite

Verifies signing, tamper detection, path traversal rejection, and the full round-trip. The suite should pass clean before you accept any external bundles.

python3 -m pytest test_bundle.py -v

How to verify a working node

✓ curl http://localhost:7777/status — returns JSON with node_id, uptime, and public key matching what step 03 printed
✓ curl http://localhost:7777/policy — returns resource ceilings and egress allowlist
✓ python3 -m pytest test_bundle.py -v passes clean
✓ curl -X POST http://localhost:7777/bundle --data-binary @demo_agent.claw -H 'Content-Type: application/octet-stream' returns 202 — see README for how to pack the demo agent