Quickstart

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
Server

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>

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

Start the server

pnpm dev:server
# → http://localhost:3001

Start the client

pnpm dev:client
# → http://localhost:3000

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

Visit http://localhost:3000
Sign in with Privy → an embedded Solana wallet is created
A Squads multisig + vault is deployed for you (server-sponsored — no SOL needed)
Fund the vault address, then go to Send → enter a recipient and amount
Confirm → the transfer is sponsored, the proposal is registered with POST /queue, and the risk engine scores it
APPROVE: the server co-signs and executes; the tx signature appears in the UI and Telegram
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.

Get Started

Sage App

Technology

Prerequisites

Install

Configure Environment

Run Locally

Verify It Works

Run the Tests

Troubleshooting

​Prerequisites

​Install

​Configure Environment

​Run Locally

​Verify It Works

​Run the Tests

​Troubleshooting

Prerequisites

Install

Configure Environment

Run Locally

Verify It Works

Run the Tests

Troubleshooting