holm

Configuration

This page lists all settings in one place. The linked pages explain them.

Client

holm and holm mcp --stdio read these.

Variable Default Effect
HOLM_SERVER_URL None The server to use. --server overrides it. See How a client finds a server.
HOLM_SERVER_TOKEN None The bearer token for the server.
HOLM_CONTENT_BOUNDARIES Off 1 puts page text between nonce markers in read, snapshot, find, eval, and console.

Server

holmd reads these. See The server.

Variable Default Effect
HOLM_SERVER_ADDR 127.0.0.1:8080 The listen address.
HOLM_SERVER_TOKEN None The bearer token. Necessary on a non-loopback address, unless a console is linked. At least 16 characters.
HOLM_CONSOLE_URL None A console's base URL. The server accepts the tokens and API keys that console signs for a workspace. See Workspaces.
HOLM_CONSOLE_SECRET None The secret the server sends when it reads revoked keys from the console and reports key use to it.
HOLM_CONSOLE_PUBLIC_KEY None One console public key to trust, in base64 or PEM, instead of reading the keys from the console. HOLM_CONSOLE_PUBLIC_KEY_FILE reads it from a file.
HOLM_PUBLIC_URL None The public origin behind a reverse proxy.
HOLM_SERVER_REAP_SECS 30 How often to remove expired boxes, in seconds.
HOLM_SERVER_JOBS inline inline launches, forks and builds in the request. queue puts the work in the store, answers 202, and the server's workers do it.
HOLM_SERVER_SCHEDULE internal internal runs the periodic work and the job workers in the server. With more than one server on one database, one of them runs the periodic work. external runs nothing by itself: a scheduler calls the /v1/jobs routes.
CRON_SECRET None A bearer token that opens the /v1/jobs routes and nothing else. Vercel Cron sends it.
HOLM_CONTENT_BOUNDARIES Off 1 applies content boundaries to /mcp.

Runtimes

See Runtimes.

Variable Default Effect
HOLM_SERVER_CONFIG None The path to the runtimes file. Read at start.
HOLM_SERVER_RUNTIMES All that answer Host runtimes to offer, separated by commas: docker, podman, nerdctl, smolvm, microsandbox.
HOLM_SERVER_SANDBOXES None Remote vendors to add from the environment, separated by commas, such as e2b, vercel, daytona, or modal.
HOLM_SERVER_SECRET_KEY None 32 bytes, base64 or hex. Encrypts vendor keys that the server stores.
HOLM_SERVER_SECRET_FILE None A file that holds the secret key. The server makes it, with mode 0600, if it does not exist.

Storage

See Storage.

Variable Default Effect
HOLM_STORAGE_BACKEND memory memory, local, sqlite, postgres, or s3.
HOLM_STATE_DIR None The directory for local.
HOLM_STATE_URL None The database URL for sqlite and postgres.
HOLM_S3_ENDPOINT None The S3 endpoint for s3.
HOLM_S3_BUCKET None The bucket for s3.
HOLM_S3_REGION None The region for s3.
HOLM_S3_PREFIX None A key prefix for s3.
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY None Credentials for s3.
HOLM_KEEP_FRAMES_SECS 2 hours How long to keep frames.
HOLM_KEEP_ENTRIES_SECS 7 days How long to keep trace entries.
HOLM_PRUNE_SECS 1 hour How often to remove old data.

E2B

The E2B client reads these, in the library and in the server.

Variable Default Effect
E2B_API_KEY None The API key. Necessary.
E2B_DOMAIN e2b.app The E2B domain, for a self-hosted E2B.

Vercel

The Vercel client reads these, in the library and in the server.

Variable Default Effect
VERCEL_TOKEN None The access token. Necessary. It must be able to write to Vercel Container Registry.
VERCEL_TEAM_ID None The team that owns the project. Necessary for the image build.
VERCEL_PROJECT_ID None The project for the sandboxes and the image. Necessary.
VERCEL_TEAM_SLUG Read from the API The team slug for the registry path, when the token cannot read the team.

Daytona

The Daytona client reads these, in the library and in the server.

Variable Default Effect
DAYTONA_API_KEY None The API key. Necessary.
DAYTONA_API_URL https://app.daytona.io/api The API URL.
DAYTONA_TARGET Daytona's The region, such as us or eu.

The Modal client reads these, in the library and in the server.

Variable Default Effect
MODAL_TOKEN_ID None The token ID. Necessary.
MODAL_TOKEN_SECRET None The token secret. Necessary.
MODAL_ENVIRONMENT The workspace default The Modal environment.
MODAL_APP holm The Modal app that holds the images and sandboxes.
MODAL_SERVER_URL https://api.modal.com:443 The API address.

