Self-hosting

Flowly runs entirely on your own machine with your own LLM keys. Nothing in this repo needs a Flowly account. This guide covers running it on a laptop, a Mac mini, or a headless VPS, and links to the deeper pages for each step.

For what's open-source vs. cloud-only, see Open source vs. Desktop & Cloud.

1. Install

# One command — sets up uv, Python, git, and a Flowly git checkout that
# `flowly update` keeps current with `git pull`
curl -fsSL https://useflowlyapp.com/install.sh | bash

The checkout and its virtualenv live under ~/.local/share/flowly/ (repo/ + venv/); everything Flowly stores lives under ~/.flowly/ (config, workspace, plugins, skills, memory, session db). See Installation and File layout.

2. Bring your own key

Pick any provider — OpenRouter, Anthropic, OpenAI, Gemini, Groq, xAI/Grok, Zhipu, Sakana, or any OpenAI-compatible local model (Ollama, LM Studio, vLLM). Those eight slugs are what setup byok accepts; subscription sign-ins (ChatGPT via Codex, Grok, GLM Coding Plan) have their own commands — see Providers and models:

flowly setup byok openrouter --key sk-or-...
# or run the full wizard (provider + channels + tools)
flowly setup

This writes ~/.flowly/config.json. Keys there are camelCase:

{
  "providers": {
    "active": "openrouter",
    "openrouter": { "apiKey": "sk-or-..." }
  }
}

providers.active pins the default. Leave it "" and Flowly cascades through whatever you've configured so it always has a working model. See Providers & models.

3. Run it

Foreground (terminal):

flowly                 # terminal UI
flowly gateway         # just the gateway daemon, no TUI

As a background service (survives reboots and terminal close):

flowly service install --start     # launchd (macOS) / systemd (Linux) / Task Scheduler (Windows)
flowly service status
flowly service logs                # tail the logs
flowly restart
flowly service uninstall

The gateway listens on 127.0.0.1:18790 by default — loopback only, reachable only from the same machine. See Running as a service.

4. Headless / VPS

Run Flowly on a VPS or Mac mini and talk to it from Telegram, Discord, etc. — or from the desktop/mobile apps over the network.

# 1. Install + configure a provider (steps 1–2 above)
# 2. Initialize the workspace without prompts (good for scripts/cloud-init)
flowly bootstrap

# 3a. Local-only + a messaging channel (recommended, no open ports):
flowly setup channels          # add Telegram/Discord/Slack/…
flowly service install --start

# 3b. Expose the gateway to network clients (e.g. the desktop app):
flowly service install --start --host 0.0.0.0 --port 18790 --token "$(openssl rand -hex 24)"

If you bind to a non-loopback address, secure it:

Always set a --token; clients must present it to connect.
Prefer an SSH tunnel or a TLS reverse proxy over exposing 0.0.0.0 directly to the internet. Restrict the port with a firewall / security group.
The agent has shell and filesystem access on the host — treat gateway access as host access. See the repo's SECURITY.md.

MCP management from a remote app

An updated gateway provides POST /api/mcp/manage for verified SSH-capable clients. Keep the gateway as a direct remote gateway; this does not require a relay or Firestore registration. The client connects through SSH to the remote loopback gateway port, then authenticates with the gateway token. The Flowly runtime does not receive or store your SSH password.

This is a separate management path: it does not encrypt the ordinary chat or media connection, publish an external-agent MCP URL, or configure TLS for you. App support must also be present; updating only the runtime is not enough. Follow Remote MCP setup before connecting external services.

5. Sandbox

Shell/exec tooling runs inside an OS sandbox by default: sandbox-exec on macOS, bwrap (bubblewrap) on Linux. On Linux, install bubblewrap so the sandbox is active:

sudo apt install bubblewrap      # Debian/Ubuntu;  dnf install bubblewrap on Fedora

It denies access to things like ~/.ssh, ~/.aws, and keychains while allowing ~/.flowly, your home dir, and /tmp. You can disable it (not recommended) with:

FLOWLY_SANDBOX=0 flowly

Windows has no sandbox yet. Full details in Sandbox & approvals.

6. Profiles & isolation

Run multiple independent Flowly instances (e.g. a test bot and a real one) without sharing state:

flowly -p testbot setup        # named profile → ~/.flowly/profiles/testbot/
FLOWLY_HOME=/srv/flowly flowly gateway   # fully custom home dir

FLOWLY_HOME — override the whole state directory (default ~/.flowly).
FLOWLY_PROFILE / -p <name> — select a named profile under ~/.flowly/.
FLOWLY_SANDBOX=0 — disable the exec sandbox.

See Profiles and Environment variables.

7. Health check

flowly doctor          # diagnose config + runtime; --fix to auto-repair
flowly status

If something's off, flowly doctor is the first stop — it checks provider keys, the gateway, the service definition, and workspace layout. See Troubleshooting.

Sandbox And Approvals

Service