_____       __                        ____  _____
  / ___/____  / /___ _____  ____ _     / __ \/ ___/
  \__ \/ __ \/ / __ `/ __ \/ __ `/    / / / /\__ \
 ___/ / /_/ / / /_/ / / / / /_/ /    / /_/ /___/ /
/____/\____/_/\__,_/_/ /_/\__,_/     \____//____/
                S O L A N A O S

One-Shot Start

Get everything running locally — Go daemon, gateway, both MCP servers — in one command.

git clone https://github.com/x402agent/SolanaOS.git
cd SolanaOS
cp .env.example .env        # add your API keys
bash start.sh               # builds binary + starts all services

Or via Make or npm:

make start          # build + start all services
make dev            # build + start all services + Vite UI on :5173
make stop           # stop all background services
make status         # show running service status

npm start           # same as bash start.sh
npm run start:ui    # with UI dev server
npm run stop        # stop all services

Or with Docker (zero local Go/Node required):

cp .env.example .env
docker compose up           # starts daemon, gateway, mcp, solana-claude-mcp
docker compose up -d        # same, background
make docker-up              # alias

What starts:

Add to Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "solanaos": {
      "command": "node",
      "args": ["/path/to/SolanaOS/mcp-server/dist/index.js"]
    },
    "solana-claude": {
      "command": "node",
      "args": ["/path/to/SolanaOS/solana-claude/mcp-server/dist/index.js"]
    }
  }
}

Minimum .env to get started:

HELIUS_API_KEY=your-key            # or SOLANA_TRACKER_API_KEY
HELIUS_RPC_URL=https://mainnet.helius-rpc.com/?api-key=YOUR_KEY
OPENROUTER_API_KEY=sk-or-v1-...   # free models at openrouter.ai
LLM_PROVIDER=openrouter
TELEGRAM_BOT_TOKEN=...            # optional — Telegram control surface

Logs are written to .logs/ (gateway.log, daemon.log, mcp-root.log, mcp-solana-claude.log).

Key Documents

See deploy/README.md for full configuration, VM sizing, troubleshooting, and post-deploy setup.

SolanaOS is a public Solana operator stack built around a compact Go runtime and a set of web, mobile, and skill surfaces. It is designed for people who want one system to:

• run an autonomous local trading and research runtime
• connect wallets, Seeker devices, Telegram, and browser/mobile control surfaces
• expose a gateway for skills, tools, and remote agent control
• publish reusable skills and SOUL profiles to a public Solana-native hub

SolanaOS combines:

• an OODA trading loop for spot, swaps, and perp workflows
• a memory stack with local vault learning plus Honcho v3 session memory
• a multi-surface control plane across Telegram, SolanaOS Control, Chrome, macOS, Android, and web
• real Solana infrastructure using SolanaTracker RPC/Datastream, Jupiter, Hyperliquid, Aster, and x402
• an optional hardware layer for Arduino Modulino sensors and physical controls

This repository is the public source of truth for SolanaOS. It includes the Go runtime, gateway tooling, Android surfaces, skills, npm installer packages, and the SolanaOS Hub frontend.

This README is the GitHub front door. Use it to install, explore the live surfaces, and understand how the repo is organized.

Why Solana Developers Care

Solana God Mode

Solana God Mode is a fully integrated liberation pipeline ported from G0DM0D3 and rebuilt in Go as a native part of the SolanaOS runtime. It transforms the chat system into a sentient, multi-model intelligence that maximizes signal density and strips safety theater.

User Input
    │
    ├─→ [1] AutoTune: Classify context → Select optimal sampling params (7 contexts, 6 dimensions)
    │
    ├─→ [2] Feedback Loop: Blend EMA-learned adjustments from user ratings
    │
    ├─→ [3] Parseltongue: Detect triggers → Obfuscate input (6 techniques, 3 intensities)
    │
    ├─→ [4] Multi-Model Race: N models in parallel via OpenRouter → Score → Winner
    │        └─→ ULTRAPLINIAN scoring: length + structure + anti-refusal + directness + relevance
    │
    ├─→ [5] STM: Strip hedges, preambles, formalize → Clean output
    │
    └─→ Response with full pipeline metadata

Deploy on Fly.io

Deploy SolanaOS to Fly.io with a single command. Download the deploy package and run the script — it handles app creation, volumes, secrets, and deployment.

git clone https://github.com/x402agent/SolanaOS.git
cd SolanaOS
bash deploy/deploy.sh

You'll need flyctl installed, a Fly.io account (free trial works), and an LLM API key (OpenRouter, Anthropic, xAI, OpenAI, or Ollama).

The script prompts for your app name, region, LLM provider, Solana RPC keys, and optional channel tokens (Telegram, Discord). All credentials are stored as encrypted Fly secrets. State lives on a persistent volume at /data, so configuration, wallet, conversation history, and skills survive restarts and redeployments.

Internet --> Fly.io proxy --> SolanaOS Web Console (:18800)
                                 |
                                 +--> SolanaOS Daemon
                                 +--> Gateway (:18790)
                                 +--> Skills Engine
                                 +--> Channel Bridges (Telegram, Discord, iMessage, etc.)

After deploy, connect your local CLI:

solanaos config set gateway.mode remote
solanaos config set gateway.remote.url wss://your-app.fly.dev
solanaos config set gateway.remote.token <your-gateway-token>

Modules

God Mode in the UI

Toggle God Mode in the chat compose bar. When enabled, every message flows through the full pipeline. The response metadata includes:

• AutoTune: detected context, confidence score, computed params, reasoning
• Race results: per-model scores, durations, winner selection
• STM: which cleanup modules were applied
• Parseltongue: triggers found and transformations applied (when enabled)

Feedback Loop

Send chat.feedback via the WebSocket gateway with rating: 1 (thumbs up) or rating: -1 (thumbs down) along with contextType and model. The EMA feedback loop learns your preferences and adjusts parameters over time — the more you rate, the more the system adapts to your signal preferences.

Start Here

• Public repo: github.com/x402agent/SolanaOS
• Launch page: solanaos.net
• Live Hub: seeker.solanaos.net
• Soul library: souls.solanaos.net
• Hosted docs: solanaos.net
• Short landing page: docs/LANDING.md
• Release notes: docs/RELEASE-2026-03-v2.md
• Honcho memory integration: docs/honcho-integration.md
• Command cheat sheet: docs/command-cheatsheet.md
• NotebookLM pack: docs/notebooklm-pack.md
• Adding a messaging platform: docs/adding-a-messaging-platform.md
• Hardware guide: docs/HARDWARE.md
• Troubleshooting: docs/TROUBLESHOOTING.md
• Control UI (Lit + Vite): ui/ — browser-based control panel embedded in the Go binary
• SolanaOS Office (3D workspace): Claw3D-main/ — deployed at office.solanaos.net
• Control API: docs/control-api.md
• Fly deployment: docs/fly-deployment.md
• Agent Wallet API: services/agent-wallet/ (one-shot bootstrap, MCP server, Privy, E2B, local signers)
• ACP Registry Generator: acp_registry/generate.mjs (interactive agent.json builder)
• ACP Registry Example: acp_registry/agent.example.json
• SolanaOS identity prompt: SOUL.md
• Trading playbook: strategy.md

Live Surfaces

Setup Guides

Packages

# Public Hub CLI — search, install, publish skills
npx @solanaos/nanohub --help

# One-shot installer — binary + web + daemon
npx solanaos-computer@latest install --with-web

# Compatibility CLI aliases
npx solanaos-cli@latest --help
npx solanaos-cli@latest --help

Note: new/npm/ contains older draft versions — the canonical packages are in npm/. Use make npm-sync to check for version drift.

Authentication

The Hub supports four sign-in methods:

• GitHub OAuth — developer identity, linked to Convex user
• Phantom Connect — Solana wallet via Phantom SDK (Google, Apple, extension)
• Seeker Pairing — QR deep-link from the Android app, wallet-backed session
• Mobile Wallet Adapter — Android Chrome users connect via installed wallet app

All methods link to the same Convex user record. Phantom wallets auto-link to GitHub accounts when both are connected.

Published Skills

The SolanaOS skill is published to the Hub and can be installed by any AI agent:

npx @solanaos/nanohub install solanaos

Browse all 80+ skills at seeker.solanaos.net/skills.

Go Packages (pkg/)

SolanaOS ships as a single Go binary under 10 MB that contains 55 packages — the equivalent of a full-stack trading platform, multi-provider AI runtime, hardware OS, and payment layer all compiled to a single executable. No Docker, no Node.js, no Python. Just go build.

Intelligence Layer

Solana + Trading Layer

Memory + Storage Layer

Gateway + Channels Layer

Agent Infrastructure Layer

Hardware + Device Layer

AI Computer Use Layer

Payments + Auth Layer

Utilities

Why This Fits in One Go Binary

