Configuration

File path

<FLOWLY_HOME>/config.json

FLOWLY_HOME defaults to ~/.flowly. The file is stored with owner-only (0600) permissions because it holds API keys.

Sibling files in the same directory:

• config.json.bak — a self-heal backup, seeded from the last good config.
• config.json.broken-<unix-ts> — a corrupted config moved aside during recovery.

Profiles

A profile is an isolated FLOWLY_HOME with its own config, sessions, workspace, and credentials. The active profile is resolved in this order:

1. -p / --profile <name> CLI flag
2. FLOWLY_PROFILE environment variable
3. ~/.flowly/active_profile sticky pointer file
4. "default"

The default profile is ~/.flowly. A named profile coder lives at ~/.flowly/profiles/coder. Profile names must match ^[a-z0-9][a-z0-9_-]{0,63}$; the names flowly, default, test, tmp, root, and sudo are reserved. See Environment variables.

Self-healing loader

The loader is resilient by design:

1. It parses config.json. If valid, it's used (and a .bak is seeded if missing).
2. If parsing or validation fails, it tries config.json.bak. If that's good, the broken file is renamed config.json.broken-<ts> and the backup is restored.
3. If both fail, Flowly falls back to in-code defaults so the agent still boots.

Top-level keys

agents

agents.defaults — applied to the main agent:

agents.defaults.compaction — see Sessions:

agents.defaults.goals — see Standing goals:

agents.defaults.heartbeat:

agents.defaults.memorySearch:

agents.defaults.memoryDreaming — cross-session "dreaming" + autonomous consolidation (see Memory):

agents.agents (per-agent map) — name, provider ("anthropic" default | "openai" | "flowly"), model="", workingDirectory="", persona="". agents.teams (per-team map) — name, agents=[], leaderAgent="".

channels

Channels are off by default. See Channels overview.

providers

BYOK provider slots — each with apiKey="", apiBase=null, fallbackKeys=[]: anthropic, openai, openrouter, zhipu, sakana, vllm, gemini, groq, xai.

When active="", the cascade picks the first usable provider in priority order:

openrouter → anthropic → openai → openai_codex → zai_coding → xai
           → xai_oauth → gemini → groq → zhipu → sakana → vllm

Setting a provider explicitly (/provider, flowly setup, or active in this file) skips the cascade entirely — worth doing if more than one credential is present, so the choice is yours rather than the order's. See Providers and models.

gateway

The dedicated POST /api/mcp/manage route always requires a valid, non-empty gateway token, including through an SSH loopback forward. An empty token may retain legacy local behavior on other routes; it never unlocks MCP management. The token is not an external-agent MCP access key. SSH passwords and host-key verification are client responsibilities, not gateway or mcpServers settings. See Remote MCP setup and the management API.

tools

See Sandbox and approvals for execution policy.

integrations

audit

Audit records are written as daily JSONL files under <FLOWLY_HOME>/audit/. These keys control retention only.

plugins

Bundled plugins load by default unless listed in disabled. User plugins under $FLOWLY_HOME/plugins/<name>/ load only if listed in enabled. disabled overrides enabled.

mcpServers

A map of server name → server config. Each server uses either local stdio (command, args, env) or HTTP/SSE (url, headers). Common defaults include enabled=true, transport="auto", protocol="auto", timeout=120, and connectTimeout=60. HTTP connections can use native OAuth with auth="oauth"; TLS, mTLS, scope, trust, elicitation, bounded sampling, diagnostics, pagination, binary-content, concurrency, and supervised lifecycle controls are available per server.

Tool permissions use tools.mode: all, selected, none, or legacy. selected with an empty include list means no tools. legacy preserves older hand-written behavior, where a non-empty include list wins, otherwise exclude applies, otherwise all tools load. Resource and prompt utilities are separately controlled by tools.resources and tools.prompts.

In all and selected modes, exclude still removes matching tool names. all includes future discoveries; use selected to pin exact tool names. App confirmation of none disables the connection and clears resource/prompt access. Configuration publication and live application are separate steps: an apply failure can leave the new settings saved, so inspect the reported runtime state and retry.

App-managed setup writes an internal oauthCredentialId only after OAuth, connection testing, discovery, and explicit permission confirmation succeed. Do not copy that identifier between server entries. Server names and env/headers keys are preserved verbatim by the loader. See the complete MCP configuration reference for every key, default, bound, and lifecycle behavior.

Example

A minimal config.json after setting an Anthropic key and a Telegram bot:

{
  "providers": {
    "active": "anthropic",
    "anthropic": { "apiKey": "sk-ant-..." }
  },
  "agents": {
    "defaults": {
      "model": "claude-sonnet-4-5",
      "persona": "default"
    }
  },
  "channels": {
    "telegram": { "enabled": true, "token": "123:ABC", "dmPolicy": "pairing" }
  },
  "gateway": { "host": "127.0.0.1", "port": 18790 }
}

Related

• Sessions
• Personas
• Running as a service
• Providers and models
• Sandbox and approvals
• Channels overview
• Setup wizard
• CLI commands
• Environment variables