IllusionDB
EN
Manual · 10

Remote instances & headless

A local IllusionDB can work directly on another instance – typically your online server. The interface always comes from the local installation, but every data change lands on the server immediately. The server itself then no longer needs a web interface of its own: its admin UI can be switched off, leaving only the REST API running as a headless service.

Setting up a connection

  1. On the server: under Settings → My Account, create an API token for an admin account and copy it.
  2. Locally: Settings → Remote Instances → New connection. Enter a name, the address (e.g. https://db.example.com) and the token. The token is stored encrypted and never shown again.
  3. In the Status column IllusionDB immediately checks whether the server is reachable, whether the token is valid and belongs to an admin, and whether both sides run the same version.

Only an admin can create and use remote connections.

Switching between instances

The switcher sits at the top of the sidebar: Local or one of your connections. While a connection is active, the switcher turns yellow with a LIVE label and a banner sits above every page – every change takes effect on the server immediately. It turns red when the server is unreachable or runs a different version; update both sides to the same version then.

In live mode everything comes from the server: data sources, tables, views, files, scripts, users, groups and permissions. Only your own login, your account (password, your own API tokens) and the management of remote connections stay local. On the server you act with the permissions of the account the token belongs to.

Switching the admin UI off (headless)

Under Settings → Remote Instances → Admin UI you can switch off the web interface of the instance you’re currently working on – in live mode, the server’s. Afterwards:

  • no web interface, no login, no setup wizard – there’s no login page left that anyone could try passwords against;
  • running browser sessions end immediately;
  • the REST API with API tokens, custom script endpoints, publicly readable tables and /healthz keep working unchanged.

Switching off is only possible while an API token of an admin account exists on that instance (or a MASTER_TOKEN is set) – otherwise nobody could reach it afterwards. You can switch it back on any time locally through the connection: pick the server in the switcher, then Settings → Remote Instances → Switch admin UI on.

Emergency routes and environment variables

Variable / command Effect
HEADLESS=true Forces the admin UI off regardless of the setting. Cannot be changed from the UI.
MASTER_TOKEN=<at least 32 characters> Additional admin token from the environment only, without a database row. The way back if all API tokens are gone: set it, restart, connect locally, switch the UI back on. Generate e.g. with openssl rand -base64 32.
illusiondb -enable-admin Switches the UI back on directly on the server and exits; then restart IllusionDB normally. In the Docker container: docker compose exec illusiondb /app/illusiondb -enable-admin, then restart the container.