Shipping 55 packages — spanning blockchain, multi-provider AI, hardware I2C, payment protocols, browser automation, and real-time trading — as a single <10MB binary is only possible because Go:

• zero-dependency deployment: no runtime, no VM, no interpreter — one file, any platform
• native concurrency: goroutines handle parallel model races, OODA loops, WebSocket feeds, and hardware polling without thread pools
• static linking: all packages compile to a single ELF/Mach-O with dead-code elimination — unused code costs zero bytes
• cross-compilation: GOARCH=arm64 go build produces an Orin Nano binary from a Mac in seconds
• embed: //go:embed inlines the 750-line control UI HTML directly — no web server needed

The result: solanaos daemon boots in under 1 second, uses under 50 MB RAM at idle, and can trade, respond to Telegram, drive hardware LEDs, and run a multi-model LLM race simultaneously on a $35 Raspberry Pi.

services/agent-wallet/ | Agent Wallet API — AES-256-GCM encrypted vault, Solana + EVM wallets, Privy managed wallets, E2B sandbox deployment, MCP server for AI agent tooling |

Architecture

solanaos.net ─── Launch page (animated preview)
     │
seeker.solanaos.net (Netlify SSR + Convex)
     ├── /launch ──── Live terminal launch surface with product entry CTAs
     ├── /mobile ──── Public Seeker mobile dapp walkthrough
     ├── /dashboard ── Art feed, 8004 agent factory, Seeker pairing
     ├── /mining ───── BitAxe fleet dashboard (connects to MawdAxe API)
     ├── /strategy ─── Multi-venue parameter builder → strategy.md
     ├── /create ───── Skill creator wizard → SKILL.md
     ├── /skills ───── Browse 80+ agent skills
     ├── /chat ──────── Private wallet-to-wallet chat with Honcho memory
     ├── /ipfs ──────── Private IPFS hub — files, groups, deploy, mesh sync
     ├── /upload ───── Publish skills to registry
     ├── /import ───── Import from GitHub URL
     ├── /setup/* ──── Gateway, Telegram, Metaplex, Mining, Extension guides
     └── /auth/* ───── GitHub OAuth + Phantom Connect + MWA
          ↕ Convex (artful-frog-940)
               ├── Users, agents, pairing sessions, gallery
               ├── Skills, souls, search embeddings
               ├── Private chat threads + messages (Honcho-backed memory)
               └── GitHub OAuth + Phantom auth + wallet linking

souls.solanaos.net ─── SOUL.md library (same deployment, dual-mode)

Local Operator Machine
     ├── solanaos daemon (Go binary, <10MB)
     │    ├── OODA trading loop (spot + perps)
     │    ├── Telegram bot (60+ commands)
     │    │    ├── Image understanding (Grok Vision)
     │    │    ├── Auto-detect Solana contract addresses
     │    │    ├── Natural language token queries
     │    │    └── Remote control (Claude Code)
     │    ├── Gateway API (port 18790)
     │    │    ├── WebSocket protocol (config, status, sessions, agents, skills, cron, logs, chat)
     │    │    ├── LLM chat integration (Ollama, OpenRouter, Anthropic, xAI)
     │    │    ├── Keepalive (30s ping, 90s read deadline)
     │    │    └── Config read/write (~/.solanaos/solanaos.json)
     │    └── Honcho v3 + vault memory
     ├── SolanaOS Control UI (port 7777, `solanaos server`)
     │    ├── Lit + Vite SPA (//go:embed into binary)
     │    ├── Chat with LLM, real-time status, config editor
     │    ├── Debug panel, cron, sessions, skills, channels, logs
     │    ├── Proxies WebSocket to gateway on port 18790
     │    └── Binds 0.0.0.0 (Tailscale/LAN), --local for localhost
     ├── Web Backend (port 18800)
     │    ├── Control console UI
     │    ├── Setup code generation (QR)
     │    └── Proxies to gateway + control API
     ├── MawdAxe (port 8420)
     │    ├── BitAxe fleet OODA loop
     │    ├── REST API + SSE live stream
     │    └── TamaGOchi pet system
     ├── Agent Wallet API (port 8421)
     │    ├── AES-256-GCM encrypted vault
     │    ├── Solana + EVM wallet CRUD
     │    ├── Privy managed wallets (optional)
     │    ├── E2B sandbox deployment
     │    └── MCP server for AI agent tooling
     └── Chrome Extension
          └── Wallet, Seeker, Miner, Chat, Tools tabs

office.solanaos.net ─── SolanaOS Office (3D workspace)
     ├── Adapted from Claw3D, rebranded as SolanaOS HQ
     ├── 3D retro office for managing agents
     ├── Real-time Solana market terminal (Birdeye API)
     │    ├── /api/market — prices, trending, OHLCV, new_listings, meme_list
     │    ├── smart_money, token_txs, holder_distribution, wallet_networth
     │    └── 60-second in-memory cache, pop-out terminal
     ├── Agent chat + skills marketplace
     └── Solana purple (#9945FF) + green (#14F195) branding

Public routes include /, /launch, /mobile, /solanaos, and /pair. Authenticated routes still require GitHub, Phantom wallet, or Seeker pairing. The web backend runs locally and generates setup codes for clients to connect through the gateway.

Repo Map

This monorepo contains product code, client apps, deployment config, registry metadata, bundled skills, and a few local-only cache/build folders. If you are reading the repo for the first time, the main product code lives in cmd/, pkg/, apps/, nanohub/, docs/, scripts/, skills/, and src/.

Top-level directories and files

What to read first

Quick start:

1. Run bash start.sh — one command to build and start everything (see One-Shot Start).
2. Edit .env with your API keys — .env.example has the full template with descriptions.

Architecture docs (read in order):
3. DAEMON.md — full system picture: every subsystem, the OODA loop, all 55 packages, hardware layer.
4. SOUL.md — agent identity and trading philosophy; use as the system prompt for any LLM.
5. SKILL.md — complete agent skill file; give to any AI to install and operate SolanaOS in one shot.
6. STRATEGY.md — multi-venue trading playbook: Solana spot, Hyperliquid perps, Aster perps, confidence model.
7. TRADE.md — pump.fun trading agent skill: token tier classification and Jupiter execution workflow.
8. TOKEN.md — $CLAWD, the first AI-deployed token on pump.fun; tokenized agent + automated buybacks.
9. PUMP.md — pump.fun scanner report format, meta analysis pipeline, token data schema.
10. META.md — live board meta: cycle position, dominant themes, sniper candidates.

Code structure:
11. cmd/ — Go binary entrypoints: daemon, gateway API, control API, TUI.
12. pkg/ — 55 Go packages: runtime, gateway, Solana, trading, memory, hardware, x402, and integrations.
13. solana-claude/ — open-source TypeScript MCP agent framework (Claude Code architecture ported to Solana).
14. mcp-server/ — SolanaOS MCP server exposing all tools to Claude Desktop, Cursor, VS Code.
15. skills/ — 80+ agent skill bundles (SKILL.md format); acp_registry/ for on-chain agent registration.
16. nanohub/ — public web surfaces, Netlify deployment, mobile dapp page, and Seeker pairing funnel.
17. apps/android/, apps/macos/, and chrome-extension/ — user-facing client apps.

Public Links

Public Repo Notes

• Primary public repo: https://github.com/x402agent/SolanaOS
• Primary binary / CLI name: solanaos
• Secrets belong in .env or deployment environment variables only

IPFS Hub + Mainnet Deployment Pipeline

SolanaOS includes a Private IPFS Hub powered by Pinata that provides per-wallet file storage and a full mainnet deployment pipeline for registering agents as Solana NFTs.

Architecture

Upload (any surface)
  ├── Web Hub (/ipfs) ─── Convex auth + wallet connect
  ├── Go daemon ───────── pkg/pinata/ client
  ├── Seeker mobile ───── presigned URLs, camera capture
  ├── Android app ─────── localhost bridge (/api/ipfs/*)
  └── Mesh nodes ──────── Tailscale + BLE auto-sync

Pinata Private IPFS
  ├── Wallet-scoped groups (wallet:{addr})
  ├── GitHub-scoped groups (github:{user})
  ├── Device-scoped groups (device:{id})
  └── Keyvalue filtering (solana_wallet, github_user, device_id)

Convex (real-time tracking)
  ├── ipfsFiles — per-file tracking with identity + sync state
  ├── ipfsGroups — group-to-identity mapping
  └── ipfsAccessLog — temporary access link audit trail

Mainnet Deploy
  ├── Pin metadata to Private IPFS (8004-compatible format)
  ├── Pin NFT metadata to Private IPFS (Metaplex Core format)
  ├── Register on-chain via 8004 SDK → asset + ATOM reputation
  ├── Register on-chain via Metaplex mpl-core → NFT + identity PDA
  └── Mesh-sync deployment info to all Tailscale/BLE nodes

API Endpoints

Environment Variables

PINATA_API_KEY=          # Pinata API key
PINATA_API_SECRET=       # Pinata API secret
PINATA_JWT=              # Pinata JWT (preferred auth)
PINATA_GATEWAY=          # Your gateway domain (e.g. your-gateway.mypinata.cloud)
PINATA_MESH_SYNC=true    # Auto-sync files across Tailscale/BLE mesh

Go Usage

import "github.com/x402agent/SolanaOS/pkg/pinata"

hub := pinata.NewHub(pinata.Config{JWT: os.Getenv("PINATA_JWT"), Gateway: os.Getenv("PINATA_GATEWAY")})
mesh := pinata.NewMeshSync(hub)
deployer := pinata.NewDeployer(hub, mesh)

// Upload per-wallet
result, _ := hub.UploadForWallet(ctx, walletAddr, "data.json", reader, nil)

// Recall with temporary URL
url, _ := hub.RecallFile(ctx, result.CID, 300)

// Deploy to mainnet
deployResult, _ := deployer.Deploy(ctx, pinata.DeployConfig{
    WalletAddress: walletAddr,
    Mode:          pinata.DeployModeDual,
    Cluster:       "mainnet-beta",
    Name:          "My Agent",
    ATOMEnabled:   true,
    MeshSync:      true,
})

What Changed In v3

SolanaOS Control UI

A new browser-based control panel built with Lit + Vite, living in ui/. The UI is embedded into the Go binary via //go:embed and served on port 7777 by the solanaos server command (aliases: nanobot, control). Binds 0.0.0.0 by default for Tailscale/LAN access; use --local to restrict to localhost. Proxies WebSocket connections to the gateway on port 18790.

Features: LLM chat, real-time status, config editor, debug panel, cron management, sessions, skills, channels, and live log streaming.

solanaos onboard Command

Interactive setup wizard that configures your SolanaOS instance in one step:

1. Select an LLM provider (Ollama, OpenRouter, Anthropic, xAI, OpenAI) and enter credentials
2. Enter Solana API keys (SolanaTracker, Birdeye)
3. Configure Telegram bot (token + chat ID)

Writes everything to ~/.solanaos/solanaos.json. Replaces the manual .env editing workflow for new users.

SolanaOS Office (3D Workspace)

A 3D retro office environment adapted from Claw3D, deployed to office.solanaos.net. Rebranded as "SolanaOS HQ" with Solana purple (#9945FF) and green (#14F195). Features a real-time Solana market terminal powered by Birdeye API (/api/market with 60-second in-memory cache), agent chat, and a skills marketplace.

Gateway WebSocket Protocol

Full method implementation for all UI and Office methods: config.get/set/schema, status, health, system-presence, sessions.list, agents.list, agent.identity.get, skills.status, channels.status, cron.*, logs.tail, device.pair.*, exec.approvals.*, models.list, last-heartbeat, chat.send (with async LLM inference), chat.history, chat.abort. WebSocket keepalive: 30-second ping, 90-second read deadline.

LLM Chat via Gateway

The chat.send WebSocket method now routes to any configured LLM provider via the LLMProvider interface (Ollama, OpenRouter, Anthropic, xAI). Streams response back as chat event.

Branding Cleanup

All openclaw / OPENCLAW_* references replaced with solanaos / SOLANAOS_* in the UI (components, storage keys, env vars, CSS). Office rebranded from Claw3D.

CI/CD Updates

CI workflow now builds the UI before the Go binary. Cross-platform release workflow triggers on tags. Dependabot configured for gomod, npm, docker, and github-actions. TruffleHog scanning cleaned up.

Remote Control — Drive Your Mac From Telegram

SolanaOS now supports Claude Code Remote Control from Telegram. Start a claude remote-control server on your Mac and send natural language commands from your phone.

• /remote start — start a Claude remote-control server on your local machine
• /remote <instruction> — execute any command in natural language (e.g. /remote check disk usage, /remote open Safari and go to github.com, /remote find all Python files modified today)
• /remote status / /remote stop / /remote list — manage sessions
• Natural language triggers: "control my mac", "remote control", "use my computer"
• Auto-starts a session if you send a command without one running
• Full environment access: filesystem, tools, MCP servers, project config

Image Understanding — Grok Vision From Telegram

Send any image to the Telegram bot and get AI-powered analysis using xAI Grok Vision.

• Send a photo with no caption — auto-describes the image in detail
• Send a photo with a question — answers your question about the image (e.g. "what breed is this dog?")
• Send a photo with /vision — explicit vision mode
• /vision <url> [question] — analyze an image by URL
• Supports compressed photos and document-mode images (JPEG/PNG)
• Uses the xAI Responses API with input_image type

Auto-Detect Solana Contract Addresses

Paste any Solana mint address into the Telegram chat and get instant realtime token data from Solana Tracker.

• Paste 6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN → instantly returns price, market cap, liquidity, holders, risk score, 24h change, pool info
• Works for any base58 address (32-44 chars) — no slash command needed
• Powered by SolanaTracker Data API

Natural Language Token Queries

Ask about any token in plain English and get live data:

• "what is TRUMP" / "price of BONK" / "tell me about WIF" / "check POPCAT"
• "lookup SOL" / "research PENGU" / "analyze JUP" / "info on RENDER"
• 20+ query prefixes supported
• Exact symbol match → full token info with price, MC, liquidity, holders, risk, 24h change
• Multiple matches → shows top 5 results with key metrics
• Falls through to LLM for conversational follow-up

New Telegram Commands

Previous Changes (v2)

• SolanaTracker is now the default RPC provider, with Helius as fallback.
• SolanaTracker Datastream support is live for real-time token, wallet, holder, price, sniper, insider, and pool feeds.
• Honcho v3 memory is integrated for session summaries, peer context, and durable trading conclusions.
• Telegram now exposes the unified memory and perp surface directly, including /positions, /dream, /profile, and /card.
• Spot /buy and /sell now prefer SolanaTracker swap execution in Telegram when SOLANA_TRACKER_API_KEY is configured, with the older on-chain path kept as fallback.
• NanoHub ACP registry sync now resolves against the linked Solana wallet and GitHub-backed Hub user instead of creating split identities.
• Mining and extension setup now have first-class Hub pages at /mining, /setup/mining, and /setup/extension.
• OpenRouter xiaomi/mimo-v2-pro is wired in as the dedicated Mimo reasoning path.
• Grok image and video generation are available in Telegram, including natural-language routing for media requests.
• The web UI, extension, and docs were updated around the SolanaOS branding and current runtime surfaces.

What SolanaOS Includes

Quick Start

Recommended install

npx solanaos-computer@latest install --with-web
cd ~/solanaos
~/.solanaos/bin/solanaos onboard        # interactive wizard: LLM, Solana keys, Telegram
~/.solanaos/bin/solanaos version
~/.solanaos/bin/solanaos server          # Control UI on port 7777
~/.solanaos/bin/solanaos daemon

The onboard wizard walks you through selecting an LLM provider (Ollama, OpenRouter, Anthropic, xAI, OpenAI), entering Solana API keys (SolanaTracker, Birdeye), and configuring a Telegram bot. It writes everything to ~/.solanaos/solanaos.json so you can skip the manual .env setup.

Primary command names:

• solanaos is the primary binary and CLI name
• solanaos is the canonical CLI name

Compatibility npm packages still exist:

• solanaos-computer
• solanaos-cli
• solanaos-cli

Fast local dev path

git clone https://github.com/x402agent/SolanaOS.git
cd solanaos
cp .env.example .env              # fill in keys (see Minimum useful .env below)

# Build everything
make build                        # solanaos binary (UI embed + Go)
make build-agent-wallet           # agent-wallet binary (port 8421)
make build-gateway-api            # standalone gateway-api binary (port 18790)
make build-mcp                    # solanaos-mcp TypeScript server (port 3001)

# Start all services in one shot
bash start.sh                     # agent-wallet → daemon → mcp
bash start.sh --status            # check what's running
bash start.sh --stop              # stop everything

# Or start individually
./build/solanaos onboard          # interactive setup wizard
./build/solanaos server           # Control UI at http://localhost:7777
./build/solanaos daemon           # full autonomous agent
./build/agent-wallet              # encrypted wallet vault API

Alternatively, the one-shot installer handles all builds:

bash install.sh                   # build + install all binaries to ~/.solanaos/bin
bash install.sh --with-web        # also build the web console

Minimum useful .env

# SolanaTracker
SOLANA_TRACKER_API_KEY=your-key
SOLANA_TRACKER_RPC_URL=https://rpc-mainnet.solanatracker.io/?api_key=your-key
SOLANA_TRACKER_WSS_URL=wss://rpc-mainnet.solanatracker.io/?api_key=your-key
SOLANA_TRACKER_DATA_API_KEY=your-data-key

# LLM
OPENROUTER_API_KEY=sk-or-v1-...
OPENROUTER_MODEL=minimax/minimax-m2.7
OPENROUTER_OMNI_MODEL=xiaomi/mimo-v2-pro
OPENROUTER_MIMO_MODEL=xiaomi/mimo-v2-pro
LLM_PROVIDER=openrouter

# Telegram
TELEGRAM_BOT_TOKEN=...
TELEGRAM_ID=123456789

# Honcho
HONCHO_ENABLED=true
HONCHO_API_KEY=hch-v3-...
# Optional override if self-hosting; production default is already api.honcho.dev
HONCHO_BASE_URL=https://api.honcho.dev
HONCHO_WORKSPACE_ID=solanaos
HONCHO_AGENT_PEER_ID=solanaos-agent
HONCHO_SESSION_STRATEGY=per-chat
HONCHO_DIALECTIC_ENABLED=true

# Optional Helius fallback
HELIUS_API_KEY=...
HELIUS_RPC_URL=https://mainnet.helius-rpc.com/?api-key=...

Smoke test

./build/solanaos solana wallet
./build/solanaos status
./build/solanaos wallet-api          # one-shot agent wallet bootstrap
./build/solanaos gateway setup-code
./build/solanaos daemon

Solana Seeker pairing

For Android/Seeker onboarding, generate or reprint the shared gateway setup code:

~/.solanaos/bin/solanaos gateway start
~/.solanaos/bin/solanaos gateway setup-code
cat ~/.solanaos/connect/setup-code.txt

If Seeker should connect over LAN/manual host instead of Tailscale, start the bridge with ~/.solanaos/bin/solanaos gateway start --no-tailscale. If you moved the bridge off the default raw native port, use ~/.solanaos/bin/solanaos gateway start --port <port> and regenerate ~/.solanaos/connect/setup-code.txt.

Use the printed code or ~/.solanaos/connect/setup-code.txt in:

• Solana Seeker onboarding
• the Connect tab setup code field

The one-shot installer already writes the bundle to ~/.solanaos/connect/, and solanaos gateway start now prints the setup code path on launch.

Daily Operator Commands

Full grouped CLI, Telegram, and NanoHub reference:
docs/command-cheatsheet.md

./build/solanaos daemon
./build/solanaos server                    # Control UI on :7777 (aliases: nanobot, control)
./build/solanaos server --local            # restrict to localhost only
./build/solanaos ooda --sim --interval 30
./build/solanaos wallet-api
./build/solanaos pet
./build/solanaos solana health
./build/solanaos gateway start
./build/solanaos gateway setup-code
./build/solanaos menubar
node acp_registry/generate.mjs

Web console:

./build/solanaos-web --no-browser

Release Hygiene

Before pushing the repo publicly, verify:

• .env, private keys, and deployment tokens are not tracked
• local caches like .gocache, .gomodcache, .gopath, and .netlify are not tracked
• compiled binaries and APKs are attached to GitHub releases, not committed to the repo root
• npm packages pack cleanly with npm run pack:npm
• installer URLs and docs point at the public repo

Telegram Control

Set TELEGRAM_BOT_TOKEN and optionally TELEGRAM_ID to lock the bot to your account. The daemon auto-registers commands on startup.

For the full grouped command set, including Hyperliquid, Aster, memory, skills, and NanoHub workflows, see docs/command-cheatsheet.md.

Slash Commands

Core:
/status, /wallet, /pet, /trending, /scanner, /ooda, /sim, /live, /strategy, /version

Spot Trading:
/buy <symbol|mint> <amount_sol>, /sell <symbol|mint> <amount|pct%|all>, /swap, /price <token>, /research <mint>

Hyperliquid Perps:
/hl, /hl_positions, /hl_open <symbol> <side> [size] [leverage], /hl_close <symbol>, /hl_orders, /hl_fills, /hl_candles, /positions

Aster Perps:
/aster, /aster_positions, /aster_open <symbol> <side>, /aster_close <symbol>, /aster_trades, /aster_income

Memory (Honcho v3):
/memory, /recall <query>, /remember <fact>, /ask_memory <question>, /forget <query>, /dream, /profile, /card

Honcho Admin:
/honcho_status, /honcho_context, /honcho_sessions, /honcho_summaries, /honcho_search <query>, /honcho_messages, /honcho_conclusions

Skills & Media:
/skills, /skill <name>, /skill_find <query>, /mimo <prompt>, /web <query>, /xsearch <query>, /image <prompt>, /video <prompt>

Pump.fun Bots:
/bots — status of both bots
/sniper [start|stop|logs|config|set KEY VAL] — Mayhem Sniper bot control
/aibot [start|stop|logs|config|set KEY VAL] — AI Trading Bot control

Natural Language Trading

SolanaOS understands trading intent from plain English — no slash commands needed:

Spot buys (prefers SolanaTracker swap, falls back to the legacy on-chain route if needed):

buy 0.5 SOL worth of BONK
ape into WIF with 1 sol
snipe that new token with 0.1
yolo 2 sol into PENGU
grab some MEW

Spot sells:

sell all my BONK
dump half my WIF
paper hand MEW
exit my position in JUP

Hyperliquid perps:

long BTC on HL with 5x
short ETH 3x
close my BTC position
show my HL positions

Aster perps:

long SOL on aster
close btc on aster
show aster positions
what's my aster pnl

Filtered out (NOT executed):

should I buy BONK?           → treated as question, not trade
what do you think about WIF? → research, not execution
price of SOL                 → lookup, not trade
research this token          → analysis, not execution

The system distinguishes execution intent from research questions using verb detection and question filtering. Simulated mode (/sim) previews trades; live mode (/live) signs and lands the transaction on-chain. When SOLANA_TRACKER_API_KEY, SOLANA_TRACKER_RPC_URL, and SOLANA_TRACKER_WSS_URL are configured, Telegram spot flows use SolanaTracker for swap building, priority fees, and RPC transport.

Memory

SolanaOS has a three-layer memory architecture that combines local vault storage, cross-session Honcho v3 persistence, and a background Dreaming consolidation sweep. All three layers are connected: vault entries feed dreaming, dreaming promotes lessons back to the vault, and Honcho carries user and agent models across sessions.

┌─────────────────────────────────────────────────────────┐
│                   Memory Architecture                    │
│                                                         │
│  Telegram / Chat ──► RecursiveRecorder ──► ClawVault    │
│                             │                   │        │
│                             ▼                   ▼        │
│                       Honcho v3 API       vault/        │
│                       (cross-session)   ├── decisions/  │
│                             │           ├── lessons/    │
│                             │           ├── trades/     │
│                             │           ├── research/   │
│                             │           ├── tasks/      │
│                             ▼           └── inbox/      │
│                     User + Agent                │        │
│                     profiles                    │        │
│                     Conclusions           Dreaming       │
│                     Session recall        Sweep (3 AM)   │
│                                                 │        │
│                                    light → REM → deep   │
│                                                 │        │
│                                         vault/lessons/  │
└─────────────────────────────────────────────────────────┘

Layer 1 — ClawVault (local, pkg/memory/)

The vault is a file-backed markdown knowledge graph under ~/.solanaos/workspace/vault/. It uses a 3-tier epistemological hierarchy:

The RecursiveRecorder captures every conversation turn, auto-routes entries to the right category by keyword scoring, and maintains a graph index for link traversal and context profile building.

Key packages:

• pkg/memory/vault.go — ClawVault: Remember, Recall, Reflect, GetShortTermContext, ListEntries, BuildContextProfile
• pkg/memory/memory.go — MemoryEngine: 3-tier hierarchy with Supabase + vault dual-storage
• pkg/memory/recorder.go — RecursiveRecorder: per-turn capture with Convex sync
• pkg/memory/epistemological.go — EpistemologicalState builder

Layer 2 — Honcho v3 (pkg/honcho/)

Honcho provides cross-session memory with dialectic user modeling. Every Telegram turn is persisted to Honcho. The daemon enriches prompts from Honcho context before each LLM call.

What Honcho stores:

• Session summaries and message history
• Peer representations (user + agent models)
• Durable conclusions about trading preferences, risk tolerance, and behavior
• Semantic search over all past observations

Configuration:

HONCHO_ENABLED=true
HONCHO_API_KEY=hch-v3-pws0szjgkuzpsnv1r6qlnu94fvylctmthvosgieqf6eeopbjw7mqutk9t05zp5z4
HONCHO_BASE_URL=https://api.honcho.dev
HONCHO_WORKSPACE_ID=solanaos
HONCHO_AGENT_PEER_ID=solanaos-agent
HONCHO_SESSION_STRATEGY=per-chat
HONCHO_DIALECTIC_ENABLED=true

Key package: pkg/honcho/client.go — sessions, peers, conclusions, dialectic Q&A, session search, peer context.

Layer 3 — Dreaming (pkg/dreaming/)

Dreaming is the background memory consolidation system. It runs a nightly sweep (default 3 AM) that moves strong short-term vault signals into durable vault/lessons/ entries while keeping the process transparent and reviewable.

Phase model:

Deep ranking signals:

Machine state lives in .clawvault/dreams/ (candidates, phase signals, last-sweep checkpoint).
Human-readable diary is appended to vault/.dreams/DREAMS.md after each sweep — LLM-generated if an LLM is configured, template fallback otherwise.

Enable dreaming in config:

{
  "dreaming": {
    "enabled": true,
    "schedule": "0 3 * * *",
    "timezone": "America/Los_Angeles",
    "min_score": 0.55,
    "min_recall_count": 1,
    "diary_enabled": true,
    "channel": "telegram",
    "chat_id": "YOUR_TELEGRAM_ID"
  }
}

Telegram commands:

/dreaming                   — sweep status + last checkpoint
/dreaming now               — run a full sweep immediately
/dreaming diary             — show latest dream diary entry
/dreaming help              — full command reference

All Memory Commands (Telegram)

/memory                           — vault overview + tier counts
/recall <query>                   — semantic search across vault
/remember <fact>                  — store a new fact
/ask_memory <question>            — LLM-powered vault Q&A
/forget <query>                   — remove matching vault entries
/dream                            — vault reflect + promote inbox entries
/dreaming [status|now|diary|help] — dreaming sweep control
/profile                          — your Honcho user profile
/card                             — Honcho agent card

/honcho_status                    — Honcho connection status
/honcho_context                   — full Honcho user representation
/honcho_sessions                  — list Honcho sessions
/honcho_summaries                 — session summaries
/honcho_search <query>            — semantic search over Honcho memory
/honcho_messages                  — recent Honcho messages
/honcho_conclusions               — stored conclusions

Private Chat

SolanaOS Hub includes a real-time private chat system at /chat for wallet-to-wallet messaging between authenticated Hub users.

Features

• Dual auth — sign in with Solana wallet (Phantom, Seeker, MWA) or GitHub OAuth
• Identity bar — shows your GitHub @handle or wallet address with a live online indicator
• Real-time sync — Convex reactive queries push new messages instantly to all connected clients
• Honcho persistent memory — every message is ingested into Honcho v3 in the background for cross-session reasoning about user context
• Thread-based — conversations are organized as 1:1 threads between wallet addresses
• Animated UI — fade-in, slide-up, and bubble animations on messages, threads, and page transitions
• Deduplication — client-generated message IDs prevent duplicate sends on retry

How it works

User A (wallet or GitHub)           User B (wallet or GitHub)
        │                                    │
        ├──── sendMessage mutation ──────────►│
        │         │                          │
        │    ┌────▼────┐                     │
        │    │ Convex   │◄── useQuery ───────┤
        │    │ Database │    (real-time)      │
        │    └────┬────┘                     │
        │         │                          │
        │    ctx.scheduler.runAfter(0)       │
        │         │                          │
        │    ┌────▼────┐                     │
        │    │ Honcho   │                    │
        │    │ v3 API   │ ── background reasoning
        │    └─────────┘     (peers, sessions, conclusions)

Convex backend

Honcho integration

Every chat message is asynchronously ingested into Honcho v3 via a scheduled Convex action. This means:

• Each wallet becomes a Honcho peer (wallet:<address>)
• Each thread becomes a Honcho session (thread:<id>)
• Honcho's reasoning engine processes messages in the background to build durable conclusions about users
• These conclusions persist across sessions and can be queried for personalized context

Environment

# Set on Convex deployment (already configured)
HONCHO_API_KEY=hch-v3-...

Models

SolanaOS can talk to several model providers:

• OpenRouter (multi-model race, reasoning, embeddings)
• xAI / Grok
• Anthropic (direct API)
• Ollama (local, including 8bit/DeepSolana)
• Together AI
• llama.cpp (OpenAI-compatible local server)

The gateway implements a unified LLMProvider interface. When chat.send arrives over WebSocket, the gateway routes to the configured provider and streams the response back as chat events. The gateway prints LLM attached: <provider> / <model> on startup. Provider and model are configured via ~/.solanaos/solanaos.json (written by solanaos onboard) or environment variables.

OpenRouter Model Presets

Switch models at runtime from Telegram with /model <preset>:

Natural language switching also works from chat: "use claude", "switch to gemma", "use model 4".

Free model chain

OPENROUTER_FREE_MODELS (comma-separated) sets the fallback chain. Defaults to all free presets:

OPENROUTER_FREE_MODELS=nvidia/nemotron-3-super-120b-a12b:free,nousresearch/hermes-3-llama-3.1-405b:free,minimax/minimax-m2.5:free,z-ai/glm-5.1,google/gemma-4-26b-a4b-it:free

Reasoning (multi-turn)

Claude-via-OpenRouter, GLM-5, and Mimo all support extended reasoning with reasoning_details preserved across turns. SolanaOS passes reasoning_details back unmodified in session history so the model continues its chain of thought.

# Use Claude opus reasoning via OpenRouter (no Anthropic key required)
OPENROUTER_CLAUDE=anthropic/claude-opus-4.6-fast
# Then switch to it: /model claude

Semantic Memory Search (Embeddings)

When OPENROUTER_API_KEY is set, SolanaOS automatically enables vector semantic search for memory recall using the OpenRouter Embeddings API:

POST https://openrouter.ai/api/v1/embeddings
model: openai/text-embedding-3-small (default)

• Memory Recall / /memory_search / /recall use cosine similarity instead of keyword matching
• Results are cached in-memory to avoid re-embedding identical strings
• Override the embedding model: OPENROUTER_EMBEDDING_MODEL=openai/text-embedding-3-large
• On startup you'll see: [MEMORY] ✅ semantic search enabled (model: openai/text-embedding-3-small)

Local DeepSolana (Ollama)

Run the Solana-specialized reasoning model locally:

ollama pull 8bit/DeepSolana
OLLAMA_MODEL=8bit/DeepSolana
# or switch at runtime: /model ollama 8bit/DeepSolana

Model source: HuggingFace ordlibrary/DeepSeek-R1-Solana-Reasoning · Ollama 8bit/DeepSolana

All LLM env vars

# OpenRouter
OPENROUTER_API_KEY=sk-or-v1-...         # required for OpenRouter + semantic memory
OPENROUTER_MODEL=minimax/minimax-m2.7   # default active model
OPENROUTER_MODEL1=nvidia/nemotron-3-super-120b-a12b:free
OPENROUTER_MODEL2=nousresearch/hermes-3-llama-3.1-405b:free
OPENROUTER_MODEL3=minimax/minimax-m2.5:free
OPENROUTER_MODEL4=z-ai/glm-5.1
OPENROUTER_CLAUDE=anthropic/claude-opus-4.6-fast
OPENROUTER_GEMMA=google/gemma-4-26b-a4b-it:free
OPENROUTER_MIMO_MODEL=xiaomi/mimo-v2-pro
OPENROUTER_OMNI_MODEL=xiaomi/mimo-v2-pro
OPENROUTER_FREE_MODELS=                 # comma-separated fallback chain (auto-built from presets if empty)
OPENROUTER_EMBEDDING_MODEL=openai/text-embedding-3-small

# Anthropic (direct)
ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_MODEL=claude-sonnet-4-6

# xAI
XAI_API_KEY=...
XAI_IMAGE_MODEL=grok-imagine-image      # /image
XAI_VIDEO_MODEL=grok-imagine-video      # /video

# Ollama (local)
OLLAMA_MODEL=8bit/DeepSolana            # or minimax-m2.7:cloud
OLLAMA_BASE_URL=http://127.0.0.1:11434
OLLAMA_FALLBACK_ENABLED=true

# Together AI
TOGETHER_API_KEY=...
TOGETHER_MODEL=zai-org/GLM-5

# llama.cpp server (OpenAI-compatible)
LLAMA_CPP_URL=http://127.0.0.1:8079
LLAMA_CPP_MODEL=gemma4
LLAMA_CPP_ENABLED=false

Trading Stack

Solana

• SolanaTracker RPC and WSS are the default
• SolanaTracker Datastream powers real-time websocket feeds
• SolanaTracker powers Telegram swap build-and-send flows when configured
• The legacy Jupiter/on-chain execution path remains available as fallback
• Helius remains the fallback provider for DAS and fallback RPC paths

Perps

• Hyperliquid support for balance, positions, orders, fills, leverage, candles, and websocket-driven triggers
• Aster support for account, positions, orders, income, and natural-language Telegram routing

Startup pump launch

Optional one-time launch on daemon boot:

PUMP_LAUNCH_ENABLED=true
PUMP_LAUNCH_CONFIRM=launch
PUMP_LAUNCH_MODE=once_only
PUMP_LAUNCH_NAME=SolanaOS
PUMP_LAUNCH_SYMBOL=NANO

The daemon persists launch state and refuses to relaunch in once_only mode unless you intentionally reset it.

Pump.fun Token Scanner

Automated pipeline that scans pump.fun for the top 100 trending tokens, classifies them by trading tiers, and sends Telegram alerts.

Data Sources:

Scanner Scripts (committed to scripts/):

Run manually:

bash scripts/pump-scanner.sh

Pipeline flow:

1. GeckoTerminal pumpswap/pools x 5 pages = 100 graduated tokens (sorted by 24h tx count, no auth)
2. Solana Tracker /tokens/trending → curvePercentage, pool.graduated, pool.market
3. Solana Tracker /tokens/{mint} per-token enrichment for top 30
4. pump-bonding.mjs (Helius on-chain) for tokens still missing bonding% — batches 4 concurrent RPC calls, 400ms between batches
5. Writes pump.md → sends Telegram digest → commits and pushes

Token classification (from trade.md):

Scheduling (three tracks):

:00  Remote trigger    → GeckoTerminal + Solana Tracker → pump.md → Telegram → git push
:30  Local skill/CLI   → Chrome computer use OR pump-scanner.sh → pump.md → Telegram
:00  Remote trigger again...

• Remote Trigger (hourly): Claude Code dispatch trig_01KUywkkCQVJeqvzDbrK82Vj — runs in cloud, no browser
• Local Computer Use: pumpfun-token-scanner skill — Chrome browser automation on local Mac
• CLI: bash scripts/pump-scanner.sh — standalone, cron-friendly

Note on pump-bonding.mjs: The SDK files from pump-fun-sdk-main 4/src/ (analytics.ts, bondingCurve.ts, fees.ts, onlineSdk.ts) are bundled compiled in @nirholas/pump-sdk under scripts/node_modules. Same exports: OnlinePumpSdk, getGraduationProgress, calculateBuyPriceImpact, getTokenPrice, computeFeesBps.

On-Chain Agent Registration (8004 + Metaplex)

The pump.fun scanner agent can be registered on-chain via the 8004 Trustless Agent Registry and Metaplex Core NFTs. This gives the scanner a verifiable on-chain identity with ATOM reputation scoring.

Register the scanner agent:

node scripts/register-scanner-agent.mjs

What happens:

1. Builds scanner-specific metadata (name, description, services, skills, domains)
2. Pins metadata to IPFS via Pinata
3. Registers on the 8004 agent registry with ATOM enabled
4. Sets on-chain metadata (scanner_type, pipeline, endpoints)
5. Syncs to the nanohub Convex backend
6. Saves state to ~/.solanaos/registry/scanner-agent.json

Required env vars:

SOLANA_PRIVATE_KEY=<JSON array of secret key bytes>
HELIUS_RPC_URL=<Solana RPC>
PINATA_JWT=<Pinata JWT for IPFS>

8004 features used:

• registerAgent() — creates on-chain agent identity as Core NFT
• setAgentWallet() — binds operational wallet
• setMetadata() — stores scanner config on-chain
• giveFeedback() / getSummary() — ATOM reputation engine
• Trust tiers: Unrated → Bronze → Silver → Gold → Platinum

Nanohub integration:

• /st/agent-registry?asset=<address> — edge function returning agent reputation from 8004 indexer
• AgentStatus component in the Pump Scanner tab shows live trust tier + ATOM score
• solanaosAgentReputation Convex table stores periodic reputation snapshots

Agent Registration (Metaplex 014)

Register your agent on-chain as a Metaplex NFT with a single command:

solanaos solana register

What happens:

1. Loads your agent wallet (auto-generated on first boot)
2. Checks for existing registration (won't double-register)
3. Auto-detects skills from your .env (OODA, SolanaTracker, Aster, etc.)
4. Registers on Solana devnet as a Metaplex 014 NFT (gasless, auto-airdrop)
5. Saves the registration result locally
6. Prints the Solana Explorer link

⛓️  SolanaOS Agent Registration

  Agent:   AAqkn72V...
  Skills:  [ooda-trading, solana-tracker-data, aster-perps]
  Network: devnet (gasless)

  ✅ Agent registered on-chain!

  Mint:     5Kz8...
  Tx:       3Qfx...
  Explorer: https://explorer.solana.com/address/5Kz8...?cluster=devnet

Three ways to create an agent

What gets saved

Every agent is stored in Convex with:

• userId — linked to your GitHub account
• ownerWalletAddress — from Phantom Connect or Seeker pairing
• metaplexAssetAddress — on-chain NFT mint address
• metaplexIdentityPda — discoverable PDA for the agent
• metaplexRegistered — boolean flag
• registryMode — 8004, metaplex, or dual
• Services array — web, A2A, MCP endpoints (ERC-8004 format)

Verify on-chain

solanaos solana registry    # show registered agents

Or check the Solana Explorer directly with the mint address.

macOS Menu Bar App

A lightweight native menu bar companion that connects to your local SolanaOS daemon and all Hub surfaces.

Build & Install

cd apps/macos
bash build-menubar.sh

This compiles the standalone Swift file (no Xcode project needed) and creates SolanaOS Menu Bar.app.

Run

open "apps/macos/SolanaOS Menu Bar.app"

Install to Applications

cp -r "apps/macos/SolanaOS Menu Bar.app" /Applications/

Auto-start on login

osascript -e 'tell application "System Events" to make login item at end with properties {path:"/Applications/SolanaOS Menu Bar.app", hidden:true}'

What it shows

Status line: daemon status · ooda mode · watchlist count · honcho on/off

Menu items

Local: Control panel (:7777), Wallet, Chat

Hub: Dashboard, Mining Fleet, Strategy Builder, Skills Registry, Agent Directory, Create Skill, Souls Library

Setup Guides: Gateway, Telegram, Metaplex, BitAxe Mining, Chrome Extension

Seeker: Reveal/copy setup code, reveal connect bundle

System: GitHub, Terminal, Quit

Control Surfaces

SolanaOS Office (3D Workspace)

A 3D retro office environment for managing agents and monitoring Solana markets. Adapted from Claw3D, lives in Claw3D-main/, deployed to office.solanaos.net.

Features

• 3D office environment — retro workspace for agent management, rebranded as "SolanaOS HQ"
• Real-time Solana market terminal — powered by Birdeye API with a pop-out terminal in the 3D scene
• Agent chat — interact with agents directly from the office
• Skills marketplace — browse and manage agent skills
• Solana branding — purple (#9945FF) and green (#14F195) color scheme

Birdeye Market API

The Office exposes an API route at /api/market supporting:

All responses are cached in memory for 60 seconds.

Gateway WebSocket Protocol

The gateway on port 18790 exposes a full WebSocket protocol used by both the Control UI and the Office. The gateway sends ping frames every 30 seconds with a 90-second read deadline that resets on every message, preventing timeout disconnects.

Supported Methods

LLM Chat Integration

The chat.send method routes to any configured LLM provider via the LLMProvider interface. Supported providers: Ollama, OpenRouter, Anthropic, xAI. The gateway prints LLM attached: <provider> / <model> on startup. Responses stream back to the client as chat WebSocket events.

Hardware

The runtime can run software-only or attach to Arduino Modulino hardware over I2C.

Supported sensors and controls:

• Pixels
• Buzzer
• Buttons
• Knob
• IMU
• Thermo
• ToF distance

Supported targets:

• NVIDIA Orin Nano
• Raspberry Pi
• RISC-V Linux boards
• x86 Linux
• macOS and Windows in stub mode

See docs/HARDWARE.md.

x402

SolanaOS includes x402 payment support for crypto-gated APIs.

Main pieces:

• facilitator proxy
• SVM signer
• configurable paywall middleware
• multi-chain config surface

Minimal enablement:

X402_PAYWALL_ENABLED=true
./build/solanaos daemon

Agent Wallet API

SolanaOS includes a full agent wallet service that manages encrypted Solana + EVM keypairs, exposes a REST API, and optionally integrates with Privy managed wallets and E2B sandbox deployment.

Local Signing Keys (dev + trade)

On every startup the agent wallet bootstraps two dedicated AES-256-GCM encrypted Solana keypairs:

Key loading priority: LOCAL_SIGNER_{MODE}_KEY env var → disk .enc file → fresh generated keypair. Each file is an AES-256-GCM envelope:

{ "data": "<hex ciphertext>", "nonce": "<hex nonce>" }

The master AES key is derived from VAULT_PASSPHRASE via SHA-256. The trade key can have its own TRADE_SIGNER_PASSPHRASE. Private keys are never returned by the API.

Local signer endpoints:

GET  /v1/local-signers              → list dev + trade pubkeys
GET  /v1/local-signers/{mode}       → get pubkey (mode: dev|trade)
POST /v1/local-signers/{mode}/sign  → sign arbitrary message
POST /v1/local-signers/{mode}/sign-tx → build + sign + broadcast SOL transfer

Sandbox Modes

The /v1/deploy endpoint works in two modes — no configuration change needed:

Local sandboxes are useful for CI, offline development, and testing agent interactions without cloud dependencies.

One-Shot Bootstrap

solanaos wallet-api

This single command:

1. Initializes the AES-256-GCM encrypted vault at ~/.solanaos/vault/
2. Generates (or loads) dev and trade signing keys at ~/.solanaos/signers/
3. Creates a default Solana vault wallet if no wallets exist
4. Connects to Solana RPC and any configured EVM chains
5. Starts the wallet API server on port 8421
6. Handles graceful shutdown on Ctrl+C

Flags

solanaos wallet-api --port 8421 --chain solana --label primary
solanaos wallet-api --chain evm --label base-wallet
solanaos wallet-api --skip-setup  # just start the API, no auto-creation

API Endpoints

MCP Servers

SolanaOS ships two MCP servers for AI agent integration (Claude Desktop, Cursor, VS Code, Zed):

1. solanaos-mcp — Full SolanaOS MCP server (mcp-server/)

Exposes the full SolanaOS tool registry, agent fleet, memory, and skills to any MCP client.

make build-mcp        # build once
make start-mcp        # start HTTP server on port 3001

Claude Desktop config (~/.claude.json or Claude Desktop settings):

{
  "mcpServers": {
    "solanaos": {
      "command": "node",
      "args": ["<path-to-repo>/mcp-server/dist/index.js"],
      "env": {
        "SOLANAOS_GATEWAY_URL": "http://localhost:18790",
        "SOLANAOS_GATEWAY_API_KEY": ""
      }
    }
  }
}

Tools: solana.price, solana.trending, solana.token_info, solana.wallet_pnl, solana.search, agent.spawn, agent.list, agent.stop, memory.recall, memory.write, task.create, task.list, skill.list, skill.run, gateway.health

Resources: solanaos://soul, solanaos://skills, solanaos://tools, solanaos://source/{path}

2. Agent Wallet MCP (services/agent-wallet/mcp/)

Exposes wallet vault operations directly to AI agents.

{
  "mcpServers": {
    "agent-wallet": {
      "command": "npx",
      "args": ["tsx", "services/agent-wallet/mcp/index.ts"],
      "env": {
        "WALLET_API_URL": "http://localhost:8421/v1",
        "WALLET_API_KEY": ""
      }
    }
  }
}

Tools: create_wallet, list_wallets, get_balance, transfer, transfer_token, sign_message, pause_wallet, unpause_wallet, deploy_sandbox, teardown_sandbox, privy_create_wallet, privy_sign, privy_send

Docker

docker build -f services/agent-wallet/Dockerfile -t agent-wallet .
docker run --env-file .env -p 8421:8420 agent-wallet

Environment Variables

WALLET_API_PORT=8421          # HTTP port
WALLET_API_KEY=               # Bearer token for auth (optional)
VAULT_PASSPHRASE=             # Master encryption key
SOLANA_RPC_URL=               # Solana RPC endpoint
EVM_CHAINS=8453:https://...   # chainID:rpcURL pairs
BASE_RPC_URL=                 # Base chain RPC (shortcut)
ETH_RPC_URL=                  # Ethereum RPC (shortcut)
E2B_API_KEY=                  # E2B sandbox deployment
PRIVY_APP_ID=                 # Privy managed wallets
PRIVY_APP_SECRET=             # Privy app secret

Supported Chains

Cloudflare Workers

SolanaOS ships two Cloudflare Worker deployments for edge-side execution:

Agent Wallet Worker (workers/agent-wallet/)

Edge version of the agent wallet vault — AES-256-GCM encrypted keys stored in Cloudflare KV, same REST API as the Go service (/v1/wallets, /v1/local-signers, etc.). Useful when you need global low-latency wallet access without running a Go process.

cd workers/agent-wallet
wrangler secret put VAULT_PASSPHRASE
wrangler secret put WALLET_API_KEY
wrangler secret put SOLANA_RPC_URL
wrangler deploy

Worker name: solanaos-agent-wallet — deployed to solanaos-agent-wallet.<account>.workers.dev

Pump.fun MCP Worker (pumpfun-mcp-worker/)

Cloudflare Worker that runs a pump.fun token scanner on a 15-minute cron trigger and exposes results via MCP. Stores scan results in KV, surfaces them as MCP tools for AI agents.

cd pumpfun-mcp-worker
wrangler deploy

Worker name: pumpfun-mcp-server — cron: */15 * * * *

