Configuration
Runtime Setup
Gamut runs each agent in an isolated container and needs a container runtime on the host. Choose the runtime and tune images, resource limits, and environment in Settings > Runtime.
Supported runtimes
| Runtime | Platforms | Notes |
|---|---|---|
| Apple Containers | macOS 26+ | Native container support on macOS Tahoe (26) and later. |
| Docker | macOS, Linux, Windows | Docker Desktop or Docker Engine. Docker-compatible runtimes such as OrbStack work through the Docker socket. |
| Podman | macOS, Linux | Daemonless OCI container runtime. Requires a Podman machine on macOS. |
| Built-in Runtime (Lima) | macOS | Bundled with the app, no separate install. Runs agents in a lightweight Linux VM. |
| Built-in Runtime (WSL2) | Windows | Uses a Windows Subsystem for Linux 2 distro bundled with the app. |
| Kubernetes | Server deployments | Runs agent containers as pods. Detected automatically when Gamut itself runs in a cluster. |
| AWS Lambda MicroVM | Server deployments | Runs each agent in a Lambda MicroVM. Can also delegate to an external MicroVM controller. |
Change the active runtime in Settings > Runtime > Container Runner. If the configured runtime is not available, Gamut auto-switches to another available runtime.
How runtime detection works
On desktop, Gamut checks runtimes in priority order: Apple Containers (macOS 26+), then Docker, then Podman, then Lima, then WSL2. For each candidate it verifies three things:
- Eligibility: Is the runtime applicable to this OS? (Apple Containers is only eligible on macOS 26+.)
- Installation: Is the CLI installed and found in the system PATH?
- Running: Is the daemon or VM actually running and usable?
Results are cached for 60 seconds to avoid repeatedly spawning CLI processes. Force a refresh with the button next to the Container Runner selector; the cache also clears when a runtime starts or restarts.
Auto-start behavior
Some runtimes start automatically when installed but not running:
- Built-in Runtime (Lima, WSL2) and Apple Containers: Started automatically when configured as the active runtime.
- Docker Desktop: Launched by Gamut on macOS and Windows.
- Podman: On macOS, a Podman machine is started if one has been initialized.
If auto-start is not possible (Docker Engine on Linux typically requires sudo systemctl start docker), the Settings UI displays instructions.
Container image
Each agent runs inside a container built from the Gamut agent image. The default image is pulled from ghcr.io/skillfulagents/superagent-agent-container-base and tagged to match the installed Gamut version.
Image pulling
On first launch (or after an upgrade), Gamut checks whether the required image exists locally and pulls it if missing. The Settings UI shows a progress bar with per-layer completion status during the pull.
Before pulling, Gamut checks for at least 5 GB of free disk space. If space is insufficient, the pull is blocked and an error is displayed.
Override the image in Settings > Runtime > Agent Image to use a custom build. Click Use default to revert to the version-matched image.
Old image cleanup
After a successful pull, Gamut removes old images from the same registry to free disk space. Images in use by running containers are skipped.
Resource limits
Each agent container is constrained by CPU and memory limits, configured in Settings > Runtime:
| Setting | Default | Options |
|---|---|---|
| CPU Limit | 2 cores | 1, 2, 4, 6, 8 cores |
| Memory Limit | 4 GB | 512 MB, 1 GB, 2 GB, 4 GB, 8 GB, 16 GB, 32 GB |
Limits apply per container: each running agent gets its own allocation. Limits cannot change while agents are running; stop all agents first.
Built-in Runtime VM memory (Lima)
With the Lima-based built-in runtime on macOS, an additional VM Memory setting controls the maximum memory for the entire virtual machine (not per container). Options range from 2 GB to 16 GB, defaulting to 4 GB. Changing this setting restarts the runtime VM.
Idle timeout and auto-sleep
Gamut stops idle containers to conserve resources. Set the Idle Timeout in Settings > Runtime (default: 30 minutes). A container with no active sessions and no recent activity for this duration is stopped. Set to 0 to disable auto-sleep.
Open dashboards count as activity: an open agent dashboard refreshes the container's keep-alive timer.
Agent limits
Global defaults for all agent sessions live in Settings > Runtime > Agent Limits:
| Setting | Default | Description |
|---|---|---|
| Max Output Tokens | 32,000 | Maximum tokens per model response. |
| Max Thinking Tokens | Unlimited | Maximum tokens for extended thinking/reasoning. |
| Max Turns | Unlimited | Maximum conversation turns per session. |
| Max Budget (USD) | Unlimited | Maximum cost per session in USD. |
Leave any field empty to use the default.
Custom environment variables
Inject additional environment variables into agent containers from Settings > Runtime > Custom Environment Variables. They are passed to the Claude Code CLI process inside the container and apply to new sessions.
Common uses include overriding Claude Code behavior flags, setting tool-specific API keys, or passing custom configuration to agent scripts.
Variable names are normalized to uppercase with underscores (my-var becomes MY_VAR).
Trusted origins (CORS)
Server deployments (outside the Electron desktop app) may need trusted origins configured for CORS and CSRF protection, especially when the UI is served from a different domain than the API.
Environment variable
Set TRUSTED_ORIGINS to a comma-separated list of allowed origins:
TRUSTED_ORIGINS=https://superagent.example.com,https://admin.example.comThis configures the CORS middleware on all API routes.
Auth settings
In auth mode, trusted origins can also be set in Settings > Auth > Trusted Origins. They apply to both CORS and Better Auth CSRF protection, and the first origin doubles as the app's external base URL for OAuth callbacks.
With no trusted origins and no HOST environment variable, the app falls back to the request's origin header.
Key environment variables
| Variable | Default | Description |
|---|---|---|
SUPERAGENT_DATA_DIR | OS-specific | Base directory for all Gamut data (database, agent workspaces, settings). |
PORT | 47891 | HTTP server port. |
HOST | localhost | Hostname for the server. Used in OAuth callbacks and external URLs. |
USE_HTTPS | false | Set to true if the server is behind an HTTPS proxy. |
TRUSTED_ORIGINS | (none) | Comma-separated list of allowed CORS origins. |
CONTAINER_STATUS_SYNC_INTERVAL_SECONDS | 300 | How often to sync container statuses with the runtime (seconds). |
CONTAINER_HEALTH_CHECK_INTERVAL_SECONDS | 30 | How often to run container health checks (seconds). |
RUNNER_AVAILABILITY_CACHE_TTL_SECONDS | 60 | How long to cache runtime availability results (seconds). |
E2E_MOCK | (none) | Set to true to use a mock container client for testing. |
Runtime status monitoring
Gamut continuously monitors running containers:
- Status sync runs every 5 minutes and queries the runtime for containers stopped externally (by Docker Desktop, a system restart, and so on).
- Health checks run every 30 seconds on running containers, monitoring CPU and memory usage. Warnings are broadcast to the UI when thresholds are exceeded.
- Connection error recovery triggers an immediate status sync when an HTTP request to a container fails, catching unexpected crashes.
All status changes are broadcast to connected clients via Server-Sent Events (SSE), so the UI updates in real time.
Data location
All Gamut data lives under a single directory. The default location depends on the OS and can be overridden with SUPERAGENT_DATA_DIR. The current data directory is shown (read-only) at the bottom of Settings > Runtime.