Runtime Setup
Configure the container runtime that powers your SuperAgent agents, including Docker, OrbStack, Podman, and the built-in runtime.
SuperAgent runs each agent inside an isolated container. To do this, it needs a container runtime installed and running on the host machine. This page covers the supported runtimes, how SuperAgent detects them, and the settings you can tune.
Supported runtimes
SuperAgent supports several container runtimes. Which ones are available depends on your operating system:
| Runtime | Platforms | Notes |
|---|---|---|
| Built-in Runtime (Lima) | macOS | Default on macOS. Bundled with the app -- no separate install needed. Uses a lightweight Linux VM. |
| Built-in Runtime (WSL2) | Windows | Default on Windows. Uses a Windows Subsystem for Linux 2 distro bundled with the app. |
| macOS Container | macOS 26+ | Native Apple container support on macOS Tahoe (26) and later. |
| Docker | macOS, Linux, Windows | Docker Desktop or Docker Engine. Default on Linux. |
| Podman | macOS, Linux | Daemonless OCI container runtime. Requires a Podman machine on macOS. |
You can change the active runtime in Settings > Runtime > Container Runner. If the configured runtime is not available, SuperAgent will attempt to auto-switch to another available runtime.
How runtime detection works
On startup, SuperAgent checks each eligible runtime in the following order:
- Eligibility -- Is the runtime applicable to this OS? (For example, macOS Container 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?
The results are cached for 60 seconds to avoid repeatedly spawning CLI processes. You can force a refresh from the Settings UI using the refresh button next to the Container Runner selector, or the cache is automatically cleared when you start or restart a runtime.
Auto-start behavior
Some runtimes can be started automatically when they are installed but not running:
- Built-in Runtime (Lima, WSL2) and macOS Container: SuperAgent will attempt to start these automatically when they are the configured runtime but not yet running.
- Docker Desktop: On macOS and Windows, SuperAgent can launch Docker Desktop for you.
- Podman: On macOS, SuperAgent can start a Podman machine if one has been initialized.
If auto-start is not possible (for example, Docker Engine on Linux typically requires sudo systemctl start docker), the Settings UI will display instructions.
Container image
Each agent runs inside a container built from the SuperAgent agent image. The default image is pulled from ghcr.io/skillfulagents/superagent-agent-container-base and is tagged to match your installed SuperAgent version.
Image pulling
On first launch (or after an upgrade), SuperAgent checks whether the required image exists locally. If it does not, the image is automatically pulled from the registry. The Settings UI shows a progress bar with per-layer completion status during the pull.
Before pulling, SuperAgent checks that at least 5 GB of free disk space is available. If space is insufficient, the pull is blocked and an error message is displayed.
You can override the image in Settings > Runtime > Agent Image if you need a custom image. Click "Use default" to revert to the version-matched image.
Old image cleanup
After a successful pull, SuperAgent automatically removes old images from the same registry to free disk space. Images currently in use by running containers are skipped.
Resource limits
Each agent container is constrained by CPU and memory limits. Configure these 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 |
These limits apply per container. If you run multiple agents simultaneously, each one uses its own allocation.
Resource limits cannot be changed while agents are running. Stop all agents first, then update the limits.
Built-in Runtime VM memory (Lima)
When using the Lima-based built-in runtime on macOS, an additional VM Memory setting controls the maximum memory available to 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
SuperAgent can automatically stop idle containers to conserve resources. Set the Idle Timeout in Settings > Runtime (default: 30 minutes). When a container has no active sessions and no recent activity for this duration, it is stopped. Set to 0 to disable auto-sleep.
Open dashboards count as activity -- if a user has an agent's dashboard open, the container's keep-alive timer is refreshed.
Agent limits
Global defaults for all agent sessions can be configured 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
You can inject additional environment variables into agent containers from Settings > Runtime > Custom Environment Variables. These are passed to the Claude Code CLI process inside the container and apply to new sessions.
Common use cases include overriding Claude Code behavior flags, setting tool-specific API keys, or passing custom configuration to agent scripts.
Variable names are automatically normalized to uppercase with underscores (e.g., my-var becomes MY_VAR).
Trusted origins (CORS)
When deploying SuperAgent as a web server (outside the Electron desktop app), you may need to configure trusted origins for CORS and CSRF protection. This is especially relevant when the UI is served from a different domain than the API.
Environment variable
Set the TRUSTED_ORIGINS environment variable 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
When running in auth mode, trusted origins can also be configured in Settings > Auth > Trusted Origins. These origins are used for both CORS and Better Auth CSRF protection. The first trusted origin is also used as the app's external base URL for OAuth callback URLs.
If no trusted origins are configured and no HOST environment variable is set, 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 SuperAgent 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
SuperAgent continuously monitors the status of running containers:
- Status sync runs every 5 minutes (configurable) and queries the container runtime to detect containers that were stopped externally (e.g., by Docker Desktop or a system restart).
- Health checks run every 30 seconds (configurable) 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, handling cases where a container crashed unexpectedly.
All status changes are broadcast to connected clients via Server-Sent Events (SSE), so the UI updates in real time.
Data location
All SuperAgent data is stored under a single directory. The default location depends on your OS and can be overridden with the SUPERAGENT_DATA_DIR environment variable. The current data directory is shown (read-only) at the bottom of Settings > Runtime.