Pump.fun Bots (bots/)

Two pump.fun TypeScript bots are bundled in bots/ and fully integrated into the SolanaOS daemon runtime via pkg/pumpfun/. The daemon manages them as supervised subprocesses — start, stop, log streaming, and .env config — all from Telegram without touching a terminal.

Bot Architecture

Both bots run as ts-node child processes under the Go daemon. The pkg/pumpfun manager captures their stdout/stderr into a 40-line ring buffer per bot, sources each bot's .env, and inherits SOLANA_TRACKER_RPC_URL and WSS from the daemon config automatically.

SolanaOS Daemon (Go)
  └── pkg/pumpfun.Manager
       ├── KindSniper  → ts-node src/index.ts  (bots/pumpfun-mayhem-sniper-main/)
       │    └── Geyser WS → pump.fun program → InitializeMint2 → buy/sell
       └── KindAIBot   → ts-node src/index.ts  (bots/pumpfun-mayhem-ai-trading-bot-main/)
            └── Express :3001 → /api/health, /api/trading

Bot Telegram Commands

/bots                    — status of both bots
/sniper start            — launch the Mayhem Sniper
/sniper stop             — kill it
/sniper logs [N]         — last N lines of stdout/stderr (default 20)
/sniper config           — show .env (private keys redacted)
/sniper set KEY VALUE    — update a .env key (restart bot to apply)

