Flowly Docs
Start using Flowly
Docs/Getting Started/Installation
Getting Started

Installation

Flowly runs entirely on your machine — one install script sets up Python, the agent, and a git checkout it can keep current. Works on macOS, Linux, and Windows; first-run setup (a Flowly account or your own API key) opens automatically once it finishes.

Install methods

WhoCommandWhat you get
Everyonecurl -fsSL https://useflowlyapp.com/install.sh | bashThe full install: uv, Python, and Flowly as a git checkout — flowly update pulls new versions
Contributorsgit clone … && uv run flowly gatewayYour own checkout, using your existing ~/.flowly — nothing else to set up. CONTRIBUTING.md
# macOS / Linux
curl -fsSL https://useflowlyapp.com/install.sh | bash

# Windows (PowerShell)
irm https://useflowlyapp.com/install.ps1 | iex

The script clones the repo into an isolated, uv-managed virtualenv and installs Flowly editable — it needs no pre-installed Python (uv provides it), and flowly update fast-forwards it with git pull.

Installed Flowly before, back when it shipped as a PyPI package? Those installs no longer receive updates — re-run the script above and it migrates in place: your ~/.flowly data is untouched, the old package is retired only after the new install proves it works, and an installed background service is rewritten onto the new install and restarted.

First run

On a fresh machine setup opens automatically right after the install script finishes. It seeds your workspace and asks how to power Flowly — sign in with a Flowly account (nothing else to configure) or bring your own API key — which is the one mandatory step before the agent can run. It then checks that the provider answers, and offers to keep the gateway running in the background. See Setup wizard for the whole flow.

If it didn't open automatically (e.g. the install ran in a non-interactive shell), run it yourself:

flowly setup

See Setup wizard for every subcommand and the BYOK one-shot.

Updating

The built-in updater pulls the checkout forward and reinstalls, then restarts the gateway:

flowly update                      # git pull --ff-only + reinstall + restart

Or re-run the native install script, which fast-forwards the checkout to the latest commit:

curl -fsSL https://useflowlyapp.com/install.sh | bash

Check the installed version with:

flowly --version

Running as a background service

Bare flowly starts the gateway on demand, so nothing below is required to chat. Install it as a background service when you want the gateway up without anyone running flowly — keeping channels reachable and scheduled jobs firing, across logout and reboots:

flowly service install --start

This registers a service using your platform's native scheduler:

PlatformBackendService file
macOSlaunchd~/Library/LaunchAgents/ai.flowly.gateway.plist
Linuxsystemd (user unit)~/.config/systemd/user/ai.flowly.gateway.service
WindowsTask Scheduler~/AppData/Local/flowly/ai.flowly.gateway.xml

The service label is ai.flowly.gateway.

On Linux, enabling systemd linger lets the service survive logout —

flowly doctor --fix can enable this for you. On Windows, Flowly tries Task Scheduler first; if that's denied (no administrator shell) it automatically falls back to a Startup-folder launcher that runs the gateway at logon — so admin is not required.

For the full lifecycle (start, stop, restart, status, logs, uninstall), see Service.

Verify your install

flowly doctor          # diagnose config + runtime health
flowly status          # show gateway status