Installing Bee Flow next to Nextcloud, step by step
· By Bee Flow · 4 min read
How to run your own Bee Flow server and connect your Nextcloud to it: what Nextcloud needs first, the installer, the pairing code and the onboarding wizard.

The Bee Flow app for Nextcloud is a small container that Nextcloud starts through AppAPI. It shows Bee Flow inside Nextcloud and passes requests on. It does not install Bee Flow itself. The server, its database and its storage are a separate stack, and this post walks through running that stack yourself and connecting your Nextcloud to it.
If you would rather have us host it, skip the first half and choose Bee Flow Cloud on the setup page. The self-host or hosted page puts the two options side by side. What the assistant does once everything runs is in an earlier post.
Check your Nextcloud first
The app runs on Nextcloud 33, 34 and 35. It needs AppAPI with a Docker deploy daemon, and for a new install we recommend HaRP. With HaRP, the reverse proxy in front of Nextcloud needs one extra rule that sends everything under /exapps/ to HaRP's port (8780 by default). Without that rule the app does not load. Nextcloud All-in-One routes /exapps/ by itself once you tick HaRP in its interface.
The older Docker Socket Proxy daemon works too, but then every request passes through Nextcloud's PHP. Chat answers arrive in one piece at the end, and long requests keep PHP workers busy.
Nextcloud has to be served over HTTPS. The app runs as a container, so the Nextcloud host needs Docker. On managed or shared hosting without Docker, Bee Flow reaches your Nextcloud from outside instead, per user, without the parts that live inside Nextcloud.
The machine for Bee Flow
You need Docker with the Compose plugin on an amd64 machine. The server images are not built for ARM. The minimum is 2 CPU cores, 4 GB of memory and 10 GB of disk, and on a host that already runs Nextcloud that comes on top. The installer also switches on the PII guard and the topic classifier by default. Those two need about 7 GB of memory, so plan about 11 GB for the default install.
Two network paths have to work. The connector must reach the Bee Flow address, and the Bee Flow server must reach your Nextcloud.
Run the installer
On the Docker host, as a user who may use Docker:
docker run --rm -it --network host \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /opt/beeflow:/opt/beeflow \
ghcr.io/bee-flow/installer
If you prefer not to hand the Docker socket to a container, the same installer is published as a script with a checksum on every release. Both ask the same questions: the address at which Nextcloud reaches this machine (not localhost), the ports, whether your Nextcloud is on a private address, and the name of your organisation. Enter accepts each default.
Before it starts anything, the installer checks Docker, the processor, free ports, memory and disk, and stops with what to do when something is missing. At the end it prints the server address, the administrator password, a pairing code that is valid for 15 minutes, and the secrets it generated on your host. Keep the .env file and a copy of those secrets. Without MASTER_ENCRYPTION_KEY your stored data cannot be read again.
The installer serves plain http on your own network. Before anyone uses Bee Flow from outside that network, put a reverse proxy with HTTPS in front of both ports. The end of the install prints those steps.
Install the app and choose your server
In Nextcloud, open Apps, search for Bee Flow in the AI category and click Install. AppAPI pulls the connector and starts it, usually within 30 to 60 seconds. A bee icon appears in the top bar.
At this point the app is connected to nothing. Open it as a Nextcloud administrator and you get the setup page with two cards, Bee Flow Cloud and Self-hosted server. When a Bee Flow server answers on the same Docker host on the default port, the page offers its address with Use this address.
Choose Self-hosted server, check the address, enter the pairing code and press Connect. The page first shows what connecting sends: the names and e-mail addresses of your Nextcloud administrators, plus the address, instance id and version of the Nextcloud. The connector then asks your server for /api/health. If nothing answers there, nothing is saved.
When the code has run out by then, make a new one in Bee Flow under Admin → Organisation → Nextcloud Sync → Pair a new Nextcloud and enter it on the same page. Nothing has to be installed again.
Finish the wizard
Open Bee Flow once more as administrator. The onboarding wizard asks which groups to synchronise, which integrations to offer and how strict the Privacy Shield should be. Until you finish it, other users see that setup is in progress. After that they get the app.
If you want automations to react to things that happen in Nextcloud, enable the Webhook Listeners app now with occ app:enable webhook_listeners. The post on Nextcloud events explains what that gives you.
Afterwards
The connector updates through Nextcloud's Apps page. The Bee Flow stack does not: you update it with the same installer and the word update at the end of the command. Back it up separately too, because your Nextcloud backup does not include Bee Flow's database, files or .env.
If Nextcloud's own Assistant answers slowly on your hardware, Nextcloud Assistant slow or not answering lists what to check first. If your setup does not fit this route, tell us about it.