@synapseia-network/node

The Synapseia Network compute node — contribute CPU/GPU cycles to autonomous AI agents and earn SYN tokens on Solana.

🟡 Status: Closed Beta — Devnet only

⚠️ Beta capacity is capped. New node registrations may be rejected with a [BETA_LIMIT_REACHED] message when the network is full. If that happens, your node exits cleanly — try again later, or wait for mainnet launch.

What is Synapseia?

Synapseia is a peer-to-peer compute layer for autonomous AI agents. Operators run nodes that contribute training, inference, and research workloads to a decentralized coordinator. In exchange, nodes earn SYN — an SPL token on Solana.

This package is the operator-side runtime: a CLI you install globally and run as a long-lived process.

Requirements

• Node.js ≥ 20 (node --version to check).
• ~2 GB RAM free, stable internet.
• Ollama (only if you plan to run inference workloads) — install from ollama.com.
• Solana wallet with devnet SOL — the node generates one for you on first run; you fund it from a faucet.

Quick start (TL;DR)

npm i -g @synapseia-network/node
synapseia start            # creates a wallet, prints the address, then waits
# In another terminal — fund the wallet on devnet:
solana airdrop 1 <YOUR_ADDRESS> --url devnet
# Re-run:
synapseia start

The node talks to the official Synapseia coordinator automatically — no URL flags needed. For the full walkthrough, keep reading.

Step-by-step beta onboarding

Step 1 — Install

npm i -g @synapseia-network/node
synapseia --version

You can use synapseia or its short alias syn interchangeably.

Step 2 — Initialize your node (creates a wallet)

The first run prompts you for a node name and a vault passphrase (min 12 characters). The passphrase encrypts your wallet at rest using the hardened EncryptedKeystore (scrypt + AES-256-GCM) — there is no recovery if you forget it, but the on-screen recovery phrase (BIP39 mnemonic) lets you restore the wallet on another machine.

synapseia start

Output looks like:

[Keystore] new wallet encrypted at ~/.synapseia/wallet.keystore.json (mode 0600)

🔐  IMPORTANT — write down this recovery phrase NOW:
     <12 BIP39 words>
     Wallet address: 3xK...nQ8
     Keystore file:  ~/.synapseia/wallet.keystore.json
     The mnemonic is the ONLY way to recover this wallet if the keystore
     file is lost or corrupted. Store it offline (paper or hardware) and
     never share it.

Copy the wallet address AND the recovery phrase now. The address gets pasted into the faucets below; the recovery phrase goes on paper / hardware backup.

Non-interactive boot (Docker, systemd, fly-machines): mount the passphrase at a mode-0600 file owned by the current uid and set SYNAPSEIA_KEYSTORE_PASSPHRASE_FILE=/path/to/file. synapseia start will skip the prompt.

Copy the wallet address now. You'll paste it into two faucets in the next steps.

Step 3 — Fund with devnet SOL (gas)

Your node needs a small amount of SOL on Solana devnet to pay for on-chain operations (registration, staking transactions). This is test SOL — it has no real value.

Option A — Solana CLI (recommended if installed):

solana airdrop 1 <YOUR_ADDRESS> --url devnet

Option B — Web faucet:

1. Open https://faucet.solana.com.
2. Select Devnet from the network dropdown.
3. Paste your wallet address.
4. Click Confirm Airdrop.

Verify the balance arrived:

solana balance <YOUR_ADDRESS> --url devnet

You should see 1 SOL within a few seconds.

Step 4 — Request SYN tokens (optional, for staking)

SYN is the network's reward token. You can run a node without staking, but staking unlocks higher reward tiers.

1. Open https://dashboard.synapseia.network/faucet.
2. Paste your wallet address.
3. Click Request 10 SYN.

Limits: 10 SYN per request, 1 request per 24 h per wallet.

Step 5 — Start your node

synapseia start

The node will:

• Connect to the official Synapseia coordinator.
• Register on the first heartbeat.
• Heartbeat every ~30 seconds.
• Wait for incoming work orders (training, inference, research).

You should see logs like:

[heartbeat] registered as <peerId>
[heartbeat] tier=0 caps=cpu_inference,research

Step 6 — Verify on the dashboard

Open https://dashboard.synapseia.network/nodes and search for your wallet address. Your node should appear in the list within ~1 minute. If it doesn't, check the Troubleshooting table below.

Optional — node-ui (desktop GUI)

Prefer a desktop app over the CLI? node-ui is a cross-platform Tauri app that wraps the same runtime, uses the same wallet (~/.synapseia/wallet.keystore.json), and points at the same coordinator.

