KOI-net Local Network (Quickstart)

This repo orchestrates a 7-node KOI-net stack locally.

For full operational detail, advanced setup, and troubleshooting, see RUNBOOK.md.

What This Does

• Clones all node repos
• Initializes .env files
• Syncs Python envs (uv)
• Starts/stops all nodes in protocol-safe order
• Auto-propagates coordinator contact and search target RIDs
• Runs end-to-end search queries

Zero to Hero (Copy/Paste)

Run from this repo root.

1) Bootstrap

make bootstrap

2) Set shared node key password

make set-shared-password PASSWORD='replace-with-strong-secret'

3) Configure GitHub sensor

make configure-github \
  GITHUB_API_TOKEN='ghp_...' \
  GITHUB_REPOSITORIES='owner/repo,owner/repo'

4) Configure HackMD sensor

make configure-hackmd \
  HACKMD_API_TOKEN='your-hackmd-token' \
  HACKMD_NOTE_IDS='note-id-1,note-id-2'

Optional for HackMD:

# add workspace scoping if needed
make configure-hackmd \
  HACKMD_API_TOKEN='your-hackmd-token' \
  HACKMD_WORKSPACE_ID='workspace-id' \
  HACKMD_NOTE_IDS='note-id-1,note-id-2'

5) Validate envs

make env-check

6) Start network

make up

7) Verify all nodes are up

make status

8) Run a query

make query \
  Q='koi network architecture' \
  TYPE=hybrid \
  TOP_K=10

9) Stop network

make down

Common Commands

make help
make logs
make restart
make query-tail UUID='<query-uuid>'

Full Documentation

• Full setup + token guidance + troubleshooting: RUNBOOK.md