# Environment Variables

> Environment variables Flowly reads at startup, with their defaults. Most users never need these — config.json covers the common cases.

Source: https://useflowlyapp.com/en/docs/reference/environment-variables
Language: en

Flowly is configured mainly through `~/.flowly/config.json`. The environment variables below override specific behaviors and are handy for wrapper scripts, CI, and headless setups.

## Profiles & home

| Variable | Default | What it does |
|---|---|---|
| `FLOWLY_HOME` | `~/.flowly` | The profile/home directory — where config, sessions, credentials, skills, and databases live. A non-default home also carries its own machine identity, so signing in from it registers a separate `<machine>-dev` server instead of taking over your main one. |
| `FLOWLY_PROFILE` | `default` | Profile name, for wrapper scripts. Resolution order: `-p` flag → `FLOWLY_PROFILE` → `~/.flowly/active_profile` → `default`. |

## Sandbox & execution

| Variable | Default | What it does |
|---|---|---|
| `FLOWLY_SANDBOX` | on | Set to `0` / `false` / `off` / `no` to disable the OS sandbox (macOS `sandbox-exec` / Linux `bwrap`). |
| `FLOWLY_SANDBOX_WRAPPED` | — | Internal recursion guard set when re-execing under the sandbox. Also tells Flowly the OS keychain is out of reach (the profile hides `~/Library/Keychains`), so credentials go to `0600` files instead of raising a keychain prompt. **Do not set this yourself.** |
| `FLOWLY_CWD` | — | Override the runtime working directory for shell/exec and Codex. |
| `FLOWLY_BASH_PATH` | — | Path to the `bash` binary used for command execution. |

## Agent & LLM