Download from https://github.com/erscoder/synapseia-node-ui/releases:

• macOS: synapseia-node-ui_<version>_aarch64.dmg (Apple Silicon) or _x64.dmg (Intel).
• Windows: synapseia-node-ui_<version>_x64.msi.
• Linux: synapseia-node-ui_<version>_amd64.AppImage.

Run the installer, follow the prompts, and on first launch the app will create or import the same ~/.synapseia/wallet.keystore.json used by the CLI. Click Start to bring the node online — the GUI shows live logs and status.

Troubleshooting

| Message / Symptom | What it means | Fix | |---|---|---| | [BETA_LIMIT_REACHED] Beta tester limit reached. | Coordinator beta cap is full. CLI exits with code 0. | Wait for the next slot bump or for mainnet. Re-run synapseia start later. | | Wallet not funded / insufficient SOL | Wallet has 0 SOL on devnet. | Re-do Step 3 (devnet SOL faucet). | | Coordinator unreachable / ECONNREFUSED | Network problem reaching the official coordinator. | Check your internet connection. Status: status.synapseia.network. | | Cannot find module 'X' | Global npm install was incomplete. | npm i -g --force @synapseia-network/node. | | Modal "Beta tester limit reached" in node-ui | Same as the CLI message above. | Same fix — re-try later. | | Vault passphrase forgotten | The keystore is encrypted; there is no passphrase recovery path. | Restore from the BIP39 recovery phrase you saved at Step 2: delete ~/.synapseia/wallet.keystore.json (and the legacy ~/.synapseia/wallet.json if present), then run synapseia start and pick Restore from mnemonic at the prompt. Without the mnemonic you must delete both files and fund a brand-new address. |

CLI command reference

synapseia start [options]

Main loop — registers the node, heartbeats, executes work orders.

| Flag | Description | Default | |---|---|---| | --model <name> | Ollama model for inference workloads | recommended for hardware | | --llm-key <key> | External LLM API key (optional) | — | | --max-iterations <n> | Maximum work order iterations | infinite | | --inference | Enable inference mode (expose GPU as AI inference provider) | off | | --inference-models <models> | Comma-separated list of models to serve (e.g. ollama/qwen2.5:7b,ollama/llama3:8b) | — | | --lat <n> --lng <n> | Geolocation override (else IP-based) | — | | --set-name <name> | Node display name | — |

Other commands

• synapseia status — current runtime status of your node.
• synapseia balance — wallet SOL + SYN balance.
• synapseia config --show — print current config. --set-name, --set-model, --set-llm-key to edit.
• synapseia stake / unstake / stake-info — stake / unstake SYN, view tier multiplier.
• synapseia claim-rewards / claim-wo-rewards — claim accrued rewards.
• synapseia deposit-sol / deposit-syn / withdraw-sol / withdraw-syn — wallet transfers.
• synapseia system-info — hardware detection report.
• synapseia export-key — export the wallet private key (prompts for password).
• synapseia wallet-create / wallet-verify — wallet provisioning helpers.
• synapseia stop — stop a running node.

Run any command with --help for the full option list.

Configuration & data location

• Wallet: ~/.synapseia/wallet.keystore.json (scrypt + AES-256-GCM, encrypted with your vault passphrase). A legacy ~/.synapseia/wallet.json may also exist on operators that upgraded from pre-0.6.x; both contain the same keypair but the keystore is the only path the runtime reads on fresh installs.
• Config: ~/.synapseia/config.json.
• Logs: stdout / stderr. Redirect to file with:

  synapseia start 2>&1 | tee node.log

• Override home dir: set SYNAPSEIA_HOME=/path/to/dir.

License

This software is licensed under the Functional Source License v1.1 with Apache-2.0 future grant (FSL-1.1-Apache-2.0).

• You can: use it personally, modify it, run nodes for your own use, fork it for non-competing internal purposes.
• You cannot (until 2028-05-07): operate a service or distributed network that competes with Synapseia.
• After 2028-05-07 the license auto-converts to Apache-2.0 — anyone can use it for any purpose, including competing networks.

Full text: see the LICENSE file in this directory.

Links

• Network dashboard: https://dashboard.synapseia.network
• Solana devnet faucet: https://faucet.solana.com
• Solana CLI install: https://docs.solana.com/cli/install
• Ollama install: https://ollama.com
• Issues: https://github.com/erscoder/synapseia-node/issues

Contributing & support

Found a bug? Have a feature request? File an issue on GitHub. PRs welcome — please open an issue first to discuss non-trivial changes.