Run a Canopy full node

This guide gets you a Canopy full node: downloads the chain, follows it, stays synced — no stake, no domain, no application, open and permissionless. What Canopy is, and what its network is actually called: Background.

Hardware requirements

The project's own figures, not yet run by the harness — the card alongside has the minimum.

Step 1: Choose your hardware

No domain, no static IP, no open port — a small rented server is enough.

What to choose on the deploy screen

Using hardware you already own

Connect to your server

Get the IP, root, and password from the provider panel, then run ssh root@<SERVER-IP>: type yes at the prompt, paste the password (nothing shows, that's normal), and you're in.

Step 2: Install Docker, make and git

Run this in the SSH session you opened at the end of Step 1, not on your own computer.

Canopy ships as Docker containers, so the whole stack is Docker Compose. These are the prerequisite commands from the Canopy quickstart, unchanged except that two lines the docs wrap for page width are joined here — a trailing backslash is easy to lose when you copy.

$sudo apt update$sudo apt install -y ca-certificates curl gnupg lsb-release$sudo mkdir -p /etc/apt/keyrings$curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg$echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null$sudo apt update$sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin$sudo apt install -y make$sudo apt install -y git

Nothing in that block is version-specific. The two $( ) substitutions in the fifth line work out your Ubuntu release and your CPU architecture for you, which is why the same paste is correct on 24.04 and on 26.04 — and why the version Canopy's quickstart names, which does not exist, matters less than it looks. Step 1 has the detail on which image to pick.

Step 3: Get the node repository

Clone from your home directory. Every later block in this guide starts by returning to ~/node, so if you clone somewhere else, adjust them to match.

$cd ~$git clone https://github.com/canopy-network/node.git

This is the repository Canopy's docs call "the official source for setting up and operating validator infrastructure". It carries the compose files, the node configuration, the genesis file, and a Makefile that wraps the useful commands. Ask the Makefile what it can do — which doubles as a check that the clone worked:

$cd ~/node$make help

  help             Show available targets
hash-password    Generate a bcrypt hash for AUTH_PASSWORDHASH (prompts for password)
pull             Pull the latest canopynetwork/canopy image
node-up          Start the node only (no monitoring)
up               Starts everything (node, monitoring, etc.)
down             Stop everything
restart          Restart the nodes (reload config.json changes)
logs             Tail node logs
status           Show container status
snapshot         Download mainnet snapshots into data/ (stops nodes first)
snapshot-up      Download mainnet snapshots into data/ and start nodes
gen-key          First-boot: generate validator key

Step 4: Generate the node's key

$cd ~/node$make gen-key

This is the one command on the page you cannot paste and walk away from, so it gets its own step. It asks you for a password and then a name for the key, one after the other, and you have to type both. The password is not echoed as you type it — the same silence as the SSH password prompt in Step 1, for the same reason. Pick something you will still be able to retrieve in a year, and put it in a password manager rather than in your head.

The command writes two files into config/: validator_key.json, the node's operator key, and keystore.json, the encrypted wallet key.

You need this step even though a full node never validates. The node's compose file declares config/validator_key.json as a Docker secret and mounts config/keystore.json into the container, and Docker Compose refuses to start a service whose secret file is missing. So the key comes first, always.

Those two prompts are also why the badge at the top of this page stops where it does. The verification harness runs a guide's commands unattended, and the Canopy CLI reads the password straight from the terminal with no flag to supply it, so a run reaches the end of Step 3 and can go no further. That is a limit of the harness, not of the command — which is why this is an ordinary command block that you type like any other.

Back up those two files, off the box

These run on your own computer, not on the server. scp copies over the same SSH connection, from your machine's side of it. Open a second terminal window and leave the SSH session alone, or type exit in it first and use the same window.

Copy the files one at a time with scp root@<SERVER-IP>:node/config/keystore.json . and then scp root@<SERVER-IP>:node/config/validator_key.json ., putting your server's address in place of <SERVER-IP> as you did for ssh. Four things are worth knowing before you run them:

• The remote path has no leading slash on purpose. It is relative to root's home directory, which is where Step 3 cloned the repository — so node/config/keystore.json.
• The trailing . is the destination, and it means "the folder this terminal is in right now". Run pwd before you start and read the answer: that is where the files will land. On Windows it is usually something like C:\Users\yourname, on macOS /Users/yourname. Nothing wrong with either, as long as you know it and do not go hunting for them on the server afterwards.
• It asks for the server's root password once per file — the same password you logged in with, invisible again as you type it, and twice because this is two separate commands.
• Check they actually arrived. List that folder — ls on macOS or Linux, dir in Windows PowerShell — and confirm both keystore.json and validator_key.json are there and are not zero bytes.

Then move them somewhere you will still have in a year and nobody else can read: an encrypted disk, or a password manager's file or secure-note storage. Not the downloads folder, not a plaintext file in a synced cloud drive, and not back on the server. Losing them costs you nothing today and costs you this node's identity later; leaking them hands that identity to whoever finds them.

validator_key.json and keystore.json are this node's identity, not a place to hold funds — a full node has no stake, so there is nothing of value in them yet. If you ever go further and start holding something you would mind losing, that is the moment a hardware wallet earns its keep:

Step 5: Start the node

$cd ~/node$make node-up

That target is docker compose -f docker-compose.yml up -d node — the node container and nothing else. The first run pulls the canopynetwork/canopy image, so give it a few minutes on a small box.

Two things this deliberately skips, both of which the quickstart includes:

• No .env file. Every field in .env.example configures the domain or the monitoring stack's passwords. The node's compose file falls back to localhost for the external address when no domain is set, which is what you want when you do not have one.
• No snapshot. The quickstart leads with make snapshot-up, which downloads a chain snapshot so you do not sync from block zero. It needs a .env for the snapshot URL and it starts the whole monitoring stack, so this guide syncs from genesis instead — which the quickstart names as a supported option, and which is slower. If you would rather trade the extra RAM for the faster sync, that is the trade on offer.

Because the external address stays localhost, other peers cannot dial you: the Configure page notes that the external address "must be configured or no inbound peers will ever be able to be established". Your node dials out to the seed peers listed in config/config.json instead. For following the chain that is enough, and it is exactly why a full node needs no domain and no open port.

Verify your node

Three checks, in order, because "the command ran" and "the node works" are different claims.

1. The container is up — not just started, but still running a minute later. A node that crashes on startup shows as exited, or as restarting, because the compose file sets a restart policy.

$cd ~/node$docker compose -f docker-compose.yml ps

2. It is talking to the network. This stack has no wallet, explorer or RPC endpoint reachable from outside the container, so the logs are where you look. Canopy's own quickstart names logs as one of the places sync status can be observed.

$cd ~/node$docker compose -f docker-compose.yml logs node --tail 50

3. It is catching up. Run the same log command again ten minutes later. The block height it reports should be higher than it was. A height that never moves means the node is running but not syncing, which is a different and worse problem than a node that will not start.

To watch the logs live rather than take a snapshot of them, use make logs — the same command with follow turned on, which will not exit until you press Ctrl-C.

Points, rewards, and what is actually known

"So what do I get for this?" is the question every node guide gets asked, and it is where most of them start making things up. Here is the whole of what Canopy has published, and where the line between documented and unknown falls.

What the project documents. Its questing-claims page lets a participant record their "current Canopy Testnet campaign progress for possible consideration in a future CNPY distribution", and states, in bold, on the same page: "Submitting points does not confirm eligibility, an allocation, token value, or a distribution date." That sentence is the entirety of the project's own promise, and this site is not going to add to it. Source: Canopy — Questing Claims.

What that means for the node you just built. Read the page's own mechanics carefully, because they matter here: you sign in with an EVM wallet, and Canopy says "we use this wallet to look up the campaign activity associated with it". Points are found by the wallet that took part in the campaign. The validator key you generated in Step 4 is a fresh Canopy key, not that wallet, and running a full node is not listed anywhere on that page as an activity that records points. So do not read this guide as a way to accrue anything — it is a way to run a node. If you took part in the campaign with an EVM wallet, that wallet is what the portal knows about, whether or not a node of yours is ever running.

How the recording flow works, as the page describes it: sign in at app.canopynetwork.org/claim with the EVM wallet used during the campaign; create or select a Canopy destination wallet, which is where a distribution would go and which you are responsible for controlling; then review the points shown and record the submission. Canopy adds that points "may change as campaign activity is added or program rules are applied", and that a submission can be updated while the portal remains available.

If the mechanics of a distribution are new to you — what a claim actually is, how to check one read-only before connecting anything, and why "connect your wallet to check eligibility" is how people lose funds — that is what what happens after a testnet ends is for. It is a page to read before a claim goes live, not after.

Background

Common errors

Filled in properly from the first real harness run. Until then, these are the failures this stack can produce and where they come from. The shape of each one is sourced; the exact error strings are not reproduced here, because nobody has seen them yet on this path and an invented one would be worse than none.

• The node will not start and Compose complains about a missing file. Almost certainly Step 4 was skipped or failed. config/validator_key.json is declared as a Docker secret and has to exist before make node-up.
• The Docker keyring step stops and waits. The gpg --dearmor line in Step 2 asks before replacing an existing keyring file, so running that block a second time prompts instead of completing.
• make gen-key refuses to replace an existing key without confirmation. It prompts before overwriting validator_key.json. Answering yes on a node that already has a key is how you lose the old one.
• make gen-key writes no key and prints writing validator key: expected newline. The nickname prompt had a space in it — see the callout above Step 4. Retry with a one-word nickname.
• Killed mid-sync. The box is under the documented 4 GB, or has no swap. The setup page recommends swap specifically for the minimum configurations, and the compose file caps the node container at 4 GB.
• The height never advances. The node started but is not syncing. Worth ruling out the boring explanation first: a genesis sync on alpha software is slow, and slow is not the same as stuck.

Maintenance

• Upgrades. make pull fetches the latest canopynetwork/canopy image and make node-up restarts the node on it. The shipped configuration also has an auto-update coordinator enabled, so the node can update itself in place.
• Logs. make logs follows them. Canopy rotates and compresses its own logs into a logs/ sub-directory, and its Configure page warns that the directory is worth watching for uncontrolled growth during the alpha and beta phases.
• Disk. The chain only grows. 25 GB is a documented minimum, not a destination — check free space before you need to.
• Stopping. make down stops the stack. Stopping the server is a different thing and, on a rented box, not the thing that ends the bill: only destroying the instance does, and destroying it wipes the disk. Take the Step 4 key backup with you before you do.

Written from the project's documentation, not from a month of running it. Once the harness has run this guide and a node has been up long enough to have an opinion, this section gets rewritten from what actually happened.

FAQ

Is there a reward for running this? Not one anybody can promise you. Canopy documentation lets participants record testnet campaign points for possible consideration in a future CNPY distribution, and says plainly that submitting them confirms no eligibility, no allocation, no token value and no date — and those points are looked up by the EVM wallet used during the campaign, not by the node you just built. Points, rewards, and what is actually known has the detail, the source, and Canopy's safety list. Anyone telling you more than that is guessing.

Can I stake and become a validator with this? Not with this guide. Staking needs the monitoring stack, a domain and CNPY — and the quickstart says the network is permissioned, so getting CNPY means applying and being accepted. A full node is a prerequisite for that path, not a short version of it.

Can I run this on my laptop? More easily than with most node guides, because a full node needs no inbound connections at all. It needs to stay on, stay connected, and have the disk.

Why is there no firewall step? Because the setup page says full nodes do not require any custom networking. The ufw commands in Canopy's docs sit under the validator networking requirements. Enabling a firewall you did not plan for is a good way to lock yourself out of a server you are renting by the month.

Why is this guide marked pending? Because nobody has run these commands and captured the output. The commands are real, and every one of them traces to Canopy's published documentation or its official repository — but that is a weaker claim than "it works", and the badge is the difference between the two. It is cleared by a harness, never by an author who thinks the commands look right.