bascule-oss/docs/configuration.md

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"

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"