Testnet version 0.2: Node Operator Guide

Overview §

Run one Logos node with one logoscore daemon and one shared modules directory.

This guide starts these modules:

Module	Package	Public ports
Blockchain	blockchain_module	3000/udp
Storage	storage_module	8090/udp, 8091/tcp
Delivery	delivery_module	9000/udp, 30303/tcp

Commands assume a Linux host and these default paths:

/usr/local/bin/logoscore
/usr/local/bin/lgpd
/usr/local/bin/lgpm
/opt/logos-node/modules
/opt/logos-node/packages
/var/lib/logos-node

Replace <public-ip> with the public IPv4 address of the node. Run the module commands as the same OS user that owns /var/lib/logos-node.

Install Runtime Tools §

Install curl, jq, and FUSE support for AppImage binaries.

apt-get update
apt-get install -y curl jq wget fuse3

Download the Linux release assets from each repository’s Releases page:

Tool	Repository
logoscore	https://github.com/logos-co/logos-logoscore-cli
lgpd	https://github.com/logos-co/logos-package-downloader
lgpm	https://github.com/logos-co/logos-package-manager

For x86_64 Linux, these were the current download URLs on 2026-06-25:

wget https://github.com/logos-co/logos-logoscore-cli/releases/download/v3/logoscore-x86_64-linux.AppImage
wget https://github.com/logos-co/logos-package-downloader/releases/download/pre-release-99d70db-7/lgpd-x86_64-linux.tar.gz
wget https://github.com/logos-co/logos-package-manager/releases/download/pre-release-05b2cf8-7/lgpm-x86_64-linux.tar.gz

Install the tools under /usr/local/bin with the expected command names:

install -m755 logoscore-x86_64-linux.AppImage /usr/local/bin/logoscore
tar -xzf lgpd-x86_64-linux.tar.gz
install -m755 lgpd-x86_64.AppImage /usr/local/bin/lgpd
tar -xzf lgpm-x86_64-linux.tar.gz
install -m755 lgpm-x86_64.AppImage /usr/local/bin/lgpm

Verify:

logoscore --help
lgpd --help
lgpm --help

Prepare The Host §

Create the runtime user and directories:

useradd --system --home /var/lib/logos-node --create-home --shell /usr/sbin/nologin logos
mkdir -p /opt/logos-node/modules /opt/logos-node/packages
mkdir -p /var/lib/logos-node/blockchain-module-devnet
mkdir -p /var/lib/logos-node/storage-module
mkdir -p /var/lib/logos-node/delivery-module
chown -R logos:logos /var/lib/logos-node

Open these ports on the host firewall:

3000/udp
8090/udp
8091/tcp
9000/udp
30303/tcp

Install Modules §

lgpd download downloads the version published in the configured module catalog. It does not automatically build or fetch the newest commit from the module repositories. For a testnet, publish the intended module versions in the catalog before operators run these commands.

Download the module packages from the configured module catalog:

lgpd download blockchain_module --output /opt/logos-node/packages
lgpd download storage_module --output /opt/logos-node/packages
lgpd download delivery_module --output /opt/logos-node/packages

Install all three packages into the shared modules directory:

lgpm --modules-dir /opt/logos-node/modules install --file /opt/logos-node/packages/blockchain_module-0.2.0.lgx
lgpm --modules-dir /opt/logos-node/modules install --file /opt/logos-node/packages/storage_module-*.lgx
lgpm --modules-dir /opt/logos-node/modules install --file /opt/logos-node/packages/delivery_module-*.lgx

Check installed versions:

