Connection modes

bext-tui can connect to bext in three ways. Pick the one that fits where the TUI is running relative to the bext server.

Remote mode (default)

Connect over HTTP(S) to a bext admin endpoint:

bext-tui \
  --host activ-2.activcommunication.ch \
  --port 443 \
  --tls \
  --token "$BEXT_ADMIN_TOKEN"

This is the most common mode. The TUI is just an admin API client — every byte goes over the wire to the same /__bext/admin/api/* endpoints the web dashboard uses. The connection is bearer-token authenticated; no separate login dance.

The token can come from:

1. The --token CLI flag (highest priority) 2. The BEXT_ADMIN_TOKEN environment variable 3. (Future) ~/.config/bext/credentials.toml

When to use it

- Operating production servers from your laptop

- Connecting to a colleague's dev instance over the office network

- Anywhere you can reach the admin port but don't have shell access

Local mode

When bext-tui runs on the same machine as bext:

bext-tui --local --host 127.0.0.1 --port 4000

Local mode is identical to remote mode in terms of network traffic — it still talks to the admin API. The difference is that the TUI can also read local state:

If bext.config.toml isn't in the current directory, point at it with --config:

bext-tui --local --config /etc/bext/bext.config.toml

When to use it

- On a production server you've SSH'd into

- Running locally during development with a bext dev server

- Anywhere the TUI can read filesystem paths the admin API doesn't expose

Multi-instance mode

Aggregated dashboard across many bext instances:

bext-tui --instances ~/.config/bext-tui/instances.toml

The instances file lists every server you want to monitor:

# ~/.config/bext-tui/instances.toml

[[instance]]
name = "activ-2"
host = "activ-2.activcommunication.ch"
port = 443
tls = true
token = "$BEXT_ADMIN_TOKEN_ACTIV2"

[[instance]]
name = "vps-staging"
host = "staging.example.com"
port = 4000
tls = false
token = "$BEXT_ADMIN_TOKEN_STAGING"

[[instance]]
name = "dev-laptop"
host = "127.0.0.1"
port = 4000
tls = false

The dashboard then shows an aggregated view: total request rate across all instances, total worker count, total cached entries, and any per-instance health alerts. Drill into a single instance with the command palette (: then type its name).

Tokens in instance config can be literal strings or $ENV_VAR references — the TUI expands env vars at startup.

When to use it

- Operating a fleet of bext servers across multiple regions

- Running an MSP with one dashboard per customer

- Watching production + staging + dev in one pane

Comparing modes

You can switch modes inside a session — press : to open the command palette and type connect <name> to switch to a different instance.