Spin Up a Chia Docker Node: The Fastest Way to Run a Full Node

• The official Chia Docker image lives at ghcr.io/chia-network/chia:latest on GitHub Container Registry — always pull from there, not unofficial mirrors.^[1]
• Port 8444 is the peer-to-peer communication port for your full node — opening it on your router is strongly recommended for faster syncing and better network health.^[2]
• Always mount ~/.chia as a persistent volume — if you skip this, your entire blockchain database is wiped every time the container restarts.
• Three core service modes are available via the service env variable: full node (default), farmer-only, and harvester.^[1]
• The blockchain database requires an SSD — as of mid-2023 it sat at around 130 GB, so budget for a 256 GB or larger drive.^[3]
• Docker Compose gives you a version-controlled, reproducible setup that beats raw docker run commands for any farm meant to stay online long-term.

A chia docker node lets you run a full Chia Network blockchain node inside a self-contained container, keeping your host system clean and making upgrades as simple as pulling a new image tag. Whether you are on bare-metal Linux, a NAS device, or a dedicated server, the official Chia Docker image gets your node synced and your farmer active with a single command.

Why Run a Chia Docker Node Instead of a Native Install?

The native Chia installer works fine for a single machine, but Docker brings three advantages that matter at scale. First, isolation: your Chia process, its Python dependencies, and its configuration all live inside the container. If something breaks, you rebuild the container rather than untangling a broken system Python environment. Second, reproducibility: the same docker-compose.yml file that runs on your home server will run identically on a cloud VPS or a friend’s machine. Third, upgrade simplicity: updating Chia is a docker pull plus a container restart rather than running an installer and hoping nothing conflicts.

There is also a security dimension that gets overlooked. Running Chia in Docker means the process is sandboxed from the rest of your system. Your farm’s hot wallet keys are mounted in from a specific host directory rather than scattered across a system keychain, making your key hygiene far easier to audit and control.

Who This Setup Is Best For

If you run more than one machine in your farm, use a NAS as a harvester, or simply want consistent behavior across multiple nodes, Docker is the right tool. Solo farmers on a single home desktop might find the native GUI installer easier to start with. But the moment you start talking about two or more machines, a dedicated always-on farming box, or any kind of automated monitoring stack, a containerized chia docker node pays for itself in saved troubleshooting time within weeks.

What You Need Before You Start

You need Docker installed and running on your host. On Ubuntu or Debian, the official Docker Engine install covers this. On Windows or macOS, Docker Desktop handles it. You also need an SSD with enough headroom for the blockchain database — plan for at least 200 GB free, since the database was approximately 130 GB as of mid-2023 and continues to grow.^[3] Spinning-disk HDDs are too slow for the database’s SQLite read/write pattern; an SSD is a hard requirement, not a recommendation.

If you already have plots on your system, note the paths — you will mount them as a volume. If you have an existing mnemonic key file, keep that path handy too. And make sure port 8444 is available to forward on your router. Opening port 8444 is strongly recommended because it lets other Chia nodes connect to yours inbound, which both speeds up your own sync and helps strengthen the overall network.^[2]

Spinning Up a Chia Docker Node: Step-by-Step

All official Chia Docker images are hosted on GitHub Container Registry under the Chia-Network organization. Never pull from a third-party Docker Hub mirror for production use — the only trusted source is ghcr.io/chia-network/chia:latest.^[1]

Option 1: Quick Start With docker run

For a basic full node with farming enabled, open your terminal and run the following. Replace the volume paths with your actual host paths:

docker run -d \
  --name=chia \
  -p 8444:8444 \
  -v /path/to/plots:/plots \
  -v ~/.chia:/root/.chia \
  -v ~/.chia_keys:/root/.chia_keys \
  --restart unless-stopped \
  ghcr.io/chia-network/chia:latest

Breaking this down: -d runs the container in the background. -p 8444:8444 exposes the peer port so other nodes can find you. The three -v flags mount your plots directory, your blockchain database and config, and your keys directory as persistent storage. --restart unless-stopped means the container comes back automatically after a reboot. Without the volume mounts, Docker would store everything inside the container itself — and you would lose your entire synced database whenever the container is removed or updated.

Option 2: Docker Compose (Recommended for Ongoing Farms)

Docker Compose is the better long-term choice because you store your entire configuration as a file you can version-control alongside the rest of your farm setup. Create a docker-compose.yml file with the following content:

