Configuration · Hyperbeam docs

The server is configured with environment variables, or the matching command-line flags. hyperbeam-server serve --help lists every option.

Core

Variable	Default	Meaning
`HYPERBEAM_DATABASE_URL`	none (required)	Postgres connection URL.
`HYPERBEAM_MASTER_KEY`	none	The master key itself: 32 random bytes, base64. Encrypts stored credentials.
`HYPERBEAM_MASTER_KEY_AWS_SECRET`	none	Name or ARN of an AWS Secrets Manager secret that holds the master key.
`HYPERBEAM_MASTER_KEY_AWS_KMS_KEY`	none	ID, alias or ARN of an AWS KMS key. The master key is generated on first start and stored in Postgres, encrypted by this key.
`HYPERBEAM_LISTEN`	`0.0.0.0:8080`	Address the server listens on.
`HYPERBEAM_PUBLIC_URL`	`http://localhost:8080`	Where people reach the UI. Used in invite links, and as where OAuth sign-ins for connections come back to, so it must be the address admins’ browsers use.
`HYPERBEAM_INTERNAL_URL`	`http://127.0.0.1:8080`	Where sandboxes reach the server.

Exactly one of the three master key settings is required. See Credentials. To change the key of an installation that holds credentials, use rotate-master-key.

Sandboxes

Variable	Default	Meaning
`HYPERBEAM_SANDBOX_DRIVER`	`process`	`process` runs agents as local processes with no isolation, for development. `kubernetes` runs one pod per session.
`HYPERBEAM_IDLE_TIMEOUT_SECS`	`900`	Tear down an idle session’s sandbox after this long. The session can still be resumed.
`HYPERBEAM_START_TIMEOUT_SECS`	`600`	Give up on a sandbox that has not connected within this long.
`HYPERBEAM_MAX_SESSIONS`	`20`	Most sandboxes running at once. Others queue.
`HYPERBEAM_RUNNER_BIN`	next to the server	Process driver: path to `hyperbeam-runner`.
`HYPERBEAM_WORKSPACE_ROOT`	`hyperbeam-sandboxes` in the system temp directory	Process driver: where workspaces are created.

Kubernetes

Variable	Default	Meaning
`HYPERBEAM_K8S_NAMESPACE`	`hyperbeam-agents`	Namespace sandboxes run in.
`HYPERBEAM_RUNNER_IMAGE`	`ghcr.io/sam-jeston/hyperbeam/runner:latest`	Image that carries the runner binary. The chart sets it from `agents.runnerImage`.
`HYPERBEAM_K8S_IMAGE_PULL_POLICY`	`IfNotPresent`	Pull policy for sandbox images.
`HYPERBEAM_K8S_CPU_LIMIT`	`2`	CPU limit per sandbox.
`HYPERBEAM_K8S_MEMORY_LIMIT`	`4Gi`	Memory limit per sandbox.
`HYPERBEAM_K8S_WORKSPACE_SIZE`	`10Gi`	Workspace size per sandbox.

Network egress

Variable	Default	Meaning
`HYPERBEAM_EGRESS_LISTEN`	none	Address for the egress proxy to listen on. Setting it enables the proxy.
`HYPERBEAM_EGRESS_ADDR`	none	`host:port` sandboxes use to reach the egress proxy.
`HYPERBEAM_EGRESS_ALLOW`	package registries	Hosts every sandbox may reach. The default allows npm, PyPI, crates.io and the Go module proxy.

Admins can add more hosts under Settings → General, and each harness profile adds its own. See Network egress.

Web access

Variable	Default	What it does
`HYPERBEAM_WEB_ALLOW_PRIVATE`	`false`	Let `web_fetch` read pages on private and loopback addresses, for documentation on an internal network. With it on, an agent can read anything the server can reach.

Which pages agents may read is set under Settings → General. See Web access.

Integrations

These point Hyperbeam at the services’ APIs. Change them only for testing or a self-hosted GitHub. A self-hosted GitLab’s address is set where GitLab is connected, under Settings → Integrations.

Variable	Default
`HYPERBEAM_GITHUB_API_URL`	`https://api.github.com`
`HYPERBEAM_GITHUB_GIT_URL`	`https://github.com`