walship

A lightweight agent that streams Cosmos node WAL data to apphash.io for consensus monitoring and debugging.

Prerequisites

Note for Chain Developers Only

This section is for chain developers who need to integrate apphash.io functionality into their chain binary. If you're an operator or partner running an already-integrated chain binary, skip this section and proceed directly to Installation and Running as a Service.

Memlogger must be integrated and enabled on your node. We ship Cosmos SDK releases with memlogger already baked in; if you run a custom fork, you can cherry-pick our single memlogger commit to enable it. For a step-by-step walkthrough, see the Getting Started Guide, or book time via Calendly—we can guide you live or handle it for you.

After integration, ensure $NODE_HOME/config/app.toml includes the following section:

[memlogger]
enabled = true
filter = true
interval = "2s"

Once enabled, WAL files will rotate under <NODE_HOME>/data/log.wal/.

---

Installation

FILE=walship_Linux_x86_64.tar.gz  # pick the tarball for your OS/arch
curl -LO https://github.com/bft-labs/walship/releases/latest/download/$FILE
curl -LO https://github.com/bft-labs/walship/releases/latest/download/checksums.txt

# Verify (Linux)
grep "$FILE" checksums.txt | sha256sum --check -

# Verify (macOS)
grep "$FILE" checksums.txt | shasum -a 256 --check -

# Install
tar xzf "$FILE"
sudo mv walship /usr/local/bin/

Other platforms: see Releases. Checksums (checksums.txt) are published with each release.

Quick Start (Not Recommended)

⚠️ Not recommended for production use. Use Running as a Service instead for better reliability and automatic restarts.

# Get your auth key: https://apphash.io/ → create project → Project Settings.
NODE_HOME="$HOME/.osmosisd"  # e.g., ~/.neutrond, ~/.quasard
walship --node-home "$NODE_HOME" \
  --auth-key <YOUR_AUTH_KEY>

Running as a Service (RECOMMENDED)

Create /etc/systemd/system/walship.service:

[Unit]
Description=Walship
After=network-online.target

[Service]
User=validator
ExecStart=/usr/local/bin/walship \
  --node-home /home/validator/.osmosisd \
  --auth-key <YOUR_AUTH_KEY>
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Adjust User, --node-home, and --auth-key to match your environment. If you prefer not to keep the key in the unit file, you can supply WALSHIP_AUTH_KEY (and other flags) via an EnvironmentFile.

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable --now walship
sudo journalctl -u walship -f  # view logs

Configuration

Essential flags are below; run walship -h to see the full list. All flags can be set via environment variables with WALSHIP_ prefix.

Required

Flag	Env	Description
--node-home	WALSHIP_NODE_HOME	Node home directory (e.g., ~/.osmosisd, ~/.<binary>d)
--auth-key	WALSHIP_AUTH_KEY	Project auth key from apphash.io → Project Settings

Config File

Alternatively, create ~/.walship/config.toml:

node_home = "/home/validator/.osmosisd"
auth_key = "your-key"

Additional Details

• walship auto-discovers chain-id and node-id from your node's config files and genesis.
• Data is sent to api.apphash.io (no custom endpoint or proxy configuration needed).
• The auth key identifies your project; keep it private even though it is not highly privileged.

Troubleshooting

"no index files found"

• Ensure memlogger is enabled in app.toml
• Check WAL files exist in <NODE_HOME>/data/log.wal/ (e.g., ~/.osmosisd/data/log.wal/)

Building from Source

Requires Go 1.22+

git clone https://github.com/bft-labs/walship
cd walship && make build
./walship --help

Documentation

• Getting Started - Full setup guide
• Node Configuration - Detailed memlogger settings
• Architecture - How it works

License

Apache-2.0. See LICENSE.