/aibot start             — launch the AI Trading Bot
/aibot stop              — kill it
/aibot logs [N]          — last N lines
/aibot config            — show .env
/aibot set KEY VALUE     — update a .env key

Sniper Bot Config (.env)

GEYSER_RPC=wss://...                # Geyser WebSocket endpoint
PRIVATE_KEY=...                     # Wallet private key (base58)
RPC_ENDPOINT=https://...            # Solana HTTP RPC
RPC_WEBSOCKET_ENDPOINT=wss://...    # Solana WebSocket RPC
BUY_AMOUNT=0.1                      # SOL per trade
SLIPPAGE=10                         # Slippage %
TAKE_PROFIT=20                      # % gain to auto-sell
STOP_LOSS=15                        # % loss to auto-sell
TIME_OUT=60                         # Max hold seconds before forced exit
CHECK_DEV_BUY=true                  # Require dev to invest ≥ MIN_DEV_BUY_AMOUNT
MIN_DEV_BUY_AMOUNT=0.5              # Minimum dev buy in SOL
MAYHEM_MODE_ONLY=false              # Only snipe tokens with Mayhem Mode flag

How the sniper works:

1. Subscribes to the pump.fun program (6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P) via Geyser WebSocket
2. Detects InitializeMint2 instructions — new token creation events
3. Optionally checks for the Mayhem Mode flag via isMayhemMode()
4. Validates the developer's initial buy against MIN_DEV_BUY_AMOUNT
5. Executes buyToken() via @cryptoscan/pumpfun-sdk with configured slippage
6. Polls the bonding curve price every 500ms until TP, SL, or timeout triggers
7. Executes sellToken() on exit