version: "3.6"
services:
  chia:
    container_name: chia
    image: ghcr.io/chia-network/chia:latest
    restart: unless-stopped
    ports:
      - "8444:8444"
    volumes:
      - /path/to/plots:/plots
      - /path/to/chia:/root/.chia
      - /path/to/chia_keys:/root/.chia_keys
    environment:
      TZ: "America/New_York"
      # Uncomment below for farmer-only mode:
      # service: farmer-only

Then start it with docker compose up -d. To stop it, use docker compose down. To update Chia, run docker compose pull followed by docker compose up -d — your blockchain data and keys remain untouched because they live on the host filesystem, not inside the container.

The chia docker node setup is designed so that your keys and blockchain data always live on the host, never inside the container itself. This is the most important habit to build — it means updates, crashes, and rebuilds never touch your farm’s persistent state.

Checking Sync Status and Farm Health

Once your container is running, you can talk to the Chia CLI inside it using docker exec. You do not need to shell into the container interactively for routine checks. The two commands you will use most often are:

# Check sync status and peer connections
docker exec -it chia venv/bin/chia show -s

# Check farm summary (plots, estimated time to win, etc.)
docker exec -it chia venv/bin/chia farm summary

The show -s command tells you how many blocks you are synced to, how many peers you are connected to, and whether your node considers itself synced. The farm summary command shows your total plot count, estimated time to win a block reward, and whether your farmer is actively responding to challenges from the network. If you see zero peers, double-check that port 8444 is reachable from the internet using a port checker tool — this is the most common reason a new node stalls during initial sync.^[2]

Service Modes: Full Node, Farmer-Only, and Harvester

One of the most powerful features of the official Chia Docker image is the ability to change which services run inside the container using a single environment variable. By default, the image starts a full node, farmer, harvester, and wallet all together. But for larger farms where machines have specialized roles, you can split these services across separate containers or machines.^[1]

Farmer-Only Mode

If you want to run only the farmer component — useful when you have a dedicated machine that holds your keys and handles block rewards but does not need to also scan local plot files — add -e service=farmer-only to your run command or set it in your Compose file under environment. The farmer still needs a synced blockchain, so it will maintain a full node connection, but it will not run a local harvester process.

Harvester-Only Mode

A harvester-only container scans a set of local plot files and reports proof-of-space challenges back to a remote farmer. This is the key pattern for multi-machine setups: your main machine runs the farmer and holds the keys, while secondary storage machines run harvesters. To set up a harvester, you need to provide the farmer’s IP address, port 8447, and a copy of the SSL CA certificates from your farmer node:

docker run -d \
  --name=chia-harvester \
  -e service=harvester \
  -e farmer_address=192.168.1.100 \
  -e farmer_port=8447 \
  -e keys=none \
  -v /path/to/plots:/plots \
  -v /path/to/ca:/ca \
  -e ca=/ca \
  --restart unless-stopped \
  ghcr.io/chia-network/chia:latest

The CA certificates live on your farmer node under ~/.chia/mainnet/config/ssl/ca. Copy that folder to the harvester machine and mount it into the container as shown above. This certificate exchange is how Chia ensures harvesters can only connect to the farmer they belong to, preventing unauthorized nodes from hijacking your farm.^[3]

Advanced Options for Your Chia Docker Node

Connecting to Testnet

Running a testnet node is useful if you are building on Chialisp or testing new coin puzzles before deploying to mainnet. Simply pass the testnet=true environment variable and expose port 58444 instead of 8444:

docker run -d \
  --name=chia-testnet \
  --expose=58444 \
  -e testnet=true \
  --restart unless-stopped \
  ghcr.io/chia-network/chia:latest

The testnet image uses the same official container, but connects to the Chia testnet blockchain instead of mainnet. This is a clean, low-risk way to experiment with Chialisp smart contracts and the Chialisp smart contract language without putting real XCH at risk.

Enabling External RPC Access

By default, Chia’s RPC server inside the container only listens on 127.0.0.1, which means you cannot reach it from outside the container network. If you want to connect a Grafana monitoring dashboard, a Chia Exporter metrics collector, or a remote GUI client to your node, you need to override the self_hostname setting:

docker run -d \
  --name=chia \
  -e self_hostname="0.0.0.0" \
  -p 8444:8444 \
  --restart unless-stopped \
  ghcr.io/chia-network/chia:latest

