Run a Logos blockchain node from Basecamp — Linux / Windows (WSL)
Workshop handout · testnet · Basecamp 0.2.1 · no terminal required (except one install line)
Validated on Ubuntu 24.04. Also confirmed working on Windows via WSL (thanks James).
This is the golden path: the exact sequence that produces a working, syncing node. It deviates from what the app would lead you to do in three places, marked 🛑 and ⚠️:
1.
Install from Package Manager, not Applications (the Applications route cannot install the correct version at all)
2.
Pin blockchain_module to 0.2.0 (the pre-selected version is a devnet build)
3.
Paste the bootstrap peers before generating the config (the default generates none)
Those three are the difference between a node that works and a node that looks fine and does nothing. Follow them exactly.
Why the deviations exist: we dogfooded the default path end-to-end on 2026-07-20. Taking
every default produces a node that starts, reports success everywhere, and never syncs a
single block. All defects are filed upstream — see What's blocking "one click".
Full findings: module-track-runbook.md.
✅ Validated end-to-end on 2026-07-20. Every step below was run start-to-finish on a
freshly wiped Ubuntu 24.04 host by following this document — clean profile, official
release, no prior Logos install. Node was syncing 15 seconds after Start Node
(height 0 → 1001) and reached the chain tip. Each steward's config gets its own keys.

Contents

What you need
Versions — pin these exactly
Step 1 — Install prerequisites
Step 2 — Download Basecamp
Step 3 — Install the node module ⚠️
Step 4 — Install the node UI ⚠️
Step 5 — Open the node view
Step 6 — Fill in the peers ⚠️ — the critical step
Step 7 — Start the node
Step 8 — Verify it's really syncing
Keeping your node running
Fund your node & propose blocks
Troubleshooting
What's blocking "one click"
Notes for the facilitator

What you need

Linux desktop (tested on Ubuntu 24.04.4, GNOME). A real screen — this is a GUI app.
~8 GB RAM, a few GB of disk. Chain sync downloads ~40 MB and grows.
Always-on is strongly preferred. A laptop that sleeps will fall behind and resync.
No prior Logos install needed.
Port forwarding is NOT required for this workshop. A blockchain node works outbound-only — you sync, validate and participate. Forwarding only makes you reachable so others can use you. We cover that separately.

On Windows? Run it inside WSL (steward-confirmed)

Same steps as Linux — just run them inside a WSL2 Ubuntu shell. Windows-specific notes (confirmed by a steward on WSL, ~1 h to green, plain NAT):
WSL2 with an Ubuntu distro installed.
Windows 11, or Windows 10 21H2+ with WSLg (needed for the GUI app).
Use the prebuilt 0.2.1 AppImage (checksum-verified) — do not build Basecamp from source on WSL: the nix build hits a CRLF line-ending snag (nix/main-ui.nix breaks the configurePhase). The prebuilt binary avoids it.
.wslconfig mirrored networking is NOT required — a default-NAT node syncs fine. Only add networkingMode=mirrored (under [wsl2] in C:\Users\<you>\.wslconfig, then restart WSL) if networking misbehaves.
Everything else — module install, the 0.2.0 pin, peers, generate config, start — is identical to the Linux steps below.

On macOS (Apple Silicon)? Same steps, a few Mac notes (proven on M1)