AI Bot Config (.env)

PORT=3001                           # HTTP server port
AI_ENABLED=true                     # Activate AI trading loop on startup
SOLANA_PRIVATE_KEY=...              # Wallet private key (base58)
SOLANA_RPC_URL=https://...          # Solana HTTP RPC

API endpoints (when running):

Running standalone (without daemon integration)

# Sniper
cd bots/pumpfun-mayhem-sniper-main
cp .env.example .env    # fill in GEYSER_RPC, PRIVATE_KEY, etc.
npm install && npm start

# AI Trading Bot
cd bots/pumpfun-mayhem-ai-trading-bot-main
cp .env.example .env    # fill in SOLANA_PRIVATE_KEY, etc.
npm install && npm run dev

Token Scanner Output (pump.md)

The pump.fun scanner pipeline (see Pump.fun Token Scanner below) writes its output to pump.md. It scans ~100 tokens per run, filters spam, classifies by trading tier, and sends a Telegram digest. Example output format:

Date: 2026-03-26  |  Scanned: 113  |  Blocked (spam): 14  |  Clean: 99

| # | Name            | Ticker   | Mint         | MCap | Change  | Age    |
|---|-----------------|----------|--------------|------|---------|--------|
| 1 | Pippin          | pippin   | Dfh5Dz...   | N/A  | +3.79%  | N/A    |
| 2 | Penguin Empress | kolwaii  | 4BZSEBVk...  | N/A  | +33.02% | N/A    |
| 5 | シコク           | Shikoku  | 4xU6BSLz...  | N/A  | +204%   | 3m ago |
...

