Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/GuaiZai233/FrostAgent/llms.txt

Use this file to discover all available pages before exploring further.

FrostAgent compiles to a single self-contained binary that starts two network listeners: an HTTP server for the management panel and ConnectRPC APIs, and a WebSocket server for the OneBot v11 protocol. This page walks through building the binary, configuring it from environment variables, running it as a managed service, and connecting it to a OneBot client.

​
Building the binary

FrostAgent requires Go 1.25.3 or later, as declared in go.mod. Build the production binary with: 
go build -o frostagent ./cmd/app
The output is a single statically linked binary named frostagent in the current directory. The CI workflow in .github/workflows/go.yml performs a full build, vet, and test run on every push to main — run those same steps locally before deploying: 
go mod download
go vet ./...
go test ./... -v
go build -o frostagent ./cmd/app

​
Environment configuration

FrostAgent reads configuration from environment variables. On startup, the godotenv library checks for a .env file in the working directory and loads it automatically. If the file is absent, the process continues with whatever variables are already present in the environment — no error is raised. Copy the provided template and fill in your values: 
cp .env.example .env
In production you can use either approach:
  • .env file — place it in the same directory as the frostagent binary and it will be loaded at startup.
  • System environment variables — export them via your process manager (systemd, Docker, Kubernetes). These take precedence if both a .env file and a system variable are set for the same key.

​
Required environment variables

At minimum, three variables must be set before the engine can make any LLM calls:
VariableDescriptionExample
UPSTREAM_ENDPOINTBase URL of the OpenAI-compatible LLM APIhttps://api.openai.com/v1
UPSTREAM_API_KEYBearer token for the upstream APIsk-...
MODEL_NAMEModel identifier to request from the upstream APIgpt-4o
All other variables have built-in defaults and are optional:
VariableDefaultDescription
LISTEN_ADDR:8080Bind address for the HTTP management server
WS_LISTEN_ADDR0.0.0.0:1234Bind address for the OneBot WebSocket server
SYSTEM_PROMPT你是一个乐于助人的助手。System prompt prepended to every conversation
VISUAL_MODEL_NAME(same as MODEL_NAME)Override model used for vision tasks
MAX_CONTEXT_MESSAGES20Maximum conversation messages retained per session (including system)
MAX_CONTEXT_CHARS24000Approximate character limit for context before trimming
WS_ALLOWED_ORIGINS(empty, all origins allowed)Comma-separated list of permitted WebSocket origins
ENABLE_AT_IN_GROUP_MSGtruePrefix group chat replies with an @mention
For the full variable reference see Configuration.

​
Service ports

FrostAgent opens two TCP listeners:

HTTP — Management + ConnectRPC

Default: :8080Serves the management panel SPA at / and the ConnectRPC endpoints at /frostagent.v1.*. Override with LISTEN_ADDR.

WebSocket — OneBot v11

Default: 0.0.0.0:1234Accepts OneBot WebSocket connections at /ws/frostagent. Override with WS_LISTEN_ADDR.

​
Running as a systemd service

Create a unit file at /etc/systemd/system/frostagent.service: 
[Unit]
Description=FrostAgent AI Agent Service
After=network.target
Wants=network-online.target

[Service]
Type=simple
User=frostagent
Group=frostagent
WorkingDirectory=/opt/frostagent
ExecStart=/opt/frostagent/frostagent
EnvironmentFile=/opt/frostagent/.env
Restart=on-failure
RestartSec=5s
StandardOutput=journal
StandardError=journal
SyslogIdentifier=frostagent

# Resource limits
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
Enable and start the service: 
# Create a dedicated user
sudo useradd --system --no-create-home --shell /usr/sbin/nologin frostagent

# Copy the binary and config
sudo mkdir -p /opt/frostagent
sudo cp frostagent /opt/frostagent/
sudo cp .env       /opt/frostagent/
sudo chown -R frostagent:frostagent /opt/frostagent

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable --now frostagent

# Tail logs
sudo journalctl -u frostagent -f

​
Running with Docker

Use a multi-stage build to keep the image small: 
# ── Stage 1: build ──────────────────────────────────────────────
FROM golang:1.25-alpine AS builder

WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download

COPY . .
RUN go build -o /frostagent ./cmd/app

# ── Stage 2: runtime ────────────────────────────────────────────
FROM alpine:3.19

RUN apk add --no-cache ca-certificates tzdata

WORKDIR /app
COPY --from=builder /frostagent /app/frostagent

# Expose management HTTP and OneBot WebSocket ports
EXPOSE 8080 1234

ENTRYPOINT ["/app/frostagent"]
Build and run, passing configuration as environment variables: 
docker build -t frostagent:latest .

docker run -d \
  --name frostagent \
  --restart unless-stopped \
  -p 8080:8080 \
  -p 1234:1234 \
  -e UPSTREAM_ENDPOINT="https://api.openai.com/v1" \
  -e UPSTREAM_API_KEY="sk-..." \
  -e MODEL_NAME="gpt-4o" \
  frostagent:latest
Alternatively, mount a .env file into the container: 
docker run -d \
  --name frostagent \
  --restart unless-stopped \
  -p 8080:8080 \
  -p 1234:1234 \
  -v /opt/frostagent/.env:/app/.env:ro \
  frostagent:latest

​
CI/CD

The repository ships with a GitHub Actions workflow at .github/workflows/go.yml that runs on every push and pull request to main. It:
  1. Checks out the code and installs Go 1.25.
  2. Downloads module dependencies (go mod download).
  3. Installs the buf protobuf toolchain and regenerates proto code.
  4. Builds all packages (go build ./...).
  5. Runs go vet and the full test suite (go test ./... -v).
Integrate a deployment step after the Test step to automatically ship a passing build to your server or container registry.

​
Connecting a OneBot client

After FrostAgent is running, point your OneBot v11 client at the WebSocket endpoint. The path is always /ws/frostagent: 
ws://<your-host>:1234/ws/frostagent
Compatible clients include go-cqhttp, Lagrange.Core, and NapCat. In each client’s configuration, set the reverse WebSocket URL (also called the “universal server” or “正向 WebSocket” URL) to the address above. Once connected, the client forwards incoming messages to FrostAgent and the engine replies through the same socket using the OneBot v11 send-group-message and send-private-message actions.

​
Management panel

After startup, FrostAgent logs the local URL of the management panel: 
📍 管理面板: http://localhost:8080
Open that address in a browser to access the dashboard, inspect live logs, view bot status, and adjust settings. The same port also serves the ConnectRPC endpoints used by the frontend SPA, so no separate API port is needed.
Set WS_ALLOWED_ORIGINS to a comma-separated list of permitted origins whenever the management frontend and the OneBot client are served from different domains or hosts. Leaving it empty permits connections from any origin, which is convenient for local development but is a security risk in production. Example: WS_ALLOWED_ORIGINS=https://panel.example.com,https://bot.example.com.

Build docs developers (and LLMs) love

Get started for freeTalk to us