2.1 Installation and Quick Start

Flocks supports several installation methods. For first-time use, command-line installation is recommended. If you need to inspect or modify the source code, use source installation. Windows x64 users can use the EXE installer. Docker is better suited to servers or standardized environments.

System Requirements

• Ubuntu >=20.04 / Debian >=10
• RHEL/CentOS family >=8, Rocky 9 or later
• Minimum recommended configuration: 2 cores and 4 GB RAM. Local installation is recommended when possible.

Method	Best For	Notes
Command-line installation	Recommended for most users	Fastest installation path, suitable for macOS / Linux / Windows
Source installation	Users who need to inspect or modify source code	Better for development, full interaction, and later troubleshooting
Windows EXE installer	Windows x64 users	Graphical installation through the setup wizard
Docker installation	Containerized deployment or environment isolation	Out-of-the-box deployment, though interactive browser operations are currently not supported

Option 1: Command-Line Installation (Recommended)

If you want the fastest installation path, use command-line installation first. The script creates ./flocks in the current directory and completes the installation.

For users in mainland China, using the one-click install_zh script on Gitee is recommended.

macOS / Linux

curl -fsSL https://gitee.com/flocks/flocks/raw/main/install_zh.sh | bash

Windows PowerShell (Administrator)

powershell -c "irm https://gitee.com/flocks/flocks/raw/main/install_zh.ps1 | iex"

After installation, enter the project directory and start the service:

cd flocks
flocks start

Option 2: Installing from Source

If you want to inspect the source code first and then run the installation script yourself, install from source:

git clone https://gitee.com/flocks/flocks.git flocks
cd flocks
sh ./scripts/install_zh.sh

Windows PowerShell (Administrator)

powershell -ep Bypass -File .\scripts\install_zh.ps1

Once installed from source, start the service:

flocks start

Option 3: Windows EXE Installer

If you use Windows x64, download the FlocksSetup-<tag>.exe installer from GitHub Releases, then complete the setup wizard.

After installation, start Flocks from the Start menu or desktop shortcut. You can also open a new terminal and run:

flocks start

If you start from a terminal, open a new PowerShell or command prompt window after installation so the updated PATH and other environment variables take effect.

Option 4: Docker Installation

The Docker version does not currently support interactive browser operations through agent-browser.

If environment isolation or fast deployment is more important, pull the image directly:

docker pull ghcr.io/agentflocks/flocks:latest
docker run -d \
  --name flocks \
  -e TZ=Asia/Shanghai \
  -p 5173:5173 \
  --shm-size 4gb \
  -v "${HOME}/.flocks:/home/flocks/.flocks" \
  ghcr.io/agentflocks/flocks:latest

Windows PowerShell

docker run -d `
  --name flocks `
  -e TZ=Asia/Shanghai `
  -p 5173:5173 `
  --shm-size 4gb `
  -v "${env:USERPROFILE}\.flocks:/home/flocks/.flocks" `
  ghcr.io/agentflocks/flocks:latest

Docker registry mirrors for users in mainland China:

• 1ms GHCR: docker pull ghcr.1ms.run/agentflocks/flocks:latest
• dockerproxy GHCR: docker pull ghcr.dockerproxy.net/agentflocks/flocks:latest
• gh-proxy prefix: docker pull docker.gh-proxy.com/ghcr.io/agentflocks/flocks:latest
• milu GHCR: docker pull ghcr.milu.moe/agentflocks/flocks:latest
• NJU GHCR: docker pull ghcr.nju.edu.cn/agentflocks/flocks:latest

Docker is better suited to service-style deployments and is not ideal for workflows that depend on interactive local browser login. If your tasks rely heavily on web login and manual browser interaction, use command-line installation or install from source instead. The image EXPOSE declaration only declares the container port; you still need -p 5173:5173 to access the service from the host browser. The WebUI and API are both served on port 5173, with API requests routed through the /api endpoint.

Prerequisites

Whichever path you choose, confirm these dependencies first:

• uv
• Node.js 22+ (npm is installed with Node.js)
• agent-browser
• bun (optional, used for TUI installation)

The installation script tries to install these dependencies automatically where possible. If automatic npm installation fails during setup, manually install Node.js 22+ and npm. If you are in mainland China, configure a domestic mirror source for uv in advance; this significantly improves installation success rate and dependency download speed.

After installation, continue to Service Startup and Access.