# Fluksio App

Fluksio is a node-based automation software that brings trust and reliability to your flow.
It just works and looks good.

The core of Fluksio: a node-based, test-driven automation software built to scale. This
repo holds the FastAPI backend, the flow engine, and the dashboard SPA. It is served on
`app.${DOMAIN}` (SPA) and `api.${DOMAIN}` (API)

## Layout

```text
backend/        FastAPI + SQLModel + Alembic + SQLite
  fluksio/flow/ the flow engine (nodes, pipeline, state backends, controller)
  fluksio/cli.py  `fluksio serve` / `enroll` / `worker`
worker/         the `fluksio-worker` distribution: the agent and the node runner
frontend/       React 19 + TanStack Router + Tailwind 4 + shadcn/ui
docs/           the public documentation site (zensical), served on docs.${DOMAIN}
docker/         compose.yml → compose.dev.yml → compose.local.yml (+ compose.traefik.yml)
scripts/        generate-client.sh, test.sh
```

## Install without Docker

Get started quickly by running

```sh
pip install fluksio
fluksio serve
```

Then, head over to [fluksio.com](https://fluksio.com), sign up and add a new instance.
Using the code provided, run

```sh
fluksio enroll <code>
```

and you're ready to rock.

Fluksio is distributed at it's heart.
A machine that should only *run nodes* for an engine elsewhere installs less:

```sh
pip install fluksio-worker
fluksio-worker --url wss://api.fluksio.com/api/v1/workers/attach --token "$TOKEN" --labels gpu
```

## Getting started

Normally driven from the workspace root (`make init` once, then `make dev`). Standalone:

```sh
make install       # uv sync + bun install
make dev-utils     # proxy and mailcatcher only
make dev-backend   # FastAPI on :8000, hot reload
make dev-frontend  # Vite on :5173
```

```sh
make test           # pytest + Playwright (the e2e half needs the stack up)
make lint           # ruff + mypy + biome
make generate-client  # regenerate the frontend SDK from the OpenAPI schema
```

`make help` lists every target.

## Documentation

The public site lives in [`docs/`](docs/) and is built with zensical:

```sh
make docs-serve   # live preview on :8000
make docs         # static build into ./site
```

It is served at `docs.${DOMAIN}` by the `docs` service in `docker/compose.yml`,
and `.gitea/workflows/docs.yml` builds it with `--strict` on every push.


## License

Copyright (C) 2026 Melvin Strobl - GNU Affero General Public License v3.0 or
later. See [LICENSE](LICENSE).