Works on macOS/arm (Basecamp 0.2.1 desktop app), verified on an M1 / macOS 26. Mac-specific notes:
⚠️ Apple Silicon only (M1/M2/M3/M4). Intel Macs are NOT supported — there is no Intel (x86_64) Basecamp .dmg or node module; the only macOS build is arm64. Check Apple menu → About This Mac: Apple M… = good, Intel = use a different machine.
Install via Package Manager, not the Applications route — Applications reverts the core to the devnet 0.0.999 here too.
Install the core blockchain_module 0.2.0 first, then the UI — and in the UI's dependency modal choose "Install just 'blockchain_ui'" (Step 4). "Install with dependencies" pulls the 0.0.999 devnet core.
Don't trust the Package Manager version label — it can show 0.2.0 while the core on disk is still 0.0.999. Trust Step 8.
If Start hangs at "Starting…" or shows "call failed": first just fully quit Basecamp (⌘Q) and relaunch — that clears it most of the time (no data lost). Only if it persists, reset chain state keeping your keys — see the recovery ladder in Troubleshooting. Data dir on Mac: ~/Library/Application Support/Logos/LogosBasecamp/module_data/blockchain_module.

Versions — pin these exactly

component
version
note
Logos Basecamp
0.2.1
official AppImage release
blockchain_module
0.2.0
⚠️ not the pre-selected 0.0.999 — that one is a devnet build
blockchain_ui
0.2.0
its default is already correct
Why 0.0.999 is dangerous: it was published 4 hours after 0.2.0, so the Package Manager lists it first and pre-selects it. It is built for devnet, not testnet. A node running it will never sync the testnet chain, and nothing in the app will tell you — the UI displays "Mainnet · chain ID 1" no matter what you're running.

Step 1 — Install prerequisites

One terminal line. This is the only one.
sudo apt-get install -y libfuse2t64 libegl1 libopengl0
On Ubuntu 22.04 and older use libfuse2 instead of libfuse2t64.
The official docs still say fuse — that package no longer exists on 24.04.

Step 2 — Download Basecamp

Get the Linux AppImage from the releases page:
https://github.com/logos-co/logos-basecamp/releases/tag/0.2.1
File: LogosBasecamp-Desktop-v0.2.1-8a36a8-x86_64.AppImage (~263 MB)
(use the aarch64 build on ARM machines)
Make it runnable and launch it — double-click, or:
chmod +x LogosBasecamp-Desktop-v0.2.1-8a36a8-x86_64.AppImage ./LogosBasecamp-Desktop-v0.2.1-8a36a8-x86_64.AppImage
✅ Checkpoint: Basecamp opens.

Step 3 — Install the node module ⚠️

🛑 Use Package Manager, NOT Applications
Basecamp has two install routes. The Applications route is broken for this module and
will give you a node that cannot work.
If you go Applications → Add Application → blockchain_ui, the Required Packages panel
lists blockchain_module at v.0.0.9…. It has a version dropdown, and the dropdown
does not work — select 0.2.0 and it silently reverts to 0.0.999, the devnet build.
There is no way to install the correct version from that screen.
Always install node modules from Package Manager. (Filed upstream — see the blocking list.)
Sidebar → Package Manager → find blockchain_module (category: Blockchain).
⚠️ Open the version dropdown and select 0.2.0.
Do not just press Install — the pre-selected version is 0.0.999, the devnet build.
Then press Install. It's ~142 MB, so give it a minute.
✅ Checkpoint: the Details pane shows Installed version: 0.2.0.
If it shows 0.0.999, select 0.2.0 in the dropdown and install again — it will offer to upgrade, which is safe.

Step 4 — Install the node UI ⚠️

Same screen → blockchain_ui → version 0.2.0 (already the default) → Install.
🛑 A dependency modal pops up — press "Install just 'blockchain_ui'"
Installing the UI shows: "Install 'blockchain_ui' v0.2.0 — requires changes to 1 dependency:
blockchain_module v0.0.999" with two buttons:
Install with dependencies ← ⚠️ NEVER press this. It overwrites the good 0.2.0 core you just
installed with the devnet 0.0.999.
Install just 'blockchain_ui' ← ✅ press this. Installs the UI only; keeps your 0.2.0 core.
This single click is the difference between a working node and a silent devnet dead-end.
(This is why Step 3 installs the core first — so "Install just the UI" is all you need here.)
✅ Checkpoint: a new blockchain_ui tab is available. (Trust Step 8 — does the node actually serve data? — over the version label; the Package Manager can show 0.2.0 while the core on disk is still 0.0.999.)

