Container Config

The default configuration for the OpenRun server is defined in openrun.default.toml. The container related config settings are

openrun.toml

[app_config]

# Health check Config
container.health_url = "/"
container.health_attempts_after_startup = 30
container.health_timeout_secs = 5
container.deploy_probe_period_secs = 1
container.deploy_health_attempts = 75

# Idle Shutdown Config
container.idle_shutdown_secs = 180
container.idle_shutdown_dev_apps = false
container.idle_bytes_high_watermark = 1500 # bytes high watermark for idle shutdown
                                           # (1500 bytes sent and recv over 180 seconds)

# Status check Config
container.status_check_interval_secs = 20
container.status_health_attempts = 10

# Show logs for container startup failures in prod mode (dev is always true)
container.log_lines_to_show = 1000
container.show_logs_for_failure = true

# Kubernetes related settings
kubernetes.default_volume_size = "10Gi"
kubernetes.scaling_threshold_cpu = 80

A health check is done on the container after the container is started. If the health check fails container.health_attempts_after_startup times, the container is assumed to be down. The health check request timeout is controlled by container.health_timeout_secs.

In Kubernetes mode, container.deploy_probe_period_secs is used as the native startup and readiness probe interval, and container.deploy_health_attempts controls how long OpenRun waits for a deployment to become ready. OpenRun watches Kubernetes Deployment status for faster readiness and rollout failure detection, but the watch uses the same configured wait budget. After blue-green promotion, OpenRun also performs a best-effort EndpointSlice convergence check; if the Kubernetes API or RBAC policy does not allow listing EndpointSlices, that check is skipped. These deployment checks are separate from the background status checks that run after the app is serving traffic.

In the running state, a status check is done on the app every container.status_check_interval_secs seconds. If container.status_health_attempts of those checks fail, then the container is assumed to be down.

If an app does not receive any REST API request for 180 seconds and the total data transfer from/to the app is below 1500 bytes over 180 seconds, the app is assumed to be idle and the container is stopped. The idle shutdown does not apply for dev apps, only for prod mode apps. For frameworks like Streamlit where WebSockets is used for communication between the UI and app, there will not be any REST API calls. The data transfer is used to determine whether the app is idle.

Changing Config

The openrun.toml can be updated to have a different value for any of the properties. After the server restart, the config change will apply for all apps.

To apply the config at the app level, the app metadata can be updated. For example the command

openrun app update conf --promote container.idle_shutdown_secs=600 /myapp

changes the idle timeout for the /myapp app to 600 seconds. Without the --promote option, the change will be staged and can be verified on the staging app. App metadata level settings take precedence over the defaults in the openrun.toml. Using all as the app name will apply the change for all current apps (but not for any new apps created later).

Configuring the container manager

The default for the container command to use is

[system]
container_command = "auto"
stale_container_cleanup_interval_mins = 5

auto means that OpenRun will look for podman executable in the path. If found, it will use that. Else it will use docker as the container manager command. If the value for container_command is set to any other value (except kubernetes), that will be used as the command to use. Orbstack implements the Docker CLI interface, so Orbstack also works fine with OpenRun.

Setting container_command = "kubernetes" enables Kubernetes mode. In Kubernetes mode, the Kubernetes APIs are used to manage the container lifecycle. No CLI commands are used in Kubernetes mode.

For Docker/Podman mode, stale_container_cleanup_interval_mins controls how often OpenRun stops running containers that were started by OpenRun but are no longer referenced by an active app. Set it to 0 or a negative value to disable stale container cleanup.

Overview Kubernetes