How to set up a Filecoin Lotus node and connect remotely to it

At Wrapped Filecoin (WFIL) we were building the first Filecoin Wrapped Token on Ethereum. We needed to read Filecoin's blockchain directly — monitor transactions, react to events, analyze data in real time.

If you're used to Ethereum, you think of Infura and move on. But Filecoin was too early for hosted node services. We had to run our own.

Here's exactly how we set up a Lotus node on an AWS EC2 instance and configured it for remote JSON RPC access. The official docs got us most of the way, but several steps needed tweaking — so we're sharing what actually worked.

1. Launch an EC2 Instance and Connect via SSH

We used an m5ad.2xlarge with Ubuntu Server 20.04 LTS. Ubuntu is critical — the dependencies for Lotus and Go aren't available on Amazon Linux.

Open port 22 in the security group for SSH access, then connect:

chmod 400 <path-to-pem-file>

ssh -i <path-to-pem-file> ubuntu@<ip-of-your-instance>

2. Install Dependencies, Go, and Rust

sudo apt install mesa-opencl-icd ocl-icd-opencl-dev gcc git bzr jq pkg-config curl clang build-essential libhwloc-dev -y && sudo apt upgrade -y

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

wget -c https://dl.google.com/go/go1.14.7.linux-amd64.tar.gz -O - | sudo tar -xz -C /usr/local

3. Configure Environment Variables

This part is poorly documented and tripped us up. Open the bash profile:

nano ~/.bashrc

Add these lines at the end:

export PATH=$PATH:/usr/local/go/bin
export PATH=$PATH:/home/ubuntu/.cargo/bin

Source it:

source ~/.bashrc

4. Install and Launch Lotus

Clone the repo:

git clone https://github.com/filecoin-project/lotus.git

Checkout your target network. We chose calibration — the testnet closest to mainnet behavior:

git checkout ntwk-calibration

Build and install:

make clean all
sudo make install

Verify:

lotus --version #should output something like lotus version 1.1.0+git.b039f44a

5. Enable Remote Connections

This is where it gets interesting. Open ~/.lotus/config.toml and find the API section. Uncomment and set:

ListenAddress = "/ip4/0.0.0.0/tcp/4001/http"
RemoteListenAddress = "/ip4/xxx.xxx.xxx.xxx/tcp/4001/http"

Replace xxx.xxx.xxx.xxx with your instance's public IP. Open port 4001 in your EC2 security group.

Launch the daemon:

lotus daemon

Create an admin token:

lotus auth create-token --perm admin

Test it from another machine:

curl -X POST      -H "Content-Type: application/json"      -H "Authorization: Bearer <the-token-you-just-generated>"      --data '{ "jsonrpc": "2.0", "method": "Filecoin.Version", "params": [], "id": 1 }'      'http://xxx.xxx.xxx.xxx:4001/rpc/v0'

If you get a version response, you're in.

6. [BONUS] Keep It Running with pm2

The daemon will die if the instance restarts. Use pm2 to auto-restart it.

sudo apt install nodejs
sudo apt install npm
npm install pm2@latest -g

echo lotus daemon >> start-lotus-daemon.sh
sudo env PATH=$PATH:/usr/bin /usr/local/lib/node_modules/pm2/bin/pm2 startup systemd -u ubuntu --hp /home/ubuntu/start-lotus-daemon.sh

pm2 start start-lotus-daemon.sh

pm2 monit

Running your own node is more work than a hosted service. But when the hosted services don't exist yet, having full control of the blockchain data is worth every hour of setup.

Feel free to check out WFIL dapp and let us know your thoughts. We are really looking forward to building the first Filecoin Wrapped Token on Ethereum, hand in hand with the community.

Special thanks to Swaroop and Mostafa for all the help in this process.