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:
- The
--tokenCLI flag (highest priority) - The
BEXT_ADMIN_TOKENenvironment variable - (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:
| Source | Used for |
|---|---|
bext.config.toml |
Initial config view (without round-tripping the API) |
/run/bext.pid |
PID detection — flagged in the status bar |
/proc/<pid>/{stat,status} |
CPU and RSS readings (more accurate than the API's metrics) |
.bext/logs/, .bext/cache/, .bext/certs/ |
Disk usage and on-disk certificate parsing |
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 devserver - 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#
| Remote | Local | Multi-instance | |
|---|---|---|---|
| Needs network access | ✓ | (loopback only) | ✓ |
| Reads filesystem | ✓ | ||
Reads /proc for CPU/mem |
✓ | ||
| Connects to multiple servers | ✓ | ||
| Suitable for SSH sessions | ✓ | ✓ | ✓ |
| Accurate disk usage | API best-effort | actual du |
API best-effort |
You can switch modes inside a session — press : to open the command palette and type connect <name> to switch to a different instance.
Environment variable references in the instances file (e.g. token = "$BEXT_ADMIN_TOKEN_ACTIV2") are expanded at startup. Unexpanded variables are treated as literal strings, not errors — double-check your shell environment if authentication fails.
Related#
- TUI Install — build and install the binary first
- TUI Configuration — full CLI flag and env var reference
- TUI Command Palette — the
connectcommand and other palette actions - Configuration → Endpoints and Credentials — where admin tokens come from