Quickstart

Get Sage running locally — client, server, and agent — in minutes.

Prerequisites

Tool	Version
Node.js	20+
pnpm	10+
Nanobot CLI	latest

You’ll also need accounts for:

• Privy — embedded Solana wallet + auth
• Supabase — patterns, rules, events, and audit storage
• A Solana RPC URL (Helius, Triton, QuickNode, or https://api.devnet.solana.com)
• A Telegram bot token — for review notifications
• Zerion — portfolio data

Install

This is a pnpm workspace. Run from the root:

git clone https://github.com/heysageme/sage
cd sage
pnpm install

Configure Environment

Client

Create client/.env.local:

NEXT_PUBLIC_API_URL=http://localhost:3001
NEXT_PUBLIC_SPONSOR_PUBKEY=<server keypair public address>
NEXT_PUBLIC_PRIVY_APP_ID=<from privy dashboard>
NEXT_PUBLIC_SOLANA_RPC_URL=<your rpc url>

Server

Create backend/.env:

SUPABASE_URL=https://your-project-ref.supabase.co
SUPABASE_SERVICE_ROLE_KEY=
PRIVY_APP_ID=
PRIVY_JWT_VERIFICATION_KEY=        # full JWK JSON from the Privy dashboard
ZERION_API_KEY=
AGENT_SECRET=                      # shared bearer token for agent + server-to-server
SPONSOR_SECRET_KEY=                # JSON byte array — the server's Solana keypair
SOLANA_RPC_URL=
TELEGRAM_BOT_TOKEN=
TELEGRAM_WEBHOOK_SECRET=           # optional
PORT=3001

See backend/.env.example for the full template. Apply the Supabase schema once before first run:

psql "$SUPABASE_DB_URL" -f backend/schema.sql

SPONSOR_SECRET_KEY is the server’s Solana keypair as a JSON byte array. It fee-pays every transaction and is added to each vault as a member with Execute permission. NEXT_PUBLIC_SPONSOR_PUBKEY on the client must be its public address.

Run Locally

1. Start the server

   pnpm dev:server
   # → http://localhost:3001
   
2. Start the client

   pnpm dev:client
   # → http://localhost:3000
   
3. Link the Sage skill into Nanobot

   mkdir -p ~/.nanobot/workspace/skills
   ln -sf "$(pwd)/agents" ~/.nanobot/workspace/skills/sage
   
   # Restart the gateway and verify detection
   nanobot gateway restart
   nanobot skills check
   

Verify It Works

1. Visit http://localhost:3000
2. Sign in with Privy → an embedded Solana wallet is created
3. A Squads multisig + vault is deployed for you (server-sponsored — no SOL needed)
4. Fund the vault address, then go to Send → enter a recipient and amount
5. Confirm → the transfer is sponsored, the proposal is registered with POST /queue, and the risk engine scores it
6. APPROVE: the server co-signs and executes; the tx signature appears in the UI and Telegram
7. REVIEW / BLOCK: check Telegram for the ✅ / ❌ / 🔎 message

Run the Tests

The Squads SDK helpers in src/ are covered by a Mocha suite:

pnpm test                                                    # all suites (needs a local validator)
pnpm test:reference                                          # the canonical 2-of-2 agentic co-signer flow
RPC_URL=https://api.devnet.solana.com pnpm test:reference    # against devnet

Troubleshooting

Vault not deploying

Confirm SPONSOR_SECRET_KEY decodes to a valid keypair and the sponsor account holds enough SOL to pay rent. Check SOLANA_RPC_URL is reachable.

Proposal stuck without a verdict

The risk engine needs the Supabase schema applied. Check server logs for getPatternsForSafe errors and confirm SUPABASE_SERVICE_ROLE_KEY is set.

No Telegram notification

Verify TELEGRAM_BOT_TOKEN is set, the bot has been started in your chat, and the vault has a telegram_chat_id (connect it from the app or /start the bot).

Balance not showing

Portfolio data requires a valid ZERION_API_KEY in backend/.env.

Agent commands not responding

Run nanobot skills check to confirm the Sage skill is detected and AGENT_SECRET matches the value in backend/.env.