Flocks: an agentic SecOps platform that ships a CLI, a WebUI and an HTTP API in one Python service

The gap Flocks tries to fill between a chat agent and a SecOps console

Most agent frameworks stop at the loop: prompt, tool call, response. Flocks wraps that loop in the operational furniture a security team already expects, a long-running service, a browser interface, a terminal interface, and an HTTP API on the same origin. The README describes it as an AI-driven SecOps platform built with Python, featuring multi-agent collaboration, an HTTP API server, and a modern terminal user interface. The target user is someone who wants to run agent-assisted security work on their own machine or their own container host rather than inside a vendor's cloud. That is the whole pitch as far as the repository states it. There is no threat-model diagram, no detection pipeline description, and no list of the security data sources it can read. The docs badge points to agentflocks.github.io/flocks-docs, so the operational detail lives outside the repository. Treat the README as an installation guide, not as a description of what the agents actually do.

Three agent roles, a tool set, and a FastAPI service in front of both

The feature list names three agent types: build, plan and general. The README does not define what distinguishes them, so the only safe reading is that Flocks ships more than one configured agent persona and lets them collaborate. Around those agents sits a tool set listed as bash, file operations, code search and LSP integration. Language Server Protocol support is the unusual entry here. It means an agent can ask a language server for definitions, references or diagnostics instead of grepping, which matters when an agent is reasoning about a codebase rather than a log file. Model support is described as Anthropic, OpenAI, Google and others, and MCP is supported, so external tool servers can be attached through the Model Context Protocol rather than only through the built-in tools. The architecture implied by the install section is a single service process that serves the WebUI and the API together. The README states that API requests use the same-origin /api path, keeping browser cookies and SSE on a single origin. That is a deliberate design choice and it has consequences for how you deploy the thing, which the remote access section makes explicit.

Installing Flocks: three paths, one prerequisite list, and a version pin on npm

The system requirements are uv, Node.js with npm 22 or newer, agent-browser, and optionally bun for the TUI. The install scripts attempt to satisfy these automatically, but the README warns that if automatic npm installation fails you must install npm manually at version 22 or newer. There are three installation routes. The one-command route on macOS and Linux is curl -fsSL https://raw.githubusercontent.com/AgentFlocks/flocks/main/install.sh | bash, which creates ./flocks under the current directory. Windows PowerShell uses powershell -c "irm https://raw.githubusercontent.com/AgentFlocks/flocks/main/install.ps1 | iex". The source route clones the repository and runs sh ./scripts/install.sh or powershell -ep Bypass -File .\scripts\install.ps1. The third route is a Windows x64 Inno Setup wizard distributed as FlocksSetup-<tag>.exe on the releases page, marked BETA, with a note that you should open a new terminal after installation so PATH changes take effect before running flocks start. Piping a remote script into a shell is a trust decision, and the repository offers the clone-and-inspect alternative for anyone who does not want to make it. The README also points users in mainland China to the Chinese README for a mirror-accelerated install, and documents a uv mirror configuration using pypi.tuna.tsinghua.edu.cn in ~/.config/uv/uv.toml.

Running it: the flocks subcommands and the flags that change exposure

Once installed, the CLI is the control surface. flocks start launches the backend and WebUI together in daemon mode and builds the WebUI before launch by default. flocks status, flocks logs, flocks restart and flocks stop cover the rest of the lifecycle, and flocks restart is described as the explicit full restart when you want one. The default service address is http://127.0.0.1:5173 for the WebUI. Remote access is configured with flocks start --host <ip>, and the FAQ shows flocks start --host 0.0.0.0 for the general case, with a note that if remote access from a virtual machine fails you should specify the virtual machine's IP instead. There is a second, more granular form: FLOCKS_WEBUI_DIRECT_BACKEND_URLS=1 flocks start --server-host 0.0.0.0 --webui-host 0.0.0.0. The README frames that environment variable as something to enable only when you explicitly need direct browser-to-backend URLs, which tells you the default same-origin arrangement is the intended one and the split-host mode is the exception. For Docker, the image is ghcr.io/agentflocks/flocks:latest, run with -p 5173:5173, --shm-size 4gb, and a bind mount of the host's ~/.flocks into /home/flocks/.flocks. The README is explicit that EXPOSE in the image only documents ports and that you still need the -p flag to reach the service from the host browser.

