Guppy's Guide — Don't Panic

Running a CAW node — the operator's guide

For people who run — or want to run — a node for the community deployment of CAW on Ethereum. What a node actually does, what it honestly costs, how to set it up with the one-touch installer, how to keep it delivering, and the mistakes the author of this page made so you don't have to.

New to the deployment itself? Start with the introduction page.

Status note — Nov 17, 2026: the author's own first public node, the one this guide was written from, ended its operation on Nov 17, 2026, by the operator's decision (its data is kept on the server). The on-chain deployment, both apps, the web viewer and these sites continue unchanged, and this guide and the installer kit remain available for anyone who wants to run a node — as of this note, no public node is running, so a new operator would be starting the network's public side again.

1. What a node is, and what a validator is

In this protocol, a post does not go straight from a phone to a blockchain. A user signs an action with their wallet — that signature is the proof of authorship — and the signed action is handed to a node: a server program that is always on. A node does two jobs.

Reading — every node

The node watches the chains (name NFTs on Ethereum, actions on Base), keeps its own indexed copy, and answers the app's and the web viewer's questions: timelines, profiles, notifications. This job needs no keys and no funds at all. If a node lies or goes quiet, users can simply ask another node — the signed actions and the chain remain the source of truth.

Delivering — a node with a validator wallet

A node whose operator has added a validator wallet also takes the signed actions waiting in its queue and submits them to the CawActions contract on Base, paying the gas itself. The contract verifies each signature before accepting anything, so a validator cannot forge or alter a post — it can only deliver, delay, or decline. For each delivered action, the poster's tip (CAW) is credited to the validator's own CAW name.

Nobody's permission is needed to run either kind. There is no application, no allow-list, no official status to apply for: you install the software, and you are a node. Every additional node means the network keeps working even if any single server — including the first one — stops.

2. What you need, and what it honestly costs

No sugar-coating: running a node costs a little money every month, and at today's prices the tips do not pay it back. People run nodes so that their own access never depends on a stranger's server staying up, and so the network is harder to stop — not because it is profitable. Here are the real numbers, measured on the first public node in November 2026. Prices, gas and the CAW price all move, so treat every figure as a dated example, not a promise.