jq -r '.name + " " + .version' /opt/logos-node/modules/*/manifest.json

Start Logos Core §

For a first manual run, start logoscore in the foreground with the shared modules directory:

cd /var/lib/logos-node
logoscore -m /opt/logos-node/modules

Keep that terminal open. Use another terminal for module commands.

For a detached manual run, start logoscore in daemon mode with -D:

cd /var/lib/logos-node
logoscore -m /opt/logos-node/modules -D

For unattended operation, prefer a systemd service over a manually started daemon.

Check:

logoscore status

Blockchain §

Create the blockchain peer file:

cd /var/lib/logos-node/blockchain-module-devnet
cat > peers.json <<EOF
{
  "initial_peers": [
    "/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"
  ]
}
EOF

Load the module and generate user_config.yaml:

logoscore load-module blockchain_module
cd /var/lib/logos-node/blockchain-module-devnet
logoscore call blockchain_module generate_user_config "$(cat peers.json)"
chmod 600 /var/lib/logos-node/user_config.yaml

generate_user_config writes user_config.yaml in the logoscore daemon working directory. With the service layout in this guide, that path is /var/lib/logos-node/user_config.yaml.

The generated user_config.yaml contains node-local wallet and key-management configuration. Keep it private, restrict file permissions, and do not publish it. Generate a fresh file for each node.

Start the module. The second argument is intentionally an empty string; the blockchain module no longer requires a downloaded deployment.yaml file:

logoscore call blockchain_module start /var/lib/logos-node/user_config.yaml ""

Check:

logoscore call blockchain_module get_cryptarchia_info | jq -r .result.value | jq .

Blockchain Config §

Operator-facing fields in user_config.yaml:

Field	Purpose	Guidance
network.initial_peers	Bootstrap peers	Use the current network document
network.port	Public UDP P2P port	Keep aligned with firewall/NAT, normally 3000
api.listen_address	Local API bind	Keep private, normally 127.0.0.1:8080
state.base_folder	State directory	Use a persistent local path
logger filters	Log verbosity	Use INFO for unattended operation

Storage §

Create the storage config:

Replace <public-ip> before running this command.

cd /var/lib/logos-node/storage-module
mkdir -p storage-data
cat > config.json <<EOF
{
  "data-dir": "./storage-data",
  "log-level": "INFO",
  "listen-ip": "0.0.0.0",
  "listen-port": 8091,
  "disc-port": 8090,
  "nat": "extip:<public-ip>",
  "network": "logos.test"
}
EOF

Fields:

Field	Purpose
data-dir	Storage repository path
log-level	Log verbosity
listen-ip	Local TCP bind address
listen-port	Public TCP libp2p port
disc-port	Public UDP discovery port
nat	Public IP advertisement mode
network	Storage network preset

The logos.test network preset provides the storage bootstrap settings.

Use fixed listen-port and disc-port. Do not leave public nodes on random ports.

Optional: Mix Support And Private Queries §

To run storage with mix support, generate the storage config from the current published mix bootstrap data. This replaces the basic config.json above.

cd /var/lib/logos-node/storage-module
cat > make-mix-storage-config.sh <<'EOF'
#!/usr/bin/env bash
set -e
 
data_dir=${1:-"./logos-storage-data"}
udp_spr_json=$(curl -s https://logos-storage-network.fra1.digitaloceanspaces.com/v0.2/udp-sprs.json)
tcp_spr_json=$(curl -s https://logos-storage-network.fra1.digitaloceanspaces.com/v0.2/tcp-sprs.json)
 
wget https://logos-storage-network.fra1.digitaloceanspaces.com/v0.2/mix-pool.json
mp_path=$(realpath "./mix-pool.json")
 
cat <<JSON
{
  "nat": "any",
  "log-level": "DEBUG",
  "mix-enabled": true,
  "listen-port": 8080,
  "disc-port": 8090,
  "bootstrap-node": $udp_spr_json,
  "dht-mix-proxy": $tcp_spr_json,
  "data-dir": "${data_dir}",
  "mix-pool": "${mp_path}"
}
JSON
EOF
 
chmod 755 make-mix-storage-config.sh
./make-mix-storage-config.sh > config.json

Start storage with that config:

logoscore load-module storage_module
logoscore call storage_module init @config.json
logoscore call storage_module start
logoscore call storage_module togglePrivateQueries true

Privately query a known test object:

logoscore call storage_module downloadToUrl zDvZRwzkzrrYB6sS1rRpRLt4gBhc1pWoyTSjkfszfmj1seaYYLCZ ./farewell-to-westphalia.pdf false 65536

Start:

cd /var/lib/logos-node/storage-module
logoscore load-module storage_module
logoscore call storage_module init @config.json
logoscore call storage_module start

Delivery §

Create the delivery config:

Replace <public-ip> before running this command.

cd /var/lib/logos-node/delivery-module
cat > config.json <<EOF
{
  "preset": "logos.test",
  "mode": "Core",
  "logLevel": "INFO",
  "tcpPort": 30303,
  "discv5UdpPort": 9000,
  "discv5Discovery": true,
  "nat": "extip:<public-ip>"
}
EOF

Fields:

Field	Purpose
preset	Network preset
mode	Delivery node mode
logLevel	Log verbosity
tcpPort	Public TCP P2P port
discv5UdpPort	Public UDP discovery port
discv5Discovery	Enable discv5 discovery
nat	Public IP advertisement mode

The logos.test preset provides the delivery network bootstrap settings. extMultiaddrs is usually not needed when nat advertises the public address.

Use fixed tcpPort and discv5UdpPort. Do not leave public nodes on random ports.

Start:

cd /var/lib/logos-node/delivery-module
logoscore load-module delivery_module
logoscore call delivery_module createNode @config.json
logoscore call delivery_module start

Check:

logoscore call delivery_module getNodeInfo Version
logoscore call delivery_module getNodeInfo MyBoundPorts

Health Checks §

Check daemon and modules:

logoscore status --json

Expected modules:

storage_module
blockchain_module
delivery_module
capability_module

Check listeners:

ss -lntup | egrep '(:3000|:8090|:8091|:9000|:30303|:8080)'

Expected:

0.0.0.0:3000/udp
0.0.0.0:8090/udp
0.0.0.0:8091/tcp
0.0.0.0:9000/udp
0.0.0.0:30303/tcp
127.0.0.1:8080/tcp

Check blockchain:

logoscore call blockchain_module get_cryptarchia_info | jq -r .result.value | jq .

Check delivery:

logoscore call delivery_module getNodeInfo MyBoundPorts

Optional: Systemd §

For unattended operation, use systemd.

Recommended pattern:

• one service for logoscore;
• one separate bootstrap service or script for module startup;
• journald output with retention limits.

Do not start modules from ExecStartPost in the logoscore service. If module startup is slow or returns an error, systemd may kill the daemon.

The daemon service should do only this:

[Unit]
Description=Logos Node
After=network-online.target
Wants=network-online.target
 
[Service]
User=logos
Group=logos
WorkingDirectory=/var/lib/logos-node
Environment=HOME=/var/lib/logos-node
ExecStart=/usr/local/bin/logoscore -m /opt/logos-node/modules -D
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
 
[Install]
WantedBy=multi-user.target

The bootstrap script should:

1. wait for logoscore status;
2. load and start storage;
3. load and start blockchain;
4. load and start delivery;
5. tolerate already-loaded modules and slow module starts.

Cap journal usage:

[Journal]
SystemMaxUse=200M
SystemKeepFree=1G
MaxRetentionSec=7day
MaxFileSec=1day

Prefer INFO logs for unattended operation. Use DEBUG only for short troubleshooting windows.