3.1 Remote Deployment

Flocks runs locally by default. After running flocks start, it listens on:

• Flocks unified service: 127.0.0.1:5173
• WebUI: http://127.0.0.1:5173
• API: the /api path under the same address

The WebUI and API are served from the same address and port. Browser API requests go through the /api endpoint on the same host and port, so there is no need to expose a separate backend port.

3.1.1 Recommended Method: Basic Binding

Listen on a specific internal IP:

flocks start --host <internal_ip>

If you need to listen on all network interfaces:

flocks start --host 0.0.0.0

When using 0.0.0.0, always restrict the access scope with a firewall, security group, reverse proxy, and TLS. External services that call the API should also access the /api path through the same entry point and include an API Token. Do not expose the legacy 8000 port for ordinary deployments.

3.1.2 Quick Check

1. Confirm the service started successfully: flocks status
2. Open http://<host_ip>:5173 from an external browser.
3. After login, verify full operational status rather than just page rendering. Confirm that sessions, tasks, and model tests return correctly.

curl http://127.0.0.1:5173/api/health

3.1.3 Remote Access with Docker

If you deploy with Docker, only map the unified service port:

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

The Flocks service in the image listens on 5173, which serves both the WebUI and API. If the container runs but the WebUI is unreachable, check whether 5173 is unmapped, mapped incorrectly, or blocked by the host firewall or cloud security group.

3.1.4 Common Issues and Fixes

The service listen address, access URL, or port exposure policy may not be configured for a remote scenario.

Symptom	Common Cause	Fix
External machines cannot open the WebUI	The service still listens on 127.0.0.1, so only the server itself can access it	Start with flocks start --host <internal_ip> or flocks start --host 0.0.0.0, and confirm the cloud security group and firewall allow 5173
The WebUI loads, but starting chats or testing models fails	/api requests fail on the same host and port, or account/model configuration is incomplete	Check /api requests in the browser and flocks logs, then confirm account initialization, API Token, and model configuration
API requests from external scripts return 401 Unauthorized	The API request is missing an API Token	Use the Authorization: Bearer <token> or X-Flocks-API-Token: <token> request header
Docker container starts successfully, but external access still fails	5173 is not mapped correctly, or the host security group does not allow it	Check -p 5173:5173, and confirm host firewall and cloud security group rules

Security Recommendation

Expose only the unified service entry point, and restrict access through a reverse proxy, TLS, authentication, firewall, or security group. Browser and API clients should both use this entry point. Do not expose internal backend ports directly.

Verification

After changing remote access settings, do not stop at confirming that the page opens. Continue verifying that new chats, model tests, and task execution return correctly.