Configuration reference

Hive is configured with environment variables. Keep secrets in the runtime environment or in your deployment secret manager, not in source control. The deployment platform must provide the required database and application settings.

Core runtime

SECRET_KEY_BASE

Required in production. Hive uses this value to protect session data. Generate it with mix phx.gen.secret or another cryptographically secure 64-byte random-value generator.

DATABASE_URL

Required for direct container deployments. PostgreSQL connection string, for example ecto://USER:PASS@HOST/DATABASE.

PHX_HOST

Public host name used to build application links. Set it to the deployed Hive domain.

PORT

Hypertext Transfer Protocol (HTTP) port Hive listens on. Defaults to 4000.

POOL_SIZE

PostgreSQL connection pool size. Defaults to 10.

DATABASE_SSL

Set to true or 1 to connect to PostgreSQL with Transport Layer Security (TLS).

DATABASE_SSL_CA_CERT_FILE

Path to the certificate authority file used to verify the PostgreSQL server certificate when secure connection verification is required.

ECTO_IPV6

Set to true or 1 when the database connection should use Internet Protocol version 6 (IPv6). Optional.

Branding

HIVE_PRODUCT_NAME

Name the instance presents itself with in the header, page titles, login screen, and link previews. Defaults to Hive.

HIVE_LOGO_URL

Absolute Uniform Resource Locator (URL) of the image used as the header logo, the favicon, and the mark on generated link-preview images. It must be publicly reachable from both the browser and the instance itself. Defaults to the bundled Hive logo. A square image of at least 256 by 256 pixels reproduces best. If the image cannot be fetched, link previews fall back to the bundled logo.

Access control

HIVE_VISIBILITY

Controls anonymous access to the dashboard. public allows anonymous visitors to view public content. private requires sign-in before any dashboard page loads.

HIVE_ORG_DOMAINS

Comma-separated email domains that become organization members at signup. When unset, every signed-in user becomes a member.

Email notifications

Email delivery is disabled by default. People can still save notification preferences while it is disabled, but Hive does not send messages until a provider and sender are configured. Daily summaries are sent at 08:00 Coordinated Universal Time.

HIVE_EMAIL_PROVIDER

Selects the outgoing email provider. Use none to disable delivery, postmark for Postmark, or smtp for a Simple Mail Transfer Protocol server. Defaults to none.

HIVE_EMAIL_FROM

Verified sender address used for notification email. Write it on its own (notifications@example.com) or with a display name (Hive <notifications@example.com>); readers see the display name and the mail server receives the address. Required when email delivery is enabled, and Hive refuses to start when the value is not an email address.

HIVE_POSTMARK_SERVER_TOKEN

Postmark server token. Required when HIVE_EMAIL_PROVIDER=postmark.

HIVE_EMAIL_MESSAGE_STREAM

Optional Postmark message stream. Leave it unset to use the server's default transactional stream.

HIVE_SMTP_RELAY

Host name of the outgoing Simple Mail Transfer Protocol server. Required when HIVE_EMAIL_PROVIDER=smtp.

HIVE_SMTP_PORT

Port for the outgoing mail server. Defaults to 587. Port 465 enables implicit Transport Layer Security; other ports require the server to upgrade the connection with Transport Layer Security.

HIVE_SMTP_USERNAME

Optional outgoing mail username. Set it together with HIVE_SMTP_PASSWORD.

HIVE_SMTP_PASSWORD

Optional outgoing mail password. Set it together with HIVE_SMTP_USERNAME.

Authentication providers

HIVE_GOOGLE_CLIENT_ID

Google Open Authorization (OAuth 2.0) client identifier for Google sign-in.

HIVE_GOOGLE_CLIENT_SECRET

Google Open Authorization 2.0 client secret for Google sign-in.

HIVE_GOOGLE_ALLOWED_DOMAINS

Optional comma-separated email domain allowlist for Google sign-in. When exactly one domain is set, Hive also sends Google's hosted-domain hint to the account picker.