Step 5 — Open the node view

Open the blockchain_ui tab. You'll see "Choose how to set up your node config".
Press Generate config. A form appears.

Step 6 — Fill in the peers ⚠️ — the critical step

The form says "All fields are optional." This is true and it is a trap. Generating with everything blank produces a node with no peers, which starts happily and syncs nothing.
⚠️ Paste these four addresses into the "Initial peers" box, one per line:
/ip4/65.109.51.37/udp/3000/quic-v1/p2p/12D3KooWFrouXfmrR4nsLMtE7wu15DoMJ6VtoUtHinREZCvbWHar /ip4/65.109.51.37/udp/3001/quic-v1/p2p/12D3KooWJRGau8M1rjT7R5e4YYsgdFhsMX35nRDtMwCDjxQkXAHz /ip4/65.109.51.37/udp/3002/quic-v1/p2p/12D3KooWQXJavMDTRscjauFSgVAB1VLB6Rzpy2uY5SU9Tk7927tb /ip4/65.109.51.37/udp/50001/quic-v1/p2p/12D3KooWSQc7CcGtvWDPF1yCbBthFnQjprfCVHmfmNDUrSmqQsU1
Leave every other field blank. Leave Deployment: Default selected.
Get this right the first time. Once a config exists the app cannot regenerate it — the Generate button will fail with "User configuration file exists. Use update command", and there is no update button. Recovery means starting over. (Upstream fix filed.)
Press Generate config, then Continue.
✅ Checkpoint: you land on the Node page showing a Peer ID and Not Started.
"Deployment Config: No file selected" — is that a problem?
No, that's correct. The node takes two configs: the User Config you just made (your
ports, peers and keys) and an optional Deployment Config describing the network itself
— genesis block, consensus parameters, timing. When none is given, the node uses the network
definition compiled into the module you installed. Since you installed the testnet build
(0.2.0), that's testnet. Leave it empty. The field exists for people running their own
private network.
This is also why pinning the module version in step 3 matters so much: the module version
is your network.
The header will say "Mainnet · chain ID 1". Ignore it — it is a hardcoded label and
it is wrong. You are on testnet. Upstream fix filed.

Step 7 — Start the node

Press Start Node.
✅ Checkpoint: the Blocks panel begins filling with blocks within a minute or two.

Step 8 — Verify it's really syncing

Don't trust the UI here — verify directly. In a terminal:
curl -s http://127.0.0.1:8080/cryptarchia/info
You want something like:
{"cryptarchia_info":{"lib":"…","slot":874218,"height":28962},"mode":{"Started":"Bootstrapping"}}
Run it twice, ~30 seconds apart. height must increase. That is the only real proof.
height climbing → ✅ you have a working node. Full sync from genesis takes ~20 minutes.
height stuck at 0 → ❌ your peers didn't take. Go to Troubleshooting.

"It still says Bootstrapping after an hour — is it broken?"

No. This confuses everyone, so read this before worrying.
Bootstrapping is a timed hold, not a progress state. After the initial download finishes, the node deliberately waits out a prolonged bootstrap period before declaring itself online:
cryptarchia.service.bootstrap: prolonged_bootstrap_period: '3600.000000000' # 60 minutes
So the timeline from pressing Start Node is:
elapsed
what's happening
what you see
0–20 min
downloading the chain from genesis
height climbing fast, blocks filling in
20–60 min
caught up, following live blocks, waiting out the hold
height tracks the tip, still Bootstrapping, LIB stays at genesis
~60 min
goes online
mode: Online, LIB jumps forward
Measured on our reference run: started 14:43, Online at 15:43:58 — lib_slot went from 0 to 1743644 at that moment.
How to tell "waiting" from "broken": look at height. If it's climbing, or matches the network tip and new blocks keep arriving, the node is healthy — regardless of what mode
says. LIB (last irreversible block) staying at genesis during this window is also normal; it only advances once online.
Broken looks different: height stuck at exactly 0, no blocks, forever.