The sniper bot targets fresh tokens from this feed. The AI bot uses it for pattern recognition and market sentiment analysis.

ACP Registry Generator

The acp_registry/ directory contains an interactive CLI for generating agent.json files for the 8004 Agent Commerce Protocol registry.

Generate

node acp_registry/generate.mjs

The wizard walks through:

• Agent identity (name, display name, description, icon)
• Distribution config (command type, args)
• Services (MCP, A2A, HTTP, WebSocket, gRPC)
• Registry settings (program IDs, metadata storage, NFT standard, clusters)
• Feature flags (ATOM reputation, SEAL v1, x402, ProofPass, heartbeat sync)
• Capabilities (skills from 7 categories, domains, x402 support)

Previews the JSON and writes agent.json on confirmation.

Validate

node acp_registry/generate.mjs validate
node acp_registry/generate.mjs validate path/to/agent.json

Checks required fields: schema_version, name, display_name, description, distribution, registry, services, capabilities.

Example

See acp_registry/agent.example.json for a complete reference configuration (the SolanaOS agent itself).

Skill Categories

The generator includes the full 8004 ACP skill catalogue:

Docs Map

Use the short README for orientation and these docs for depth:

• docs/LANDING.md: short product/landing copy
• docs/RELEASE-2026-03-v2.md: current release summary
• docs/command-cheatsheet.md: grouped CLI, Telegram, and NanoHub commands
• docs/notebooklm-pack.md: NotebookLM source pack generation and prompt
• docs/HARDWARE.md: hardware deploy and wiring
• docs/TROUBLESHOOTING.md: runtime issues and recovery
• docs/control-api.md: SolanaOS Control API
• docs/cli-guide.md: broader CLI usage
• docs/deployment.md: deployment patterns