Be aware that opening RPC access requires the calling client to hold the correct TLS certificate. The Chia RPC is not an open unauthenticated endpoint — every component (full node, farmer, wallet) generates its own TLS cert pair, and clients must present the matching private cert to make calls. Copy the relevant cert from inside the container to your monitoring host before pointing any external tooling at the RPC port.^[4]

Passing Keys Securely

There are two main ways to provide wallet keys to your container. The first — and simplest for users who already have Chia installed on the host — is to mount the host keychain directory. The second is to mount a plaintext mnemonic file and pass its in-container path via the keys environment variable:

docker run -d \
  --name=chia \
  -v /secure/path/to/mnemonic.txt:/mnemonic.txt \
  -e keys="/mnemonic.txt" \
  -p 8444:8444 \
  --restart unless-stopped \
  ghcr.io/chia-network/chia:latest

Store your mnemonic file on an encrypted volume or use a secrets manager if your infrastructure supports one. Never hard-code a mnemonic as a Docker environment variable in plain text — environment variables are visible in docker inspect output and in container logs, which creates an unnecessary exposure risk.

“All connections between nodes are encrypted and signed with X.509 certificates. Each node generates a certificate and signs it with the Chia CA for connections on port 8444.”

— Chia Network Networking Documentation^[4]

Keeping Your Chia Docker Node Updated

One of Docker’s biggest advantages is how clean updates become. Because your blockchain data, config, and keys all live on the host filesystem via volume mounts, updating Chia requires nothing more than pulling the new image and recreating the container:

# With Docker Compose
docker compose pull
docker compose up -d

# With plain docker run (you need to stop and remove the old container first)
docker stop chia
docker rm chia
docker pull ghcr.io/chia-network/chia:latest
# Then re-run your original docker run command

Your synced blockchain database and wallet keys are never touched during an upgrade, because they live on the host — not inside the container. This is why Docker Compose is worth using: the restart: unless-stopped directive combined with docker compose pull && docker compose up -d gives you a reliable, repeatable upgrade path with zero configuration drift.

If you want to pin to a specific Chia version rather than always running latest, replace the tag with the exact version number, for example ghcr.io/chia-network/chia:2.4.4. Pinning versions is a good practice for production farms where you want to control when you adopt changes.

Conclusion: Your Farm Deserves a Containerized Node

Running a chia docker node is not just a technical preference — it is a solid operational choice that makes your farm more reliable, easier to maintain, and simpler to scale. The official image from ghcr.io/chia-network/chia:latest covers every service mode you need, from a simple single-machine full node all the way to a distributed fleet of harvesters talking to a dedicated farmer. Start with the Docker Compose approach, mount your data to the host filesystem from day one, open port 8444, and you will have a rock-solid foundation for however large your farm grows. Ready to go deeper on Chialisp and what your node can actually do on-chain? Explore how Chialisp is transforming blockchain smart contracts next.

Chia Docker Node FAQs

What is a chia docker node and why should I use one?

A chia docker node is a full Chia Network blockchain client running inside a Docker container. It keeps your host system clean, makes upgrades a one-command operation, and lets you run specialized service modes — full node, farmer-only, or harvester — without touching your host’s software environment.

How do I check if my chia docker node is synced?

Run docker exec -it chia venv/bin/chia show -s from the host terminal. This outputs your current block height and peer count; when the node reports “Full Node Synced,” your chia docker node is current with the network.

What port does the Chia full node use in Docker?

The Chia full node uses port 8444 for peer-to-peer communication between nodes. Publishing this port with -p 8444:8444 and enabling port forwarding on your router allows inbound peer connections, which speeds up sync and improves overall network health.^[2]

Can I run both a farmer and harvester on different machines using Docker?

Yes — run the farmer container on your main machine with service=farmer-only, then run harvester containers on each storage machine pointing at the farmer’s IP using farmer_address and the CA certificates copied from the farmer. This is one of the cleanest use cases for containerized Chia farming.

How do I connect to testnet with a chia docker node?

Add -e testnet=true and expose port 58444 instead of 8444 when running your container. The same official image handles both mainnet and testnet; the environment variable tells the container which network to join at startup.

Chia Docker Node Citations

1. Chia-Network/chia-docker — Official Docker Image Repository, GitHub
2. Node Syncing & Port 8444 — Chia Network Official Documentation
3. Beginner’s Guide to Farming — Chia Network Official Documentation
4. Chia Networking Protocol & TLS Certificates — Chia Network Documentation