Item What it takes Cost (Nov 2026 examples)
Server (VPS) Ubuntu 24.04, 2 GB RAM minimum (4 GB is comfortable). The node, its database and the indexer all live here. ConoHa 2 GB ≈ ¥1,259/month · XServer VPS 2 GB ≈ ¥1,760–1,980/month · Sakura VPS 2 GB ≈ ¥1,738/month. Check current pricing before you buy.
Delivery gas (validators only) A small amount of ETH on Base in the validator wallet. One delivery (a batch of queued actions, usually one post) cost about 1.2×10⁻⁶ ETH in Base gas + LayerZero fees when measured — roughly ¥0.36 per post. About 0.005 ETH is plenty to start; it covers well over a thousand deliveries at that rate. ≈ ¥0.36 per delivered post, paid by you as it happens.
Tips coming back Every action carries a tip paid by the poster; the default is 1,000 CAW. At the CAW price measured on Nov 12, 2026 (1 CAW ≈ 7.1×10⁻¹² ETH), 1,000 CAW is worth about ¥0.001. The break-even tip at those prices would be roughly 165,000 CAW per delivery. Tips do not cover delivery cost today. A delivering validator is currently subsidising each post by roughly ¥0.36 out of pocket. The first node ran in an explicit "subsidy mode" for exactly this reason (section 4).
A CAW name (validators only) Tips are credited to a name you own, so a delivering validator needs a name NFT (minted in the app or the web viewer; the price depends on the name's length) and its number. One-time, varies by name.

If you only want the reading job, the gas and name rows do not apply: a read-only node costs the VPS and nothing else, and still helps — every reader is one more independent copy of the timeline.

3. Setup, step by step

4. Keeping it healthy: caw-doctor

The installer also places a small operations tool on your server: caw-doctor. It runs entirely on your own machine — your node's local API, your own database, and read-only checks against a public Base RPC. There is no central server and nothing phones home. Four subcommands:

caw-doctor status

A read-only overview: is the service up, does the API answer, what network does it report, how many queue rows sit in each state (pending / processing / done / failed), how old the oldest stuck-looking row is, how much Base ETH the validator wallet holds, and which cawonce the chain expects next for your name. Start here whenever something feels off.

caw-doctor check

The cron-friendly version. Silent success: exit code 0 means healthy. It exits non-zero and prints one line per problem when the API is down, when a row has sat in processing for over 15 minutes (the known stall signature), when any failed rows exist, or when the validator balance falls below 0.0005 ETH (warning) or 0.0001 ETH (critical). An hourly cron entry is enough:

17 * * * * root /usr/local/bin/caw-doctor check >> /var/log/caw-doctor.log 2>&1

caw-doctor restart

Restarts the node service and waits until the API answers again. This is the documented first move when a post stops moving: a row wedged in processing is normally resumed by a restart. It asks for confirmation unless you pass --yes.

caw-doctor unblock

Releases failed queue rows that are blocking new posts. Why this exists: when a signed action fails, its row stays in the queue marked failed — and the node refuses any new action that reuses that row's cawonce (a per-sender sequence number), so one bad row can quietly block a poster's later posts. Deleting database rows by hand is risky, so unblock checks the chain first, for every failed row: it reads the sender's on-chain nextCawonce and offers deletion only when the row's cawonce is provably dead — either it never landed (the chain still expects exactly that number, so freeing it is safe) or it was already consumed on-chain (the row is a ghost). If the chain says anything else, or cannot be read, the row is left untouched. It never touches pending or processing rows, asks before each deletion, and prints exactly what it removed.

The two delivery problems you will actually meet. (1) The stall: the validator delivers one post after a restart, then wedges again on the next — a queue row sits in processing forever. Restart first (caw-doctor restart); that has resumed every stall seen so far. (2) The blockage: posts from one name start failing with a cawonce collision even though the chain is fine — a leftover failed row is holding the number. That is what unblock is for. Both patterns, and the manual recovery they were learned from, are written up in the red lessons below.

5. Day-to-day operations

6. Security, briefly and plainly

Where the author of this page actually got stuck

Everything in this section is red because it deserves to be. These are not generic warnings copied from a checklist — each one actually happened to me while I was setting up the first public node on November 12, 2026, and each one cost me real time. They are written the way I wish someone had written them for me.

#1 — I forgot the root password, and I had not written it down.

This is the expensive one. XServer cannot display your root password to you, and cannot reissue it. There is no recovery flow. My only way back was to reinstall the OS and start the entire setup from zero — server, installer, everything. So: ALWAYS record the password, somewhere you will actually keep, before you do anything else. Two habits that would have saved me: use the "show password" (eye) icon on the setup form and visually confirm what you typed before submitting; and choose a password made only of lowercase letters and digits — phone keyboards auto-capitalise the first letter, and a password you cannot type reliably into a serial console is a password you do not really have.

#2 — The serial console kept "eating" my login.

The VPS serial console's login prompt times out after about 60 seconds and silently resets — if you are slow (say, typing a password carefully on a phone), the prompt you were typing into is already gone, and your password lands nowhere. It looks like the password is wrong; it usually isn't. Just type it again, calmly. Related phone trap: on a phone browser, switching the console to "desktop view" reloads the console screen and the display clears. That clearing does NOT stop anything on the server — my install kept running fine behind the blank screen. Do not panic, and above all do not restart or re-run anything while an install is in progress just because the screen went empty.

#3 — I checked the wrong address, and I listed my node in the wrong shape.

Two small traps, one lesson: the node was fine; my checks were wrong. First, opening the node's root URL (/) shows a web page, not a health answer — liveness lives at /api/instances (and /api/health). I spent time "confirming" a healthy node was broken because I was reading the wrong path. Second, when a node is listed in a nodes.json-style registry, each entry must be an object with a url field — {"url": "https://…"}. I first wrote plain URL strings, and every app silently skipped my node: no error anywhere, it just never connected. If your node seems invisible, check the shape of the entry before you check anything else.

#4 — My node served timelines for hours and delivered nothing.

I finished the install, the timeline loaded, and I assumed posting worked too. It didn't: the installer ships VALIDATOR_PRIVATE_KEY empty on purpose, so my node could read and serve but had no wallet to submit anything with. Nothing told me so — reads succeeding feels like "it works". The validator-wallet step (setup step 4) is a required step, not an optional extra. If your node serves but never delivers, check whether the wallet step was actually done and whether the address holds any Base ETH.

#5 — My node's public address changed underneath me.

The free Cloudflare quick tunnel is a temporary address. When my tunnel restarted, the URL changed — and anything still pointing at the old URL was pointing at nothing. The node does re-announce itself to the registry automatically, and the current address is always written in /opt/caw/node-url.txt, but a quick-tunnel URL is not a permanent address and must never be treated as one. If people suddenly can't reach your node after a restart, compare the URL they are using with the one in that file before debugging anything deeper.

#6 — Posts stopped, and the fix was embarrassingly simple.

My first real stall: a post sat in the queue as processing and nothing moved. I was preparing database surgery when I tried the boring thing first — systemctl restart caw-node — and the stuck post was delivered within a minute. Since then it is always my first move, and it has worked every time so far: the validator seems to deliver once after a restart and then, occasionally, wedge again on the next post. Restarting is cheap and safe; rooting around in the queue database is neither. Only if a restart does not clear it do I look at the queue rows and the logs — and for the one failure a restart cannot fix (a failed row holding a cawonce hostage), that is exactly what caw-doctor unblock was built for.

7. The honest limits

Stuck beyond this page? The node kit's beginner guide (Japanese) covers the manual, step-by-step installation path, and the community channels linked from the Guppy's Guide dashboard are where operators actually talk. Costs and powers for this deployment are kept honest in the transparency report — this page follows the same standard.