HIVE_OIDC_ISSUER

Issuer base address for a generic OpenID Connect provider. Hive discovers provider endpoints from <issuer>/.well-known/openid-configuration.

HIVE_OIDC_CLIENT_ID

Generic OpenID Connect client identifier.

HIVE_OIDC_CLIENT_SECRET

Optional generic OpenID Connect client secret.

HIVE_OIDC_DISPLAY_NAME

Optional label for the generic OpenID Connect login button. Defaults to Identity provider.

HIVE_OIDC_ALLOWED_DOMAINS

Optional comma-separated email domain allowlist for generic OpenID Connect sign-in.

HIVE_GITHUB_CLIENT_ID

GitHub Open Authorization 2.0 client identifier for GitHub sign-in.

HIVE_GITHUB_CLIENT_SECRET

GitHub Open Authorization 2.0 client secret for GitHub sign-in.

HIVE_GITHUB_ALLOWED_DOMAINS

Optional comma-separated email domain allowlist for GitHub sign-in.

GitHub App

HIVE_GITHUB_APP_ID

GitHub App identifier used for repository and webhook integrations.

HIVE_GITHUB_APP_INSTALLATION_ID

GitHub App installation identifier.

HIVE_GITHUB_APP_PRIVATE_KEY

Private key for the GitHub App installation. Accepts Privacy Enhanced Mail text or a base64-encoded value.

HIVE_GITHUB_WEBHOOK_SECRET

Signing secret for GitHub App events sent to /webhooks/github. Configure it to resolve linked error issues when a pull request that references them is merged.

HIVE_GITHUB_API_URL

Optional GitHub application programming interface (API) base address. Defaults to https://api.github.com.

Agent Model Provider

HIVE_LLM_API_KEY

Fallback provider key for features backed by a large language model. Agentic workflows prefer the profile marked Use for Hive inference in the dashboard. Flights first prefer the profile marked Use for Hive coding, then fall back to the general inference profile. When no applicable profile is marked and this value is unset, agentic workflows stay dormant.

HIVE_LLM_MODEL

Fallback model identifier in provider:model_id form, for example anthropic:claude-haiku-4-5. Required when HIVE_LLM_API_KEY is set. For an OpenAI-compatible gateway such as Together.ai, use the openai: prefix together with HIVE_LLM_BASE_URL.

HIVE_LLM_BASE_URL

Optional fallback provider endpoint override for OpenAI-compatible gateways or self-hosted providers.

Flight runners

Flights require a profile marked Use for Hive coding, a general Hive inference profile, or the launch-time model configuration. They also require a configured GitHub App and one of the sandbox runners below. They are disabled when any required part is missing. The model and GitHub credentials stay in Hive and are never passed into the sandbox.

HIVE_CODING_RUNNER

Names the sandbox provider used for new Flights. Use microsandbox for local development, kubernetes for production on Kubernetes Agent Sandbox, or disabled to turn Flights off. The default is microsandbox in development and disabled in other environments.

The local runner requires the microsandbox executable installed by mise install. The Kubernetes runner requires Agent Sandbox 0.5.1 or newer, a gVisor runtime class, and permission for Hive to create Sandbox resources and execute commands in their pods.

Other names select a custom provider supplied through HIVE_CODING_SANDBOX_MODULE. The name is stored with each Flight, so keep it stable when changing that provider's implementation.

HIVE_CODING_SANDBOX_MODULE

Fully qualified Elixir module for a custom sandbox provider. The module must be compiled into the Hive release and implement the Condukt sandbox behaviour. Hive validates the required file, search, and command operations before enabling Flights. Built-in microsandbox and kubernetes providers ignore this setting.

Hive creates the repository baseline after the custom provider starts. The provider is responsible only for creating the isolated environment and implementing the Condukt operations. It must provide a Unix-compatible shell and use /workspace as its working directory.

HIVE_CODING_SANDBOX_OPTIONS