"I see a red ERROR about Blend — did something break?"

No. You will see this on every start, roughly 60 seconds in:
ERROR ... ServiceStatuses: Blend: ServiceStatus::Starting
Blend deliberately waits for the chain to reach Online — which takes ~60 minutes (see above). The internal watchdog gives up waiting after 60 seconds and logs an error. It is noise; your node is fine. Judge health by height, as always.

What your node is and isn't doing on the Blend network

Your node participates in Blend as an Edge node: it routes its own traffic through the network. It is not a Core node — Core relays other people's traffic and requires an on-chain declaration backed by a locked note (staked funds).
Since the genesis reset wiped balances, nobody can stake right now, so every node from this workshop is Edge. That's expected and fine — your chain node is fully participating. It just means you're using the blend network rather than serving it, the same way an unforwarded node uses the chain without being reachable for others.
This is about the Blend network only — it does not stop your chain node from proposing
blocks. Proposing uses your wallet balance as stake, which you can get from the faucet — see
Fund your node & propose blocks.

Keeping your node running

Read this before you close anything. It is the part people get wrong on day two.

Your node runs only while Basecamp is open

The node is a child process of the Basecamp app. Close Basecamp — or log out, or reboot — and the node stops. There is no background service, no daemon, and nothing that starts it again on its own.
So for the node to keep participating, Basecamp has to stay open. Leaving the machine on with the app running is the whole trick.

After a restart, you must start it again by hand

Reopening Basecamp does not resume your node. The blockchain module opens cold, on the same "Choose how to set up your node config" screen you saw on day one. To get back:
1.
Open the blockchain_ui tab → Set path to config
2.
Your config path is already filled in — you don't need to browse or find anything
3.
Continue
4.
Start Node
Nothing is lost and nothing needs choosing — the app remembers everything. You just have to walk it through those four clicks every time. (Fix requested upstream — see the blocking list.)

If you were offline more than ~20 minutes, expect ~1 hour of "Bootstrapping"

There are two different restart behaviours, and the boundary is 20 minutes:
you were off for
what happens
under ~20 min
node resumes straight to Online — no waiting
over ~20 min
node restarts in Bootstrapping and holds for ~60 minutes
Either way the chain data itself catches up within seconds — we measured 57 blocks recovered in 15 s. What waits is the node declaring itself online.
So if you shut down overnight, your node spends its first hour each morning in Bootstrapping. That's expected, not broken. Watch height, not the status label.

What this means practically

This path gets you a running node, not a permanent one. That's genuinely useful — you sync, validate and participate — but it needs a person and an open window.
If you want a node that survives reboots and runs unattended, that needs the CLI track
(systemd service, no GUI). Ask and we'll set you up — it's the right answer for anyone with an always-on box or a headless server.

Fund your node & propose blocks

(Optional — a synced node is already contributing. This is how to go further and propose.)
A synced node validates the chain, but it won't propose blocks until its wallet has a balance.
For chain leadership your wallet balance is your stake, automatically — there is no manual "lock" step. The full path:
1.
Copy a wallet key. Node view → Operations → Accounts → copy one of your keys. (Accounts panel blank? Grab a key from the keystore instead — see Troubleshooting.)
2.
Fund it at the faucet. Go to https://testnet.blockchain.logos.co/web/faucet/ , paste the key, and click Request Funds — do this once your node is Online.
3.
Funds auto-stake. Your balance counts as stake automatically. The node starts winning leader slots proportional to it and proposes blocks on its own — you never click "propose."
4.
Claim rewards. Each won slot earns a reward voucher; these show up under Operations → Leader Rewards, where Claim redeems them into your wallet.
No open ports required — an outbound-only (Private) node can still propose once funded.
Not the same as Blend staking. The Blend network's Core role needs a separate locked note
and is blocked by the genesis reset — that does not affect block proposing.

