# 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

```toml
[[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

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

### Production (containers + SSH keys)

```toml
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)

```toml
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"
```