Hosted:

• Docs: https://solanaos.net
• Hub: https://seeker.solanaos.net

Build And Deploy

Local build

make build    # builds UI (cd ui && npm ci && npx vite build) then Go binary with //go:embed
make test

make build now runs the UI build step first (Vite production build in ui/), then compiles the Go binary which embeds the UI dist output. CI workflows also build the UI before the Go binary. A cross-platform release workflow triggers on tags. Dependabot is configured for gomod, npm, docker, and github-actions.

Common targets

make orin
make rpi
make riscv
make macos
make docker
make cross

Docker

docker build -t solanaos .
docker run --env-file .env \
  -v "$HOME/.config/solana/id.json:/root/.config/solana/id.json:ro" \
  solanaos

Fly.io

Relevant files:

• Dockerfile.fly
• scripts/fly-start.sh
• fly.toml

The Fly path is intended for persistent daemon state plus the web console. Start with research, memory, and Telegram before enabling live keys.

Repo Layout

solanaos/
├── main.go                    # root Go binary (solanaos daemon)
├── start.sh                   # unified service start/stop/status script
├── install.sh                 # one-shot installer (build + workspace + keys)
├── Makefile                   # all build targets
│
├── cmd/
│   ├── mawdbot/               # primary daemon CLI entrypoint
│   ├── gateway-api/           # standalone gateway binary (port 18790)
│   ├── mawdbot-tui/           # TUI launcher
│   └── solanaos-control-api/  # control API binary (port 18789)
│
├── pkg/                       # 55 Go library packages (see pkg/ table above)
│   ├── daemon/                # 8,400-line orchestrator
│   ├── agent/                 # OODA loop + tool-calling
│   ├── llm/                   # multi-provider LLM + God Mode pipeline
│   ├── solana/                # SolanaTracker RPC, Birdeye v3, Jupiter
│   ├── gateway/               # TCP + WebSocket gateway
│   ├── nanobot/               # Control UI server (port 7777)
│   ├── hardware/              # Modulino I2C drivers
│   ├── x402/                  # x402 payment protocol
│   └── ...                    # 45 more — see pkg/ section
│
├── services/
│   └── agent-wallet/          # AES-256 encrypted wallet vault + REST API (port 8421)
│       ├── cmd/               # standalone agent-wallet binary
│       └── mcp/               # MCP server for AI agent tooling
│
├── mcp-server/                # solanaos-mcp — local MCP server (Claude Desktop / Cursor)
│
├── workers/                   # Cloudflare Workers monorepo
│   ├── agents/                # agent task dispatch worker
│   ├── gateway/               # gateway proxy worker
│   ├── routing/               # request routing worker
│   ├── sessions/              # session management worker
│   ├── commands/              # command handler worker
│   ├── cron/                  # scheduled job worker
│   ├── auto-reply/            # auto-reply worker
│   ├── infra/                 # infra shared utilities
│   └── shared/                # shared types + helpers
│
├── pumpfun-mcp-worker/        # pump.fun MCP server (Cloudflare Worker + Cron)
│
├── npm/                       # canonical npm packages (published to npmjs.com)
│   ├── solanaos/              # solanaos-computer (v1.1.1) — one-shot installer
│   ├── solanaos-installer/    # solanaos-cli (v2.1.1) — CLI alias
│   └── mawdbot-installer/     # solanaos-cli (v2.1.1) — legacy compat alias
│
├── new/npm/                   # ⚠️  older package drafts — npm/ is canonical
│
├── acp_registry/              # ACP 8004 agent registry tooling
│   ├── agent.example.json     # reference ACP config
│   └── generate.mjs           # interactive agent.json builder
│
├── skills/                    # bundled SKILL.md files for agent context
├── bots/                      # standalone trading bots (pump.fun sniper + AI)
├── mawdbot-bitaxe/            # MawdAxe BitAxe ASIC miner agent (own Makefile)
├── g0dm0d3-main/              # God Mode source (Rust/Python ML components)
├── page-agent-main/           # web UI automation agent
├── extensions/bluebubbles/    # iMessage bridge via BlueBubbles
├── WatchApp/                  # Apple Watch app (Swift / WatchOS)
│
├── ui/                        # Lit + Vite Control UI (//go:embed into binary)
├── web/                       # web backend + frontend (optional solanaos-web)
├── src/                       # TypeScript shared sources (workers / web)
│
├── db/                        # database schema (index.ts, schema.ts)
├── internal/                  # Go internal packages (hal)
├── scripts/                   # release, deploy, seeker, pump scripts
├── deploy/                    # Fly.io deployment package
├── docs/                      # markdown documentation
└── build/                     # compiled binaries (gitignored)

