Installing

Binaries

To install Forest from pre-compiled binaries, please refer to the releases page, or consider using Docker.

Verifying the installation

Ensure that Forest was correctly installed.

forest --version

Sample output:

forest-filecoin 0.19.0+git.671c30c

Docker

Images

Images are available via Github Container Registry:

ghcr.io/chainsafe/forest

tip

If you have trouble using the Github Container Registry, make sure you are authenticated with your Github account.

You will find tagged images following these conventions:

• latest - latest stable release
• vx.x.x - tagged versions
• edge - latest development build of the main branch
• date-digest (e.g., 2023-02-17-5f27a62) - all builds that landed on the main branch

A list of available images can be found here.

Basic Usage

Running the Forest daemon:

docker run --init -it --rm ghcr.io/chainsafe/forest:latest --help

Using forest-cli:

docker run --init -it --rm --entrypoint forest-cli ghcr.io/chainsafe/forest:latest --help

note

More information about Docker setup and usage can be found in the Docker documentation.

Build From Source

Dependencies

• Rust compiler (install via rustup)
• OS Base-Devel/Build-Essential
• Clang compiler
• Go for building F3 sidecar module

For Ubuntu, you can install the dependencies (excluding Rust) with:

sudo apt install build-essential clang

Compilation & installation

Option 1: From crates.io (latest release)

cargo install forest-filecoin

Option 2: From repository (latest development branch)

git clone --depth 1 https://github.com/ChainSafe/forest.git && cd forest

Use mise-en-place to handle the build and installation:

mise install

Both approaches will compile and install forest and forest-cli to ~/.cargo/bin. Make sure you have it in your PATH.

Verifying the installation

Ensure that Forest was correctly installed.

forest --version

Sample output:

forest-filecoin 0.19.0+git.671c30c

Systemd Unit Setup

Running Forest as a systemd Service

This guide shows how to configure Forest to automatically restart on failure and start on system boot using systemd.

Prerequisites

• Forest must be installed and available in your PATH (see other tabs for installation). This guide assumes the forest binary is located at /usr/local/bin/forest.
• You are running commands as root or with sudo privileges
• vi editor. If you're using nano, reconsider your life choices and career path.

Step 1: Create a systemd Service File

Create a new service file for Forest:

vi /etc/systemd/system/forest.service

Add the following content (adjust paths and options as needed):

[Unit]
Description=Forest Filecoin Node
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=forest
Group=forest
# Adjust the forest binary path if needed (check with: which forest)
# You might want to encrypt the keystore in production with `--encrypt-keystore true` and using, e.g., `systemd-creds`
ExecStart=/usr/local/bin/forest --chain calibnet --auto-download-snapshot --encrypt-keystore false --rpc-address=127.0.0.1:1234
# Or for mainnet:
# ExecStart=/usr/local/bin/forest --encrypt-keystore false

# Restart policy
Restart=on-failure
RestartSec=10s

Environment=FOREST_CHAIN_INDEXER_ENABLED=1
# Optional, if F3 is not working properly.
# Environment=FOREST_F3_SIDECAR_FFI_ENABLED=0

[Install]
WantedBy=multi-user.target

tip

For production mainnet nodes, consider creating a dedicated forest user for better security isolation. For development/testing, you can use your own user.

Step 2: Create a Dedicated User (Optional but Recommended)

If you specified User=forest in the service file, create the user:

adduser forest

Make sure the binary is accessible by this user.

Step 3: Enable and Start the Service

Reload systemd to recognize the new service:

systemctl daemon-reload

Enable the service to start on boot:

systemctl enable forest

Start the service immediately:

systemctl start forest

Step 4: Verify the Service is Running

Check the service status:

systemctl status forest

Sample output:

● forest.service - Forest Filecoin Node
     Loaded: loaded (/etc/systemd/system/forest.service; enabled; vendor preset: enabled)
     Active: active (running) since Wed 2026-01-28 10:30:15 UTC; 2min ago
   Main PID: 12345 (forest)

Step 5: View Logs

View real-time logs:

journalctl -u forest -f

View recent logs:

journalctl -u forest -n 100

Troubleshooting

If the service fails to start:

1. Check logs with journalctl -u forest -n 50
2. Verify the forest binary path with which forest
3. Ensure the user has appropriate permissions
4. Check that required directories exist and are writable

note

The Restart=on-failure option ensures Forest automatically restarts if it crashes. The RestartSec=10s adds a 10-second delay between restart attempts to prevent rapid restart loops.