Skip to main content

Connect to Bee Flow Cloud or self-hosted

The connector ships with a setup picker — a small page hosted by the connector itself where an admin chooses whether this Nextcloud talks to Bee Flow Cloud (api.beeflow.ai) or to a self-hosted Bee Flow server.

This page is what lets you switch targets without ever touching the command line.

Where to find it​

From inside Nextcloud, with the Bee Flow connector installed:

http://<your-nextcloud>/index.php/apps/app_api/embedded/bee_flow/setup

Direct (only reachable from the host running the connector container):

http://localhost:23000/setup

(Replace 23000 with the connector's actual port — check with docker ps.)

The page is admin-gated through AppAPI, so only Nextcloud admins can open it through the embedded URL.

What it looks like​

Two big cards:

  • ☁️ Bee Flow Cloud — recommended. One click and you're done.
  • 🏠 Self-hosted server — paste the URL of your own server. Test it before saving.

After saving, the connector:

  1. Persists the choice to ${APP_PERSISTENT_STORAGE}/setup-config.json (mode 0600, alongside the tenant-key cache).
  2. Updates the in-memory apiBaseUrl so the SPA picks up the new target on its next request — no container restart needed.
  3. Discards the existing tenant key if the SaaS target changed (the old key was issued by a different service) and triggers a fresh background bootstrap against the new target.

Three configuration paths​

The effective apiBaseUrl is resolved at every startup using this priority:

#SourceSet how
1BEEFLOW_API_BASE_URL env varocc app_api:app:setenv bee_flow BEEFLOW_API_BASE_URL <url>
2setup-config.json (the picker)The /setup page
3https://api.beeflow.aiDefault — Bee Flow Cloud

If the env var is set, the picker shows a 🔒 Env-locked badge and the form is disabled. To unlock:

sudo -u www-data php occ app_api:app:setenv bee_flow BEEFLOW_API_BASE_URL ''

"Test connection" before saving​

The form has a Test connection button that probes <your-url>/api/health from the connector container's perspective and reports:

  • HTTP status (200, 404, …)
  • version and tier if the server includes them
  • Network error class (DNS failure, connection refused, TLS error, timeout)

This is the same hostname/network the connector itself will use, so a green test means the save is going to work.

Switching back​

The picker is reachable any time. Switching from self-hosted back to Cloud is a single click — same flow, no manual cleanup.

When you switch:

  • The previous tenant key is dropped.
  • A fresh bootstrap runs against the new target.
  • Existing chat history / agents / KBs in the SPA are tied to the old tenant; they won't follow you to the new SaaS.

Programmatic alternative​

For automated provisioning (Ansible, Terraform, CI):

# Lock the choice via the env var — picker stays read-only.
sudo -u www-data php occ app_api:app:setenv bee_flow \
    BEEFLOW_API_BASE_URL https://beeflow.example.com

# Or POST directly to the connector if you want the picker to remain editable.
curl -sX POST http://localhost:23000/setup \
    -H 'Content-Type: application/json' \
    -d '{"mode":"self-hosted","apiBaseUrl":"https://beeflow.example.com"}'

The POST /setup endpoint is admin-gated through AppAPI's signed proxy when called via Nextcloud, so the curl-from-host shortcut only works on the same machine where the connector is running.

What about the tenant key?​

BEEFLOW_TENANT_KEY=auto (default) plays nicely with the picker — switching SaaS targets triggers a re-bootstrap that mints a new key against the new service. If you've explicitly set BEEFLOW_TENANT_KEY to a fixed value (e.g. for an enterprise reinstall against an existing tenant), you'll want to update that too via occ app_api:app:setenv before / after switching targets. See Connector → Architecture for the full key-resolution order.