JavaScript Object Notation (JSON) object containing runner-specific options. Custom providers receive it unchanged, which allows adapters for services such as Daytona or E2B without adding provider settings to Hive itself. Defaults to an empty object.

Options may contain provider credentials. Keep them in the deployment secret manager and never commit them to the repository.

The Kubernetes provider accepts:

Field	Behavior
in_cluster	Uses Hive's mounted Kubernetes service-account identity. Set this to true for normal deployments.
kubeconfig	Uses a kubeconfig file instead of the in-cluster identity. Intended for development and diagnostics.
namespace	Namespace where Sandbox resources are created. Defaults to hive-sandboxes.
runtime_class_name	Runtime class enforced on every sandbox. Defaults to gvisor.
service_account	Service account assigned to sandbox pods. Its token is never mounted.
image_pull_policy	Kubernetes image-pull policy for the coding image. Defaults to IfNotPresent.
node_selector	Labels that select dedicated sandbox worker nodes.
tolerations	Tolerations required by dedicated, tainted sandbox workers.
image_pull_secrets	Names of image-pull secrets available in the sandbox namespace.
ready_timeout_ms	Maximum time to wait for Agent Sandbox to report ready. Defaults to 120000.

The Hive chart produces this object from codingRuns.kubernetes values. It also creates the namespace-scoped permissions, service account, network policy, and resource quota. The cluster operator must install Agent Sandbox and configure gVisor on the selected worker nodes before enabling the runner.

HIVE_MICROSANDBOX_HOME

Optional state directory for the local microsandbox runtime. Hive defaults to the short application-specific /tmp/hive-msb directory so Unix socket paths remain within operating-system limits and Flights do not share runtime metadata with manually managed local sandboxes.

HIVE_CODING_IMAGE

Open Container Initiative (OCI) image used for each isolated run. Defaults to ubuntu:24.04.

The default image can inspect and edit code after the setup command installs Git and ripgrep. To run repository validation, use a pinned image containing that repository's build tools or extend HIVE_CODING_SETUP_COMMAND to install them. Production deployments should use an immutable image tag.

HIVE_CODING_CPUS

Virtual processor count assigned to each sandbox. Defaults to 2.

HIVE_CODING_MEMORY_MIB

Sandbox memory in mebibytes. Defaults to 4096.

HIVE_CODING_DISK_MIB

Scratch-disk capacity in mebibytes. Defaults to 8192. Kubernetes applies it as the workspace's ephemeral-volume size limit. The local microsandbox provider does not use this setting.

HIVE_CODING_TIMEOUT_MINUTES

Maximum duration of one Flight in minutes. Defaults to 30. Hive also sets the remote sandbox's automatic cleanup timer beyond this limit.

HIVE_CODING_SETUP_COMMAND

Shell command executed once after the sandbox starts and before the coding harness receives control. The default installs Git, ripgrep, and certificate authority data with Ubuntu's package manager. Set it to true when a custom image already contains every required tool.

The setup command is operator-controlled. Alert content and model output are never interpolated into it. Kubernetes sandboxes run as a non-root user, so their image should already contain required system packages and normally use true as the setup command.

Model Gateway

HIVE_INFERENCE_PROVIDERS

JavaScript Object Notation (JSON) object that declares one or more upstream model providers for the model gateway.

HIVE_INFERENCE_UPSTREAM_ID

Identifier for the single upstream provider shorthand. Defaults to default.

HIVE_INFERENCE_UPSTREAM_BASE_URL

Base address for the single upstream provider shorthand. For Together.ai, use https://api.together.ai/v1.

HIVE_INFERENCE_UPSTREAM_API_KEY

Optional provider key for the single upstream provider shorthand.

HIVE_INFERENCE_UPSTREAM_TIMEOUT

Optional upstream request timeout for the single upstream provider shorthand.

Object storage

HIVE_OBJECT_STORAGE_PROVIDER

Object storage backend. Use none to disable object storage or s3 to use Amazon Simple Storage Service (S3)-compatible storage.

