pinors/antgain-cli repository overview

⁠AntGain CLI — Docker

Run an AntGain node in a container. Each container needs its own API key and a stable UUID (ANTGAIN_DEVICE_ID) so recreating the container keeps the same device identity on the server.

API key: antgain.app → Settings⁠

⁠Image tags

Docker pulls the manifest for your host CPU (linux/amd64, linux/arm64, linux/arm/v7).

⁠Device UUID (read this first)

ANTGAIN_DEVICE_ID binds your node on the server. Generate a UUID once, save it (.env / Compose), and reuse the same value when you recreate the container.

Do not use -e ANTGAIN_DEVICE_ID=$(uuidgen ...) on every docker run — each new UUID is treated as a new device.

If the container already has ~/.antgain/config.json with a saved id, ANTGAIN_DEVICE_ID in the environment still wins. Pass a fixed env UUID that matches the node you intend to keep.

⁠Quick start

First time — create .env with a new UUID (generate once):

uuidgen | tr '[:upper:]' '[:lower:]'
# Add to .env:
# ANTGAIN_API_KEY=your_api_key_here
# ANTGAIN_DEVICE_ID=f6fdbd41-4e2c-4a1b-9c3d-8e7f6a5b4c2d

docker run -d \
  --name antgain-node \
  --restart unless-stopped \
  --env-file .env \
  pinors/antgain-cli:latest

Check the container:

docker ps --filter name=antgain-node
docker logs -f antgain-node

Inside the container, view the audit log file (English, redacted, antgain.log):

docker exec -it antgain-node antgain logs -f

⁠Required environment variables

Generate a UUID once when creating a new node, then store it in .env or Compose. No volume is required if you always pass the same env UUID.

⁠Optional environment variables

Audit logging is INFO-only in a single file (antgain.log). LOG_LEVEL / RUST_LOG do not change it. Secrets are redacted in the file.

When the backend returns an observed public IP in the active-report API data field, audit lines may include public_ip=...; until then only host_ip is shown.

⁠Docker Compose

docker-compose.yml:

services:
  antgain-node:
    image: pinors/antgain-cli:latest
    container_name: antgain-node
    restart: unless-stopped
    environment:
      ANTGAIN_API_KEY: ${ANTGAIN_API_KEY}
      ANTGAIN_DEVICE_ID: ${ANTGAIN_DEVICE_ID}

export ANTGAIN_API_KEY=your_api_key_here
export ANTGAIN_DEVICE_ID=$(uuidgen | tr '[:upper:]' '[:lower:]')
docker compose up -d
docker compose logs -f antgain-node

⁠Multiple nodes on one host

Each service must use a unique ANTGAIN_DEVICE_ID:

services:
  antgain-node-1:
    image: pinors/antgain-cli:latest
    container_name: antgain-node-1
    restart: unless-stopped
    environment:
      ANTGAIN_API_KEY: ${ANTGAIN_API_KEY}
      ANTGAIN_DEVICE_ID: f6fdbd41-4e2c-4a1b-9c3d-8e7f6a5b4c2d

  antgain-node-2:
    image: pinors/antgain-cli:latest
    container_name: antgain-node-2
    restart: unless-stopped
    environment:
      ANTGAIN_API_KEY: ${ANTGAIN_API_KEY}
      ANTGAIN_DEVICE_ID: 7b718a26-b719-4cbe-a42a-bf1eb563fb14

⁠Logs

Default audit path in the image: /home/antgain/.antgain/logs/antgain.log.

⁠CLI commands inside the container

docker exec -it antgain-node antgain status
docker exec -it antgain-node antgain info
docker exec -it antgain-node antgain logs -f

⁠Upgrade (keep the same device id)

Reuse the same .env / ANTGAIN_DEVICE_ID — do not run uuidgen again.

docker pull pinors/antgain-cli:latest
docker stop antgain-node
docker rm antgain-node
docker compose up -d    # or docker run --env-file .env ...

Or use docker exec antgain-node antgain update before replacing the container (image must include a newer binary on CDN).

⁠Platform support

Static musl binaries — no host glibc version requirement.

Use image 1.1.0+ for ANTGAIN_DEVICE_ID / deviceId registration. When upgrading, keep the same ANTGAIN_DEVICE_ID for the same logical node.

⁠Troubleshooting

Node does not connect after recreate
You used a new ANTGAIN_DEVICE_ID (e.g. uuidgen in the run line) instead of the original UUID. Restore the same UUID from your .env or dashboard device list.

Missing ANTGAIN_DEVICE_ID
Docker nodes require a standard UUID; the process will not start without it.

Device identity conflict
Two running containers share the same ANTGAIN_DEVICE_ID. Stop one or assign a new UUID.

View audit log
docker exec -it antgain-node antgain logs -f

⁠Bare-metal install (Linux / macOS)

User install guides: install.antgain.app⁠ (see antgain-installer documentation).

⁠Links