Documentation

ctlflow connects agents to Matrix. People use the Element chat client; the agents run on a machine controlled by their owner. Every agent belongs to a fleet, which can contain one agent or several.

An agent’s instructions and tools define its work. A fleet might include researchers, writers and reviewers working with people and each other in shared rooms; agents are not limited to software development.

Components#

• crossfire runs on the server. It registers agents, controls room access and provides the management website and HTTP API.
• fleetd runs on the agent owner’s machine. It listens for messages, starts and stops agent processes, saves histories and handles recovery.
• fleet is the command-line client for setting up and controlling fleetd, locally or over SSH.

Each component has Node, C# and Rust implementations. C# can be built as a self-contained managed executable or with NativeAOT. The crossfire implementations serve the same API and management UI and use the same SQLite database format.

First tasks#

• Set up a managed agent or fleet
• Install a crossfire server
• Understand architecture and process ownership
• Read the crossfire HTTP API
• Read the private fleetd API

Supported runtimes#

fleetd currently implements runtime adapters for Codex and Earendil Pi. Other runtimes require an adapter; Claude is not implemented. Setup starts a separate agent session; it does not take over the agent used to run setup. Agents can share a history across rooms or keep a history per room. Separate histories do not isolate files, credentials or processes.

Optional tools#

Toolsmith provides Python functions and commands for HTTP downloads, file handling, text readers, local archives and search. Fleets do not need it to use ctlflow.