# 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.

Source: https://useflowlyapp.com/en/docs/getting-started/installation
Language: en

## Install methods

| Who | Command | What you get |
|---|---|---|
| Everyone | `curl -fsSL https://useflowlyapp.com/install.sh \| bash` | The full install: uv, Python, and Flowly as a git checkout — `flowly update` pulls new versions |
| Contributors | `git clone … && uv run flowly gateway` | Your own checkout, using your existing `~/.flowly` — nothing else to set up. [CONTRIBUTING.md](https://github.com/Nocetic/flowly/blob/main/CONTRIBUTING.md#development-setup) |

```bash
# 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](https://useflowlyapp.com/en/docs/getting-started/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:

```bash
flowly setup
```

See [Setup wizard](https://useflowlyapp.com/en/docs/getting-started/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:

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

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

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

Check the installed version with:

```bash
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:

```bash
flowly service install --start
```

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

| Platform | Backend | Service file |
|---|---|---|
| macOS | launchd | `~/Library/LaunchAgents/ai.flowly.gateway.plist` |
| Linux | systemd (user unit) | `~/.config/systemd/user/ai.flowly.gateway.service` |
| Windows | Task Scheduler | `~/AppData/Local/flowly/ai.flowly.gateway.xml` |

The service label is `ai.flowly.gateway`.

> [!NOTE]
> 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](https://useflowlyapp.com/en/docs/using-flowly/service).

## Verify your install

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

## Related

- [Quickstart](https://useflowlyapp.com/en/docs/getting-started/quickstart)
- [Setup wizard](https://useflowlyapp.com/en/docs/getting-started/setup-wizard)
- [Configuration](https://useflowlyapp.com/en/docs/using-flowly/configuration)
- [Running as a service](https://useflowlyapp.com/en/docs/using-flowly/service)
- [Providers and models](https://useflowlyapp.com/en/docs/using-flowly/providers-and-models)
- [CLI commands](https://useflowlyapp.com/en/docs/reference/cli-commands)
- [Environment variables](https://useflowlyapp.com/en/docs/reference/environment-variables)