Container engines

The engines read their own settings. The server does not change them.

Setting Effect
DOCKER_HOST, docker context Point Docker at a different host.
default-runtime in daemon.json Put all Docker containers on another OCI runtime, such as gVisor (runsc) or Kata.

Runtimes file

A TOML file at HOLM_SERVER_CONFIG. See The runtimes file.

default = "docker"

[runtimes.docker]
memory = "4g"

[runtimes.hardened]
provider = "docker"
isolation = "runsc"

[runtimes.e2b]
lifetime = "4h"
max_lifetime = "24h"

Top level:

Key Effect
default The runtime for a box that names none. Default docker.
[runtimes.NAME] A table for each runtime.

Runtime tables:

Field Runtimes Effect
provider Host With it, the table adds a new runtime on that engine. Without it, the table changes the runtime with the same name.
enabled Host false hides a runtime that the server found.
memory All Default memory for each box, such as "4g".
cpus All Default CPUs for each box.
lifetime All Lifetime of a box that does not give one. Default one hour.
max_lifetime All The longest lifetime a box can ask for.
isolation docker, podman, nerdctl OCI runtime for each box, such as runsc.
context docker A Docker context name.
program smolvm, microsandbox Path to the hypervisor program.
build_with smolvm, microsandbox The engine that builds images. Default docker.

Times are 24h, 90m, 3600s, or a number of seconds. The server refuses unknown fields, and refuses a lifetime that is more than max_lifetime.

Vendor fields

Fields for a remote runtime added with holm runtime add --field name=value or POST /v1/runtimes.

Field Effect
endpoint The API endpoint of a self-hosted vendor. Through the API, it must be https and a public address.
image A template ID to use for all boxes, instead of a template that the server builds.
lifetime_secs Lifetime of a box that does not give one.
max_lifetime_secs The longest lifetime a box can ask for.
public_traffic true lets anyone reach the box's published ports with no E2B traffic token. Default false.
project_id Vercel: the project. Necessary.
team_id Vercel: the team that owns the project.
team_slug Vercel: the team slug, when the token cannot read the team.
target Daytona: the region.
token_id Modal: the token ID. The secret goes in as api_key.
environment Modal: the environment.
app Modal: the app.

Secrets, such as api_key, go in with --api-key or --api-key-env, or under secrets in the API. The server never returns them.

Cargo features

For the root holm package. See Install.

Feature Default Effect
cli On The holm and holmd binaries. Turn it off for a library-only dependency.
e2b Off The E2B client.
vercel Off The Vercel Sandbox client.
daytona Off The Daytona client.
modal Off The Modal client.
microsandbox Off The microsandbox Rust library. The server uses the msb CLI with no feature.
sqlite Off SQLite storage for the server.
postgres Off PostgreSQL storage for the server.
s3 Off S3 storage for the server.

Release builds turn on e2b, vercel, daytona, modal, sqlite, postgres, and s3.

Box settings

Each box setting is available from each interface.

Setting CLI (holm new) MCP (launch_box) REST (POST /v1/boxes) Rust builder
Screen size --size WxH width, height spec.desktop.width, height size(w, h)
Screens --screens N screens spec.desktop.screens Builder::from_spec
Wayland --wayland wayland spec.desktop.server: "wayland" profile(Arc::new(WaylandProfile))
Applications --app NAME apps spec.apps Builder::from_spec
Packages --package PKG packages spec.desktop.packages packages([…])
Features (default: wide fonts, video, dock, accessibility, and X11 apps on Wayland) --base, --minimal, --audio minimal; wide_fonts, audio, video, accessibility: true adds, false leaves out spec.desktop.features minimal(), audio(), without(feature), features([…])
Network --no-network network: false spec.policy.network network(false)
Runtime --runtime NAME runtime placement.runtime runtime(name), machine(…)
Memory --memory SIZE memory placement.memory memory(size)
CPUs --cpus N cpus placement.cpus cpus(n)
Lifetime --ttl MINUTES ttl_minutes placement.expires_after_secs expires_after(duration)
Idle timeout --idle MINUTES idle_minutes placement.idle_timeout_secs expires_when_idle(duration)
Keep files when stopped --persistent persistent placement.persistent persistent(true)
Browser profile --profile NAME profile placement.profile profiles(volume)
Viewer access --spec FILE spec.policy.auth, bind, advertise auth(…), publish_on(…), advertise(…)
Full spec --spec FILE The request body