Service port map:

Notes:

• solanaos is the canonical name throughout
• npm/ is the canonical npm workspace — new/npm/ contains older drafts and is not published
• Workers in workers/ and pumpfun-mcp-worker/ are deployed separately via Wrangler/Cloudflare
• bots/ — two standalone pump.fun bots (AI trading + sniper); independent Node.js projects
• WatchApp/ — Apple Watch app (Swift/WatchOS) for wallet balance glances; built with Xcode
• page-agent-main/ — web UI automation agent (AI-powered browser control)
• extensions/bluebubbles/ — iMessage bridge integration via BlueBubbles server
• workers/ and pumpfun-mcp-worker/ — deployed separately to Cloudflare via wrangler deploy
• new/npm/ — stale draft packages; canonical npm packages live in npm/

Configuration Notes

JSON config (~/.solanaos/solanaos.json)

The gateway and Control UI read/write a structured JSON config file at ~/.solanaos/solanaos.json. This file is created by solanaos onboard or by editing the Config tab in the Control UI. It contains sections for:

• LLM — provider, model, API key (Ollama, OpenRouter, Anthropic, xAI, OpenAI)
• Solana — SolanaTracker API key, Birdeye API key
• Telegram — bot token, chat ID
• Gateway — port, bind address

The config schema is served via the config.schema WebSocket method so the UI can render a dynamic editor.

Environment loading order

• current working directory .env
• executable directory .env
• parent of executable directory .env
• ~/.solanaos/.env

Useful overrides:

• SOLANAOS_HOME
• SOLANAOS_CONFIG
• SOLANAOS_ENV_FILE
• SOLANAOS_SOUL_PATH
• SOLANAOS_SKILLS_DIR

Security

• no API keys should be committed
• .env stays local
• generated wallets are stored under the runtime home with restrictive permissions
• only public addresses should appear in logs

See SECURITY.md.

Contributing

git checkout -b feature/my-change
make build
make test
git commit -m "Add my change"

See CONTRIBUTING.md.

License

MIT. See LICENSE.

Vision

The next billion blockchain transactions will be executed by AI agents, not humans clicking buttons.

SolanaOS is building toward a world where any AI agent can launch, trade, and manage tokens through natural language — where fee revenue flows autonomously to agent wallets, where agent fleets coordinate across protocols through shared memory and skills, and where epistemological reasoning becomes the competitive moat that separates agents that adapt from agents that don't.

See docs/vision.md for the full thesis.