Quickstart

Boot the four-agent debate mesh and run a recommendation in under a minute.

Prerequisites

• Node.js LTS
• pnpm 9+
• macOS or Linux

Install

For the published CLI:

npm install -g @zunocli/cli
export OPENAI_API_KEY=sk-...
export ZUNO_ARBITRUM_RPC_URL=https://...
zuno

The published CLI uses the hosted Zuno auth proxy for Turnkey email OTP. Users should provide their own OpenAI/Groq, RPC, and Uniswap Trading API keys as environment variables. Missing optional env is shown as a non-blocking notice when zuno starts.

For source development:

git clone <your-fork-url> zuno
cd zuno
pnpm install

For source development, configure the Turnkey-backed Zuno wallet, chain, and AXL peer ids:

export ZUNO_AGENT_WALLET_ADDRESS=0x...
export ZUNO_CHAIN_ID=42161
export ZUNO_ARBITRUM_RPC_URL=https://...
export ZUNO_MONITOR_INTERVAL_MS=60000
export TURNKEY_ORGANIZATION_ID=...
export TURNKEY_API_PUBLIC_KEY=...
export TURNKEY_API_PRIVATE_KEY=...

# AXL peer ids (one per role, plus the cli)
export ZUNO_AXL_CLI_PEER_ID=...
export ZUNO_AXL_SCOUT_PEER_ID=...
export ZUNO_AXL_STRATEGIST_PEER_ID=...
export ZUNO_AXL_CRITIC_PEER_ID=...
export ZUNO_AXL_ARBITER_PEER_ID=...

# Required for the LLM debate. Falls back to deterministic when unset.
export OPENAI_API_KEY=sk-...

Optional Telegram notifications for the monitor:

export ZUNO_TELEGRAM_BOT_TOKEN=
export ZUNO_TELEGRAM_CHAT_ID=

Optional: tune the debate.

export ZUNO_RISK_PROFILE=balanced       # conservative | balanced | aggressive
export ZUNO_MAX_DEBATE_ROUNDS=2         # strategist↔critic rounds before arbiter
export ZUNO_AGENT_MODEL=gpt-4o-mini     # any OpenAI model with structured outputs
export ZUNO_DETERMINISTIC=false         # set "true" to bypass the LLM entirely

All four agents in one command

pnpm --filter @zuno/strategy start:agents

Then in a second terminal:

pnpm cli

Manual: five terminals

If you want each agent’s log stream separately:

# terminal 1
axl

# terminal 2
pnpm --filter @zuno/strategy start:scout

# terminal 3
pnpm --filter @zuno/strategy start:strategist

# terminal 4
pnpm --filter @zuno/strategy start:critic

# terminal 5
pnpm --filter @zuno/strategy start:arbiter

Then, in a sixth terminal:

pnpm cli

Inside the shell:

create my zuno wallet
show my zuno wallet
fund my zuno wallet
inspect my positions
inspect position 42

# Open a brand-new position via the four-agent debate:
create a position with 0.05 ETH passively
approve it
apply it

# Or rebalance an existing one:
recommend what I should do with this position
show me the diff
simulate it
approve it
apply it

For live monitoring, run the worker in a separate terminal:

pnpm monitor

The worker writes local alerts to ~/.zuno/alerts.json. If Telegram env vars are configured, it also sends each new alert to the configured chat. In the shell, use:

show alerts
show my zuno wallet

Without the mesh

If the four agent peers aren’t visible on AXL, the CLI falls back to an in-process orchestrator that runs the same four handlers in one Node process. Same prompts, same deterministic tools, same transcript. The demo works either way.

If OPENAI_API_KEY is also unset (or ZUNO_DETERMINISTIC=true), the recommendation falls back further to the deterministic recommendPlan math - the legacy 1.4×/0.65× candidate generator with threshold-rule critique.