Troubleshooting

Node says Online / height is climbing, but "Consensus: Call failed" (or Accounts won't load)
The node is fine — that's a UI-side hiccup, not a node fault. The core is healthy; the UI just can't render the consensus/accounts call. Recover in this order, least-destructive first:
1.
Fully quit Basecamp and relaunch. Actually Quit it (not just close the window), reopen, and go back to the node. This re-runs the capability handshake and clears most "call failed"
cases — nothing is lost. (Steward-confirmed: this alone fixed it, no wipe needed.)
2.
Check the versions match. Package Manager should show both blockchain_module and blockchain_ui at 0.2.0 — a UI/core version mismatch is the #1 cause of this message.
3.
Only if it's still stuck (or it hangs on "Starting…") — reset the chain state, keeping your keys: quit Basecamp, delete just db/ and state/ inside ~/.local/share/Logos/LogosBasecamp/module_data/blockchain_module/<id>/ (not the whole folder — that deletes your wallet keystore), relaunch, and Start. The node re-syncs from genesis.
Don't wipe a node that's actually syncing. If curl http://127.0.0.1:8080/cryptarchia/info
shows a climbing height, the "call failed" is only the UI — a restart (step 1) is enough.
Need your wallet address while the Accounts panel is blank (e.g. to fund it at the faucet)?
Your keys are safe in the keystore regardless of what the UI shows — grab an address directly:
cd ~/.local/share/Logos/LogosBasecamp/module_data/blockchain_module/<id>/ grep -A20 public_keys keystore.yaml # your wallet public keys = addresses grep funding_pk user_config.yaml # also present here
Paste one into the faucet — https://testnet.blockchain.logos.co/web/faucet/ — and click Request Funds.
height stays 0 / "No blocks yet…" forever
Your initial_peers are empty — the most common failure. The app won't overwrite an existing config, so you have to regenerate it. To keep your wallet keys, delete only the config + state, not the keystore: quit Basecamp, then inside ~/.local/share/Logos/LogosBasecamp/module_data/blockchain_module/<id>/ delete user_config.yaml, db/, and state/ (leave keystore.yaml), restart, and redo steps 5–7 — careful with step 6.
Log says Skipping IBD as no peers are configured
Same cause. Note it also logs "Initial Block Download completed successfully" immediately after — that success line is misleading and is filed upstream.
Installed the wrong module version
Package Manager → blockchain_module → pick 0.2.0 → Install. It will offer to upgrade and tells you which running modules restart. Safe to accept.
Basecamp won't launch
Usually the FUSE prerequisite (step 1). Also try clearing the QML cache: rm -rf ~/.cache/Logos.
Where the logs are
~/.local/share/Logos/LogosBasecamp/logs/ — newest file. Also /tmp/ if you launched from a terminal with output redirected.

What's blocking "one click"

🎯 The goal is to make this guide obsolete — every row below is a manual step that only exists because of the linked bug. When they're fixed, the guide isn't needed. Tracked upstream at https://github.com/logos-co/ecosystem/issues/170.
Today this handout needs two manual deviations (steps 3 and 6). Each maps to a filed issue.
When these land, the golden path collapses into install → install module → Start.
Blocks
Issue
Fix (mine, unless noted)
1
No bootstrap peers ship with the module, and the skipped download is logged as success. Forces step 6.
https://github.com/logos-blockchain/logos-blockchain/issues/3153
https://github.com/logos-blockchain/logos-blockchain-ui/pull/39
2
Config can't be regenerated from the GUI — --overwrite exists but the UI never passes it. Makes step 6 unforgiving.
https://github.com/logos-blockchain/logos-blockchain-ui/issues/35
—
3
Version dropdown sorts by date, not semver → pre-selects the devnet 0.0.999. Forces step 3.
https://github.com/logos-co/logos-package-manager-ui/issues/54
https://github.com/logos-co/logos-package-manager-ui/pull/58
3b
Applications route: version selector silently reverts to 0.0.999 — no workaround exists on that path. Forces the "use Package Manager" warning.
https://github.com/logos-co/logos-package-manager-ui/issues/54#issuecomment-5023034119
https://github.com/logos-co/logos-package-manager-ui/pull/58
4
UI hardcodes "Mainnet · chain ID 1" regardless of network — hides #3.
https://github.com/logos-blockchain/logos-blockchain-ui/issues/34
—
—
Ubuntu 24.04 prereqs wrong in docs. Affects step 1.
https://github.com/logos-co/logos-docs/issues/404
—
—
No release checksums; catalog packages unsigned.
https://github.com/logos-co/logos-basecamp/issues/273
—
5
Node doesn't resume after restart — config is remembered but the wizard must be re-walked and the node started by hand.
https://github.com/logos-blockchain/logos-blockchain-ui/issues/36
https://github.com/logos-blockchain/logos-blockchain-ui/pull/40
6
No module autostart — modules can't run independently of the app/UI, so no unattended node.
https://github.com/logos-co/logos-basecamp/issues/275
—
7
Dependency modal defaults the core to the devnet 0.0.999 — "Install with dependencies" downgrades a good 0.2.0 core. Forces the "Install just blockchain_ui" step.
https://github.com/logos-co/logos-package-manager-ui/issues/56
fixed on master — https://github.com/logos-co/logos-package-downloader/pull/17
8
PM row shows the upgrade target, not the installed version — you can't tell what you're running. Forces the "verify on disk" step.
https://github.com/logos-co/logos-package-manager-ui/issues/57
—
9
"Generate config" silently no-ops (needs 3+ restarts on some states). Forces the restart-retry note.
https://github.com/logos-blockchain/logos-blockchain-ui/issues/37
—
10
Bare "call failed" is the only diagnostic across 3 different faults; no log pointer. Forces "read the logs".
https://github.com/logos-blockchain/logos-blockchain-ui/issues/38
—
11
Node doesn't recover after an unclean shutdown (chain service spams channel closed, API dead). Forces the clear-config+restart step.
https://github.com/logos-blockchain/logos-blockchain/issues/3171
https://github.com/logos-blockchain/logos-blockchain-ui/pull/42
12
Node hard-aborts (SIGABRT) when no peers reachable instead of failing gracefully.
https://github.com/logos-blockchain/logos-blockchain/issues/3166
—
—
Intel Macs unsupported, not detected at launch (no build exists). Forces the Apple-Silicon-only warning.
https://github.com/logos-co/logos-basecamp/issues/277
—
—
WSL from-source build fails on CRLF in nix/main-ui.nix. Forces the "use prebuilt AppImage" note.
https://github.com/logos-co/logos-basecamp/issues/288
https://github.com/logos-co/logos-basecamp/pull/289
Umbrella / tracking: https://github.com/logos-co/ecosystem/issues/170
Fixing 1 and 3 alone gets us to one-click. Both are small: ship the peers you already publish in the Quick Start, and sort a dropdown by semver using the comparator the app already has elsewhere.

Notes for the facilitator

Do not hand out a shared user_config.yaml. The generated config embeds a per-node libp2p node_key plus keystore-linked key IDs — copies would collide on one peer identity.
Pasting peers into the form (step 6) gives each steward their own keys.
Step 6 is where people will fail. Have the four addresses in the chat, pre-formatted, and watch each steward's Blocks panel before moving on.
Step 8 is not optional. The UI reports success in states where nothing is happening, so a visual check is not evidence.
Stewards without always-on hardware or router control should go to the community-infra
track instead — see pre-flight-checklist.md. This handout is for the self-host track.