3.5 Configuration & File Storage
Think about the directories in two groups:
- The user directory
~/.flocks/, which stores user information, runtime configuration, plugins, and business artifacts. Updating source code or upgrading the program usually does not overwrite this directory. - The source directory
flocks/, which stores program code, frontend code, scripts, and tests. On Windows, read~as%USERPROFILE%.
User directory ~/.flocks/
| Directory | Purpose |
|---|---|
~/.flocks/config/ | Configuration directory. Stores runtime configuration and sensitive credentials such as flocks.json and .secret.json. |
~/.flocks/data/ | Runtime data directory. Stores databases, session records, memory, media cache, Workflow service data, sandbox state, and other system data. |
~/.flocks/logs/ | Log directory. Stores server-side, task, tool-call, channel, and troubleshooting logs. |
~/.flocks/workspace/ | User business Workspace. Stores uploaded files, output results, knowledge materials, channel state, and other user-managed artifacts. |
~/.flocks/plugins/ | User-level plugin directory. Stores Agents, Skills, Workflows, Tools, Tasks, MCP, custom pages, and other capabilities installed in the current user environment. |
~/.flocks/flockshub/ | Local Flocks Hub directory. Stores bundled plugin indexes, category information, and plugin content pending installation. |
~/.flocks/browser/ | Browser automation runtime directory. Stores browser control, temporary state, and related runtime files. |
~/.flocks/version/ | Version and upgrade backup directory. Stores current version markers, upgrade backups, and rollback-related files. |
~/.flocks/flockspro/ | Flocks Pro data directory. Stores Pro authorization, License, and other enterprise-edition local files. |
~/.flocks/run/ | Runtime state directory. Stores startup state, component installation markers, and state files needed while processes are running. |
~/.flocks/audit/ | Audit directory. Stores audit records for local sensitive operations, such as SSH command audit logs. |
~/.flocks/workflow/ | Legacy Workflow compatibility directory. Historical Workflows may still be scanned. New Workflows should prefer ~/.flocks/plugins/. |
~/.flocks/mcp/ | Legacy MCP dependency directory. Historical local MCP installations may use it. New configuration should prefer ~/.flocks/plugins/ and ~/.flocks/config/. |
Source directory flocks/
| Directory | Purpose |
|---|---|
flocks/flocks/ | Main Python program directory. Contains core implementations for the server, Agent, Workflow, Tool, Workspace, channels, configuration, and more. |
flocks/webui/ | WebUI frontend directory. Contains pages, components, static assets, and frontend build configuration. |
flocks/tui/ | TUI terminal interface directory. |
flocks/scripts/ | Scripts for installation, startup, builds, and helper processing. |
flocks/tests/ | Test directory. Contains unit tests, integration tests, and module-level tests. |
flocks/assets/ | Static assets for project documentation or presentation. |
flocks/docker/ | Docker-related files. |
flocks/packaging/ | Packaging and release directory, such as Windows installer files. |
flocks/.flocks/ | Repository-bundled examples and default plugin directory. Provides sample configuration, bundled plugins, and development-time default content. It is not the same as ~/.flocks/ under the user's home directory. |
flocks/README.md / flocks/README_zh.md | Entry points for project installation, startup, and usage instructions. |