Quick Installation Guide (Single-Machine Offline Package Deployment)

FinClaw ships with an official one-shot installer install-finclaw.sh that wizards you through every option up-front, then unattendedly installs Docker, downloads and extracts the offline package, loads images, initializes .env, writes the LLM config, starts services, and runs health checks.

1. One-Shot Install (Recommended)

Prerequisites

Item	Requirement
Privileges	root (or sudo)
OS	CentOS 8+ / RHEL 8+ / Ubuntu 22.04+, x86_64
Network	Reachability to static.finogeeks.club and the release URL (the script downloads on demand)
Base tools	curl, tar, openssl (the script checks)
Docker	Optional — if missing, the script auto-installs the offline package

One Command

curl -fsSL https://static.finogeeks.club/deploy/init_env/install-finclaw.sh -o install-finclaw.sh \
  && sudo bash install-finclaw.sh

Non-root users must use sudo. The script aborts immediately when not run as root.

What the Wizard Asks

The script collects every choice up-front, then confirms so the long-running steps run uninterrupted:

Question	Default	Notes
Install Docker	(asked only if missing)	Auto-downloads the Docker offline package from static.finogeeks.club
Docker data dir	/data/docker	Empty = default; entering /data/2026 auto-appends /docker
Release URL	—	Required, must start with http(s)://
Install / extract dir	/data	The release package is extracted here
Target dir exists	—	1) skip extraction and reuse / 2) abort
LLM_PROVIDER	openai	OpenAI-compatible (Xinference / vLLM / custom gateway, etc.)
LLM_MODEL	deepseek-v4-flash	Must match the upstream model name
LLM_BASE_URL	https://api.deepseek.com/v1	OpenAI-compatible Base URL, must include /v1
LLM_API_KEY	—	Required; use not-empty when the endpoint has no auth

After confirmation, the script proceeds with 6 unattended steps:

Step	Action
1/6	Install Docker (if needed)
2/6	Download & extract the release package (cached under <install_root>/.cache/)
3/6	load-images.sh basic
4/6	init-env.sh — generate .env from .env.example, mint Identity JWT keys
5/6	Write LLM config + probe LLM connectivity
6/6	fleet.sh basic up -d, wait 10 s, run doctor.sh

When done it prints access info:

End users:  http://<server-ip>:26100/
Admin:      http://<server-ip>:26100/admin/

Local health check:
  curl http://127.0.0.1:26100/health
  curl http://127.0.0.1:26450/health

Update LLM: sudo ./install-finclaw.sh update-llm

State File

The script writes installation details to <install_root>/.finclaw-install.state (default /data/.finclaw-install.state) so update-llm can locate the deploy directory automatically:

INSTALL_ROOT=/data
RELEASE_DIR=/data/chatkit-offline-release-1.0.96-linux-amd64
DEPLOY_DIR=/data/chatkit-offline-release-1.0.96-linux-amd64/deploy
EDITION=basic
INSTALLED_AT=2026-06-23T08:00:00Z
RELEASE_URL=https://temp-...../chatkit-offline-release-1.0.96-linux-amd64.tar.gz

2. Other Script Commands

Update LLM Config

Updates LLM_* and automatically does fleet.sh basic down && up -d:

# Auto-locate the deploy dir from /data/.finclaw-install.state
sudo bash install-finclaw.sh update-llm

# Or specify the deploy dir explicitly
sudo bash install-finclaw.sh update-llm -d /data/chatkit-offline-release-1.0.96-linux-amd64/deploy

Help

bash install-finclaw.sh --help

3. Environment Variables

Variable	Default	Purpose
FINCLAW_DOCKER_CACHE_DIR	<docker-data-dir>/.cache	Docker offline package cache (script downloads but never deletes)
DOCKER_INIT_URL	https://static.finogeeks.club/deploy/init_env/init/docker29.tar.gz	Docker offline package URL

4. Manual Deployment (Fallback)

When to use:

• Fully air-gapped environments without access to static.finogeeks.club or the release URL (you must hand-transfer the package).

# 1. Extract the release package
tar -xzf chatkit-offline-release-<version>-linux-amd64.tar.gz
cd chatkit-offline-release-<version>-linux-amd64/deploy

# 2. Verify package integrity
sha256sum -c CHECKSUMS.sha256

# 3. Load images
./scripts/load-images.sh basic

# 4. Initialize the environment (generates .env and JWT keys)
./scripts/init-env.sh

# 5. Edit .env — at minimum configure LLM
vi .env
# LLM_PROVIDER=deepseek
# LLM_MODEL=deepseek-v4-flash
# LLM_API_KEY=<your-key>
# LLM_BASE_URL=https://api.deepseek.com/v1

# 6. Start
./scripts/fleet.sh basic up -d

# 7. Health check
./scripts/doctor.sh

5. Common Issues

Symptom	Cause / Resolution
root required	Use sudo bash install-finclaw.sh
Unsupported CPU architecture	Script supports amd64 / arm64 only
URL must start with http:// or https://	Use the full release URL
File is not a valid gzip archive	Download was interrupted or URL wrong — retry
LLM connectivity check failed (HTTP xxx)	Containers cannot reach the host via localhost — use the host IP or Docker gateway address
doctor.sh reports failures	First start takes 2–5 minutes; wait then re-run ./scripts/doctor.sh
Target dir already exists	Choose 1 to skip and reuse, or 2 to abort and manually clean up

6. Uninstall / Reinstall

The script has no uninstall command. Manual cleanup:

# 1. Stop services
cd /data/chatkit-offline-release-<version>-linux-amd64/deploy
./scripts/fleet.sh basic down

# 2. Remove data volumes (for full cleanup)
docker volume ls | grep chatkit
docker volume rm <volume-name>

# 3. Remove the release dir and state file
rm -rf /data/chatkit-offline-release-<version>-linux-amd64
rm -f  /data/.finclaw-install.state
rm -f  /data/.cache/chatkit-offline-release-*.tar.gz   # to free cache

To reinstall, run the one-shot script again; when prompted about an existing target dir, choose abort, clean up manually, and retry.