| Variable | Default | What it does |
|---|---|---|
| `FLOWLY_LLM_TIMEOUT_SECONDS` | `120` | Timeout for a non-streaming LLM call. |
| `FLOWLY_LLM_STREAM_TIMEOUT_SECONDS` | `120` | Timeout for a streaming LLM call. |
| `FLOWLY_CLAUDE_CACHE_TTL` | `1h` | TTL for the Anthropic prompt cache (Claude models). |
| `FLOWLY_PLAN_PERSIST` | on | Set to `0` / `false` / `off` / `no` to keep [plan mode](https://useflowlyapp.com/en/docs/features/plan-mode) state (plans + the standing-mode flag) in memory only, instead of writing it to `<FLOWLY_HOME>/plan-mode`. |

## Cron

| Variable | Default | What it does |
|---|---|---|
| `FLOWLY_CRON_TIMEOUT` | `600` | Per-job watchdog timeout, in seconds. |
| `FLOWLY_CRON_RETENTION_DAYS` | `30` | How long per-run output archives are kept. |

## Media

Generated media (image generation, etc.) is written to `<FLOWLY_HOME>/media`. The gateway prunes it at start so it can't fill the disk; recent files are kept so chat-history re-fetch still works.

| Variable | Default | What it does |
|---|---|---|
| `FLOWLY_MEDIA_RETENTION_DAYS` | `30` | Delete generated media older than this many days at gateway start. `-1` disables the age cap. |
| `FLOWLY_MEDIA_MAX_SIZE_MB` | `500` | If `<FLOWLY_HOME>/media` is still larger than this, delete the oldest files until under cap. `0` disables the size cap. |

## Skills & plugins

| Variable | Default | What it does |
|---|---|---|
| `FLOWLY_HUB_REGISTRY` | `https://useflowlyapp.com` | Skill hub registry base URL. |
| `FLOWLY_ENABLE_PROJECT_PLUGINS` | off | Set to `1` to load project-local plugins from the working directory. |

## Provider & account

| Variable | Default | What it does |
|---|---|---|
| `FLOWLY_API_BASE` | `https://useflowlyapp.com` | Base URL for the hosted Flowly API / relay. |
| `FLOWLY_SERVER_ID` | — | Relay server id (set during `flowly login`). |
| `FLOWLY_USER_AGENT` | `FlowlyBot/1.0` | HTTP User-Agent for outbound requests. |
| `FLOWLY_XAI_OAUTH_MODEL` | `grok-4.20-reasoning` | Model used with an xAI OAuth subscription. |
| `FLOWLY_X_SEARCH_MODEL` | `grok-4.20-reasoning` | Model used by the `x_search` tool. |
| `FLOWLY_CODEX_MODEL` | `gpt-5.6-sol` | Default model used with a ChatGPT subscription (`openai_codex` provider). |
| `FLOWLY_CODEX_INSTRUCTIONS` | — | Overrides the `instructions` field sent to the ChatGPT Codex backend, replacing your system prompt wholesale. |
| `FLOWLY_AUTH_DEBUG` | off | Set to `1` for verbose auth logging. |
| `CODEX_HOME` | `~/.codex` | State directory for the Codex CLI subprocess (Codex runtime) — also where the `openai_codex` provider looks for a `codex login` session as a fallback credential source. |

## Tool credentials

These let tools pick up credentials from the environment instead of `config.json`:

| Variable | Used by |
|---|---|
| `BRAVE_API_KEY` | `web_search` |
| `GROQ_API_KEY` | Voice STT (Groq Whisper) |
| `TRELLO_API_KEY`, `TRELLO_TOKEN` | `trello` |
| `XAI_API_KEY` | `x_search` (fallback when no OAuth subscription) |
| `XAI_BASE_URL` | `x_search` (overrides the xAI API base URL) |
| `GITHUB_PERSONAL_ACCESS_TOKEN` | GitHub MCP server installed from the catalog |
| `GITHUB_TOKEN` | GitHub-oriented skills and repository watchers |
| `EDITOR` | Opening the TUI draft with `Ctrl+E` |

## MCP bridges

| Variable | Used by |
|---|---|
| `FLOWLY_MCP_ENDPOINT` | `flowly mcp connect`: the exact remote HTTPS MCP URL, or local loopback HTTP URL |
| `FLOWLY_MCP_ACCESS_KEY` | `flowly mcp connect`: the scoped, expiring key created in Desktop |
| `FLOWLY_MCP_TOKEN` | Default bearer-token variable for `flowly mcp serve --transport http`; override its name with `--auth-token-env` |

These keys serve different bridges. A scoped access key is not the gateway administration token. See [MCP](https://useflowlyapp.com/en/docs/features/mcp#let-another-agent-use-flowly) for configuration and permission details.

SSH-based owner management does not use these bridge variables. Its
`/api/mcp/manage` requests authenticate with the configured gateway token
(`gateway.token`), inside the client's verified SSH channel. There is no SSH
password to set in the runtime environment for this feature; enter SSH details
in a supported client. See [Remote MCP setup](https://useflowlyapp.com/en/docs/using-flowly/remote-mcp).

## TUI

| Variable | Default | What it does |
|---|---|---|
| `FLOWLY_TUI_THEME` | `flowly` | Default TUI theme. |
| `FLOWLY_NO_GATEWAY_AUTOSTART` | — | Set to `1` to stop bare `flowly` from starting the gateway when none is running. Without it, `flowly` starts an installed service, or installs and starts one, before opening the chat. Never fires for a non-loopback `--host`, for a `--port` other than the configured one, or outside an interactive terminal. |
| `FLOWLY_BROWSER_PLAN_ENABLED` | `1` | Toggles the `browser_plan` tool. |
| `FLOWLY_BROWSER_PLAN_PERSIST` | — | Controls browser-plan persistence. |

## Install script

Read only by the install script (`install.sh` / `install.ps1`), not by the
running agent. They tune the git-checkout install; see [Installation](https://useflowlyapp.com/en/docs/getting-started/installation).

| Variable | Default | What it does |
|---|---|---|
| `FLOWLY_REPO_URL` | GitHub repo | Git remote the installer clones. |
| `FLOWLY_BRANCH` | `main` | Branch to track (and that `flowly update` pulls). |
| `FLOWLY_SRC` | `~/.local/share/flowly/repo` | Where the checkout is cloned. |
| `FLOWLY_VENV` | `~/.local/share/flowly/venv` | Where the virtualenv is built (kept outside the checkout). |
| `FLOWLY_PYTHON` | `3.12` | Python version uv provisions for the venv. |
| `FLOWLY_SKIP_SYSTEM_DEPS` | `0` | Skip the optional `ffmpeg` / `ripgrep` install. |
| `FLOWLY_SKIP_BOOTSTRAP` | `0` | Skip first-run onboarding. |
| `FLOWLY_NO_PATH_UPDATE` | `0` | Don't edit shell profiles for PATH. |

## Related

- [Configuration](https://useflowlyapp.com/en/docs/using-flowly/configuration)
- [CLI commands](https://useflowlyapp.com/en/docs/reference/cli-commands)
- [Sandbox & approvals](https://useflowlyapp.com/en/docs/using-flowly/sandbox-and-approvals)