HIVE_S3_BUCKET

Object storage bucket name.

HIVE_S3_REGION

Object storage region. Defaults to us-east-1.

HIVE_S3_ENDPOINT_URL

Endpoint address for S3-compatible providers.

HIVE_S3_ACCESS_KEY_ID

Access key identifier for S3-compatible object storage.

HIVE_S3_SECRET_ACCESS_KEY

Secret access key for S3-compatible object storage.

HIVE_S3_PUBLIC_BASE_URL

Optional public base address for generated object links.

HIVE_S3_FORCE_PATH_STYLE

Set to true or 1 for S3-compatible providers that require path-style bucket addressing.

Slack

HIVE_SLACK_CLIENT_ID

Slack app client identifier.

HIVE_SLACK_CLIENT_SECRET

Slack app client secret.

HIVE_SLACK_SIGNING_SECRET

Slack app signing secret used to verify incoming Slack requests.

HIVE_SLACK_BOT_SCOPES

Optional comma-separated Slack bot authorization scope list. Defaults to the scopes Hive needs for installation, message capture, replies, and link unfurling.

HIVE_SLACK_ALLOWED_TEAM_IDS

Optional comma-separated Slack workspace identifier allowlist.

HIVE_ERROR_SUMMARY_ENABLED

Set to true or 1 to post periodic, model-generated summaries of recently observed unresolved errors to Slack. The workflow also requires error tracking, a connected Slack workspace, and either a profile marked Use for Hive inference or the launch-time model provider configuration. Defaults to disabled. This value initializes the setting for a new installation. Instance administrators can later change it under Ops -> Errors without restarting Hive.

HIVE_ERROR_SUMMARY_SCHEDULE

A five-field Cron schedule controlling how often Hive prepares an error summary. Defaults to 0 9 * * *, once per day at 09:00 in Coordinated Universal Time. A summary covers unresolved issues observed since the last successfully completed period, or the preceding 24 hours on its first run. Inputs and generated output are persisted, so retries do not request the same model output twice. This value initializes the setting for a new installation and can later be changed under Ops -> Errors.

HIVE_ERROR_SUMMARY_SLACK_CHANNEL_ID

Slack channel identifier that receives error summaries. Required when error summaries are enabled. Hive uses the oldest connected Slack workspace installation to post, matching its existing operational alert behavior. This value initializes the setting for a new installation and can later be changed under Ops -> Errors.

ClickHouse

HIVE_CLICKHOUSE_ENABLED

Set to true or 1 to connect Hive to ClickHouse. It defaults to enabled in development and disabled in other environments. The Helm chart configures the connection automatically when clickhouse.enabled=true.

HIVE_CLICKHOUSE_HOST

ClickHouse host name. Defaults to localhost.

HIVE_CLICKHOUSE_PORT

ClickHouse Hypertext Transfer Protocol port. Defaults to 8123.

HIVE_CLICKHOUSE_DATABASE

ClickHouse database name. Defaults to hive in production. In development, Hive derives a database name from the same per-worktree suffix used for its PostgreSQL database, so concurrent checkouts do not share data.

HIVE_CLICKHOUSE_USERNAME

ClickHouse user name. Defaults to default.

HIVE_CLICKHOUSE_PASSWORD

ClickHouse password. The Helm chart derives this from the existing Hive application secret, so it does not require another stored credential.

HIVE_CLICKHOUSE_POOL_SIZE

Maximum number of ClickHouse connections for each read and write pool. Defaults to 5.

Observability

Hive captures its own unhandled errors through the built-in error tracking system when ClickHouse is available. Crashes are recorded as Sentry-format events against a private, auto-provisioned "Hive" project so the same dashboard and Model Context Protocol tools that surface application errors also surface Hive's own. No environment variables are required.

Vector database

HIVE_OPENDATA_VECTOR_URL

Optional base address for a compatible vector service. Current deployments can leave it unset unless a feature explicitly requires vector search.