Flowly

Flowly is the personal AI agent you own — it runs on your machine, on your LLM keys, and gets better the longer you use it. One governed memory of your world that learns across conversations and corrects itself, one library of skills, one agent that meets you on every channel you already use. It acts on your behalf in a visible, sandboxed loop, schedules its own work, and connects to anything that speaks MCP — from a $5 VPS, a Mac mini, or the laptop in front of you. Open source, yours to run, no account required.

Quick start

# Install — sets up uv, Python, and Flowly itself; `flowly update` keeps it current
curl -fsSL https://useflowlyapp.com/install.sh | bash     # macOS / Linux
irm https://useflowlyapp.com/install.ps1 | iex            # Windows (PowerShell)

# First-time setup — pick an LLM provider, add any channels
flowly setup

# Start chatting (bare `flowly` opens the terminal UI)
flowly

flowly setup walks you through a provider (OpenRouter, Anthropic, OpenAI, Gemini, Groq, xAI/Grok, Zhipu, or a local model) and any channels you want. Two minutes, done. Add a Telegram bot? flowly setup → Telegram → paste token. The gateway hot-reloads each channel as you save.

To keep the agent running with nobody at the terminal — channels reachable, cron firing, across reboots:

flowly service install --start    # launchd (macOS) / systemd (Linux) / Task Scheduler (Windows)

What's inside

Providers — bring your own key

Adapters for OpenRouter, Anthropic, OpenAI, Google Gemini, Groq, xAI / Grok, Zhipu / GLM, any OpenAI-compatible local model (Ollama, LM Studio, vLLM), and a hosted Flowly Cloud option. Sign in to xAI with your SuperGrok / X Premium+ subscription instead of an API key. Switch any time:

flowly                     # open the chat
/provider openrouter       # pick provider
/model anthropic/claude-haiku-4.5

Or edit ~/.flowly/config.json. When nothing is pinned, Flowly cascades through whatever you've configured (OpenRouter → Anthropic → OpenAI → xAI → …) so it always has a working model.

CLI vs messaging — quick reference

Two entry points: start the terminal UI with flowly, or run the gateway and talk to Flowly from Telegram, Discord, Slack, WhatsApp, iMessage, or email. Once you're in a conversation, most slash commands work the same in both.

Self-host or cloud

Flowly's agent core is Apache 2.0. Self-host on your laptop, a VPS, or a Mac mini — your keys, your data, your machine. Everything in this repo works with no Flowly account. → self-hosting guide · open source vs. Desktop/Cloud

Optional Flowly Cloud adds the native Mac/iOS/Android apps, cross-device sync, hosted LLM access, and a managed relay that keeps your agent reachable when your laptop sleeps. Sign-in is opt-in (flowly login) and only affects the cloud features; the agent is unchanged.

Common commands

flowly                         # terminal chat (TUI)
flowly setup                   # interactive wizard (LLM, channels, integrations)
flowly agent -m "..."          # one-shot prompt
flowly service install --start # run the gateway as a background service
flowly restart                 # smart restart (launchd / systemd / Task Scheduler)
flowly doctor                  # diagnose config + runtime health
flowly memory list             # inspect / correct long-term memory
flowly skill mine --dry-run    # preview self-improved skills (opt-in subsystem)
flowly mcp install <name>      # add an MCP server from the catalog
flowly mcp serve               # expose Flowly as an MCP server
flowly login / logout          # Flowly Cloud account (optional)

Other command groups: flowly channels · cron · plugins · skills · bundles · persona · codex · xai · sessions · approvals · pairing. Full reference: flowly --help.

Architecture

The gateway runs as a local daemon, and the whole process runs inside the OS sandbox (sandbox-exec on macOS, bwrap on Linux). Channels route through an in-process message bus; the TUI, desktop, and mobile apps connect as clients over one WebSocket protocol (ws://127.0.0.1:18790) — desktop and mobile can also reach it remotely via the Flowly Cloud relay. Config lives at ~/.flowly/config.json, shared by every client. → internal RPC protocol

Develop from source

Clone it anywhere and run it. Flowly keeps its state in one place — ~/.flowly — and a checkout uses that same state, so there is no second config to keep in sync and nothing to set up twice:

git clone https://github.com/Nocetic/flowly.git
cd flowly

uv run flowly setup       # first time on this machine: pick a provider
uv run flowly gateway     # your code, serving the usual gateway port

Already use Flowly? Skip the first line — your provider, memory and channels are already there, and the gateway will use them. New to it? The agent can't answer without a provider, so setup is the one step that isn't optional; it takes a minute and you never repeat it.

That's it. Edit, restart, repeat.

If Flowly is already installed and running, its service holds that port — and the gateway handles the handover itself: it asks, stops the service, serves in its place, and restores the service when you press Ctrl+C. Nothing else to learn.

Tests and lint:

uv pip install -e ".[dev]"    # pytest + ruff
uv run pytest                 # ~3,800 tests, about a minute
uv run ruff check flowly/

Working on Flowly Desktop or the iOS app? Nothing extra — they connect to the gateway on its usual port, which is now yours.

Want an instance that can't touch your real one? For risky work — a migration, a destructive experiment, a second agent running side by side — scripts/dev-install.sh builds a fully isolated instance (its own home, port, and account). It's the exception, not the starting point.

Full walkthrough — system dependencies, the isolated instance, PR conventions — in CONTRIBUTING.md.

Documentation

Full docs: useflowlyapp.com/docs — searchable, with everything below. The Markdown sources live in content/docs/.

• MCP — connect external MCP servers + run Flowly as an MCP server
• Plugins — extend Flowly with custom tools, hooks, commands, skills
• Task board — the cross-channel task board (sequential + parallel agents)
• Self-hosting — run Flowly on your own machine or a VPS
• Open source vs. Desktop & Cloud — what's in this repo vs. the apps
• Security — trust model + vulnerability reporting
• Contributing — dev setup, project layout, PR process
• Engineering deep-dives: memory governance · skill self-improvement · internal gateway RPC

Community

• 🐛 Issues — bugs and feature requests
• 🌐 useflowlyapp.com — apps, hosted cloud, and docs
• 📚 agentskills.io — the open skills standard Flowly speaks

Status

Flowly was open-source in v1.x, closed during the v2 rewrite, and is back open under Apache 2.0. The agent, 40+ tools, 135 skills, and every channel adapter in this repo are the same code that ships inside the Flowly Desktop app — there is no separate "lite" build.

Active development. Issues and PRs welcome.

License

Apache 2.0. Fork it, ship it, embed it. Self-hosted use with your own LLM keys is unrestricted. Commercial use of Flowly Cloud credentials (account / relay / gateway tokens) is governed by our Acceptable Use Policy — broadly: use them via official Flowly clients, not custom harnesses that proxy our subscription.

Acknowledgments

Inspired by Claude Code (Anthropic) and the broader open-source agent community. Built by Nocetic Limited.