tking/bascule-oss
SHA256
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
bascule-oss/docs/configuration.md
Tyler King 6eb2de5dc0 docs: update all documentation for management API + dashboard 
Updated 9 files to reflect:
  Management API (axum, port 9090) — embedded in bascule-server
  Dioxus dashboard components (WASM web target)
  6 crates in workspace (was 4)

README.md:
  Added Management API + Dashboard features section
  Added dashboard row to comparison table

docs/architecture.md:
  Updated diagram showing dual-listener architecture
  Added Management API section explaining Arc<SessionStore> sharing
  Updated crate table (6 crates)

docs/configuration.md:
  Added [dashboard] config section reference

docs/observability.md:
  Added Management API monitoring section with curl examples

docs/quickstart.md:
  Added Management API quick start section

docs/comparison.md:
  Added dashboard and TPM attestation rows

CLAUDE.md + CONTRIBUTING.md:
  Updated crate lists and feature flags

config/bascule.example.toml:
  Added [dashboard] section

All 17 README links verified valid. Build clean.

Signed-off-by: Tyler King <tking@guildhouse.dev>
2026-04-05 17:17:18 -04:00

4.1 KiB
Raw Blame History

Configuration Reference

Bascule uses a TOML configuration file. Pass it with --config path/to/config.toml.

Top-Level

Field Type Default Description
listen_addr string 0.0.0.0:2222 Address to listen on
host_key_path string (generated) Path to SSH host key
shell_command string /bin/bash Shell to spawn (local PTY mode)
shell_args list [] Arguments for shell_command
banner string Welcome, {name}. Session banner
max_sessions int 0 Max concurrent sessions (0 = unlimited)

[auth]

Field Type Default Description
mode string accept-all Auth mode: accept-all, authorized-keys
authorized_keys_path string — Path to authorized_keys file

[auth.agent_id] (Entra Agent ID)

Field Type Default Description
tenant_id string — Entra tenant ID
audiences list [] Expected token audiences
multi_tenant bool false Accept agents from any tenant

[proxy]

When set, sessions are forwarded to a target SSH host.

Field Type Default Description
target_host string — Target SSH host
target_port int 22 Target SSH port
target_user string (principal) Username on target
target_key_path string — Private key for target auth
accept_target_host_key bool false Accept any target host key (dev only)

[container]

When set, sessions spawn an ephemeral container.

Field Type Default Description
runtime string auto docker, podman, nerdctl, auto
image string — Container image
pull_policy string if-not-present always, if-not-present, never
mounts list [] Volume mounts
env map {} Extra environment variables
memory_limit string — Memory limit (e.g. 512m)
cpu_limit string — CPU limit (e.g. 1.0)
shell string (image default) Shell command in container
user string — User to run as
ephemeral bool true Destroy container on disconnect
hardened bool true Drop all caps, add minimal set
read_only_rootfs bool false Read-only root filesystem
network string — Network mode (none, bridge, host)

Mount format

[[container.mounts]]
source = "/host/path"
target = "/container/path"
readonly = true

[telemetry]

Field Type Default Description
otlp_endpoint string — OTLP endpoint for trace export
service_name string bascule OTel service name

[metrics]

Field Type Default Description
enabled bool false Enable Prometheus /metrics endpoint
port int 9090 Metrics server port

Example Configs

Development

listen_addr = "127.0.0.1:2222"
[auth]
mode = "accept-all"

Production (containers + SSH keys)

listen_addr = "0.0.0.0:2222"
host_key_path = "/etc/bascule/host_key"

[auth]
mode = "authorized-keys"
authorized_keys_path = "/etc/bascule/authorized_keys"

[container]
image = "bascule-shell:k8s-ops"
ephemeral = true
hardened = true
memory_limit = "512m"
network = "none"

[dashboard]

Management API and dashboard (requires --features dashboard, default on).

Field Type Default Description
enabled bool true Enable management API
listen string 0.0.0.0:9090 Listen address for HTTP API

Example Configs

Jumphost (proxy)

listen_addr = "0.0.0.0:2222"
host_key_path = "/etc/bascule/host_key"

[auth]
mode = "authorized-keys"
authorized_keys_path = "/etc/bascule/authorized_keys"

[proxy]
target_host = "10.0.1.50"
target_port = 22
target_key_path = "/etc/bascule/target_key"