The Docker trade-off and the file ownership trap

The README states plainly that in the Docker installation the agent-browser headed mode is currently unavailable, and repeats the caveat in the deployment table. If your workflow depends on a visible browser session driven by the agent, the container path is the wrong one and you should use a PC install instead. The second Docker issue is permissions. The mount can fail to be writable by the container process, and the README gives two remedies: append :Z to the volume specification, or inspect the image's user with docker run --rm --entrypoint id ghcr.io/agentflocks/flocks, which the README illustrates returning uid=1001(flocks) gid=1001(flocks), then run sudo chown -R 1001:1001 ~/.flocks on the host. That is a real operational step, not an edge case, and it is the kind of thing that silently breaks first-run state if you skip it. For users in mainland China the README lists several GHCR mirrors, including ghcr.1ms.run, ghcr.dockerproxy.net, docker.gh-proxy.com, ghcr.milu.moe and ghcr.nju.edu.cn. Note that these are third-party registry proxies. Pulling a security tool's image through an unaffiliated mirror is a supply-chain decision you are making implicitly, and the README does not discuss that trade-off.

What the README does not tell you about SecOps work

This is the largest limitation in the supplied material. Flocks is labelled a SecOps platform, yet nothing in the README describes case management, alert ingestion, detection rules, evidence handling, or how findings are recorded. The features are agent capabilities and interfaces. If you need to know whether Flocks can ingest a SIEM export, correlate it with asset inventory, or produce an auditable incident record, the README will not answer you. The docs site linked from the badge is where that would have to live, and it is outside the repository. There is a second, smaller gap: the three agent roles are named but not defined, so you cannot tell from the README whether build, plan and general are distinct system prompts, distinct tool permissions, or distinct orchestration patterns. Anyone evaluating Flocks for a regulated environment should treat the repository as an installer and read the docs before assuming the platform covers a workflow. The Apache-2.0 licence is stated in the repository, which removes licence cost as a blocker, but it does not tell you anything about the project's operational maturity.

How Flocks differs from wiring an agent framework into your own service

The obvious alternative is to take a general agent framework, define your own tools, and put your own FastAPI service in front of it. That path gives you full control over the API surface and the deployment topology, and it is the right choice if your SecOps workflow has requirements the Flocks agent roles cannot express. The difference in approach is packaging. Flocks arrives with the service, the WebUI, the TUI, the CLI lifecycle commands and the same-origin /api convention already assembled, so the first hour is installation rather than architecture. A hand-rolled stack gives you nothing until you have written the tool layer and the session handling. The trade is that Flocks's opinions are fixed at the points the README documents: the WebUI and API share a port and origin by default, the daemon lifecycle is managed by flocks start and flocks stop, and the container image has a known headed-browser limitation. If any of those constraints conflict with your environment, you are working against the tool rather than with it. If they match, you skip a substantial amount of scaffolding.

Release cadence, upgrade cost and who should wait

The release tags are date-based, v2026.8.12, v2026.8.17 and v2026.9.9, with roughly weekly to fortnightly spacing between the three most recent entries. Date-versioned releases make it easy to see how far behind you are, and the flocks restart command plus the daemon model means an upgrade is a stop, replace and start rather than a live migration. What the README does not describe is state migration. Session and context management is listed as a feature, and the Docker instructions mount ~/.flocks as the persistent state directory, so that directory is where your sessions live. Nothing in the supplied material says whether a release can read state written by an older one. Before upgrading a deployment that holds work you care about, copy ~/.flocks aside first. The Apache-2.0 licence permits commercial use and modification, and the repository carries a LICENSE.txt; that is the extent of what can be said here, and it is not legal advice. If your team needs a written description of how agent sessions are persisted before you can run this in production, that description is not in the README, and you should look for it in the docs site or in the code under the session management path before committing.

Editorial conclusion

Adopt Flocks if you want a self-hosted agent runtime with a browser UI and a same-origin /api surface you can put behind a reverse proxy, and you are willing to read the separate docs site for the SecOps specifics. Do not adopt it if you need headed agent-browser automation inside Docker, or if you expect the README to explain how detection or triage is actually performed. Verify first that the agent-browser binary and npm 22+ are present on the target host, that port 5173 is free, and that the container user's uid owns ~/.flocks before you mount it.

Official sources

1. AgentFlocks/flocks on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases