Server environment variables
This page documents the environment variables that you can use to configure the Vivaria server.
Unless explicitly specified, all environment variables are optional.
API and UI
Variable Name |
Description |
Required? |
MACHINE_NAME |
Your machine name, e.g. from running hostname . Must be lower-case, e.g. johns-macbook or joans-system-76. |
True |
API_IP |
Tells pyhooks inside agent containers where to find the Vivaria server (this server). |
True |
PORT |
What port to serve the Vivaria API on. |
True |
UI_URL |
The URL on which Vivaria is serving its UI. |
False |
NODE_ENV |
Controls several Vivaria features. For example, Vivaria only syncs data to Airtable if NODE_ENV is 'production'. |
False |
Sentry
| Variable Name | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----- |
| SENTRY_ENVIRONMENT
| Configures what environment the server/UI/pyhooks are running in, for Sentry. | False |
| SENTRY_DSN
| Enables Sentry reporting in the server and specifies its DSN. | False |
| SENTRY_DSN_REACT
| Enables Sentry reporting in the UI and specifies its DSN. | False |
| SENTRY_DSN_PYTHON
| Enables Sentry reporting in pyhooks and specifies its DSN. | False |
Datadog
Variable Name |
Description |
DD_ENV |
Configures what environment the server is running in, for Datadog. |
Database
Variable Name |
Description |
Required? |
PGHOST |
The host name or IP address of the PostgreSQL server. |
True |
PGPORT |
The port number on which the PostgreSQL server is listening. |
True |
PGDATABASE |
The name of the PostgreSQL database. |
True |
PGUSER |
The username to connect to the PostgreSQL database. |
True |
PGPASSWORD |
The password to authenticate the PostgreSQL user. |
True |
PGSSLMODE |
The SSL mode to use when connecting to the PostgreSQL server. NOTE: PGSSLMODE is not accurately passed to the pg javascript client; the only useful alternative value here is "disabled". |
True |
DB_CA_CERT_PATH |
A path to a CA certificate to use when connecting to the database. |
False |
PG_READONLY_USER |
The username for a read-only user with access to the PostgreSQL database. |
True |
PG_READONLY_PASSWORD |
The password for the read-only user. |
True |
MAX_DATABASE_CONNECTIONS |
The maximum number of database connections that each Vivaria process is allowed to use. |
False |
ACCESS_TOKEN_SECRET_KEY |
Used to encrypt and decrypt runs_t."encryptedAccessToken". |
True |
AWS and aux VMs
Variable Name |
Description |
TASK_AWS_REGION |
Vivaria will create VMs for task environments in this AWS region. |
TASK_AWS_ACCESS_KEY_ID |
Vivaria can use this AWS access key to create VMs for task environments. |
TASK_AWS_SECRET_ACCESS_KEY |
Vivaria can use this AWS secret access key to create VMs for task environments. |
AUX_VM_HAS_PUBLIC_IP |
If 'true', aux VMs will have public IPs. Otherwise, access is only possible from within the aux VM's VPC. If you set this to false, be sure to set the subnet ID appropriately (i.e. choose a private subnet). |
AUX_VM_SUBNET_ID |
If set, Vivaria will create aux VMs in this subnet. |
AUX_VM_SECURITY_GROUP_ID |
Security group for the aux VM. If not set, Vivaria will create a new security group. Note: It is wise to finish all long-running aux VM tasks if you change this from being set to unset, or vice versa. Otherwise, the code is going to either try to delete a security group that's in use by aux VMs (and fail) or it will fail to clean up a security group. |
AUX_VM_EXTRA_TAGS |
Extra tags added to resources created for the aux VM. The string is parsed in a naive way, so don't put "=" or "," in the tag names or values. |
Docker and the primary VM host
Vivaria communicates with VM hosts using the Docker CLI and will pass environment variables along to it. Use DOCKER_HOST
or DOCKER_CONTEXT
to configure how Vivaria connects to the primary VM host's Docker daemon. Use DOCKER_TLS_VERIFY
to tell the Docker to use a provided TLS client certificate to authenticate the primary VM host's Docker daemon.
Variable Name |
Description |
DOCKER_BUILD_PLATFORM |
If set, Vivaria will pass DOCKER_BUILD_PLATFORM to the --platform argument of docker build when building images. |
VIVARIA_DOCKER_IMAGE_NAME |
If set, Vivaria will build all task/run images as tags under this Docker image. |
VIVARIA_DOCKER_REGISTRY_URL |
The registry to use when using a private Docker registry. Using a private registry will cause Vivaria to --push task and run images on build. |
VIVARIA_DOCKER_REGISTRY_USERNAME |
The username to use when using a private Docker registry. |
VIVARIA_DOCKER_REGISTRY_PASSWORD |
The password to use when using a private Docker registry. |
VIVARIA_DOCKER_BUILD_CLOUD_BUILDER |
If set, Vivaria will use a Docker Build Cloud builder with this name to build images. Must also provide VIVARIA_DOCKER_REGISTRY_URL , VIVARIA_DOCKER_REGISTRY_USERNAME and VIVARIA_DOCKER_REGISTRY_PASSWORD . |
MP4_DOCKER_USE_GPUS |
Whether there are local GPUs that Vivaria can attach to task environments and agent containers. |
VM_HOST_LOGIN |
Used by Vivaria to connect to the VM host over SSH. This |
VM_HOST_HOSTNAME |
Should be the same as the hostname in DOCKER_HOST . Used by Vivaria to connect to the VM host over SSH, to set up iptables rules for no-internet task environments on the VM host and to grant users SSH access to the VM host. If unset, Vivaria will assume you want to use a Docker host running on the same machine as the Vivaria server. TODO: This is redundant with VM_HOST_LOGIN and should be removed. |
VM_HOST_SSH_KEY |
Path to an SSH key with root access on the VM host. If not set, Vivaria will fall back to the default SSH behaviour: using keys available in ssh-agent. |
FULL_INTERNET_NETWORK_NAME |
Vivaria will connect full-internet task environments to this Docker network. |
NO_INTERNET_NETWORK_NAME |
Vivaria will connect no-internet task environments to this Docker network. |
VM_HOST_MAX_CPU |
If the VM host's CPU usage is greater than this, Vivaria won't start any new runs. |
VM_HOST_MAX_MEMORY |
If the VM host's memory usage is greater than this, Vivaria won't start any new runs. |
DEPOT_TOKEN |
Optional API token for Depot (https://depot.dev/). If this and DEPOT_PROJECT_ID are provided, task and agent images will be built using Depot, otherwise they will be built using the VMHost's local docker. |
DEPOT_PROJECT_ID |
Optional project ID for Depot (https://depot.dev/). If this and DEPOT_TOKEN are provided, task and agent images will be built using Depot, otherwise they will be built using the VMHost's local docker. |
Kubernetes and EKS
You can configure Vivaria to run task environments and agent containers in:
- A Kubernetes cluster using Amazon EKS, and/or
- A Kubernetes cluster with machine that have GPUs, e.g. on a cloud provider like Voltage Park or FluidStack.
Variable Name |
Description |
K8S_POD_CPU_COUNT_REQUEST |
Vivaria will start pods with this CPU request, unless a task's manifest.yaml explicitly requests a different amount. |
K8S_POD_RAM_GB_REQUEST |
Vivaria will start pods with this RAM request, unless a task's manifest.yaml explicitly requests a different amount. |
K8S_POD_DISK_GB_REQUEST |
Vivaria will start pods with this disk request, unless a task's manifest.yaml explicitly requests a different amount. |
VIVARIA_K8S_RUN_QUEUE_BATCH_SIZE |
When a user requests that Vivaria start a k8s run, Vivaria puts the run in a queue. This controls how many k8s runs Vivaria will pull from the queue at once. VIVARIA_K8S_RUN_QUEUE_INTERVAL_MS controls how often Vivaria will check the queue for new runs. For non-k8s runs, Vivaria will always pull one run from the queue at a time and VIVARIA_RUN_QUEUE_INTERVAL_MS controls how often Vivaria will check the queue for new runs. |
VIVARIA_K8S_RUN_QUEUE_INTERVAL_MS |
How often Vivaria will check the queue for new k8s runs, in milliseconds. |
Kubernetes
Variable Name |
Description |
VIVARIA_K8S_CLUSTER_URL |
The URL of the Kubernetes cluster used by Vivaria. |
VIVARIA_K8S_CLUSTER_CA_DATA |
Vivaria uses this to verify the Kubernetes cluster's identity, to prevent man-in-the-middle attacks. Vivaria puts this in the cluster's certificate-authority-data field in its kubeconfig object. |
VIVARIA_K8S_CLUSTER_NAMESPACE |
The namespace in the Kubernetes cluster where Vivaria will create resources. Defaults to 'default'. |
VIVARIA_K8S_CLUSTER_IMAGE_PULL_SECRET_NAME |
If you're pulling images from a private registry, put credentials for the registry in a Kubernetes secret as specified here: https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/ Then, set this to the name of the secret. |
VIVARIA_K8S_CLUSTER_CLIENT_CERTIFICATE_DATA |
The client certificate for the Kubernetes cluster. Vivaria puts this in the client-certificate-data field of the user it uses to authenticate to the cluster. Not needed if using EKS. |
VIVARIA_K8S_CLUSTER_CLIENT_KEY_DATA |
The client key for the Kubernetes cluster. Vivaria puts this in the client-key-data field of the user it uses to authenticate to the cluster. Not needed if using EKS. |
VIVARIA_EKS_CLUSTER_ID |
If using EKS, the name of the EKS cluster used by Vivaria. |
VIVARIA_EKS_CLUSTER_AWS_REGION |
If using EKS, the AWS region where the EKS cluster is located. |
VIVARIA_AWS_ACCESS_KEY_ID_FOR_EKS |
If using EKS, an AWS access key ID for an IAM user with permission to create and delete Pods in the EKS cluster. |
VIVARIA_AWS_SECRET_ACCESS_KEY_FOR_EKS |
If using EKS, the AWS secret access key for the IAM user with permission to create and delete Pods in the EKS cluster. |
Kubernetes cluster with GPUs
Variable Name |
Description |
VIVARIA_K8S_GPU_CLUSTER_URL |
The URL of the Kubernetes cluster with GPUs used by Vivaria. |
VIVARIA_K8S_GPU_CLUSTER_CA_DATA |
Vivaria uses this to verify the Kubernetes cluster's identity, to prevent man-in-the-middle attacks. Vivaria puts this in the cluster's certificate-authority-data field in its kubeconfig object. |
VIVARIA_K8S_GPU_CLUSTER_NAMESPACE |
The namespace in the Kubernetes cluster with GPUs where Vivaria will create resources. Defaults to 'default'. |
VIVARIA_K8S_GPU_CLUSTER_IMAGE_PULL_SECRET_NAME |
If you're pulling images from a private registry, put credentials for the registry in a Kubernetes secret as specified here: https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/ Then, set this to the name of the secret. |
VIVARIA_K8S_GPU_CLUSTER_CLIENT_CERTIFICATE_DATA |
The client certificate for the Kubernetes cluster with GPUs. Vivaria puts this in the client-certificate-data field of the user it uses to authenticate to the cluster. |
VIVARIA_K8S_GPU_CLUSTER_CLIENT_KEY_DATA |
The client key for the Kubernetes cluster with GPUs. Vivaria puts this in the client-key-data field of the user it uses to authenticate to the cluster. |
VIVARIA_API_IP_FOR_K8S_GPU_CLUSTER |
An IP address or hostname at which pods in the Kubernetes cluster with GPUs can find the Vivaria server. |
Agent sandboxing
Variable Name |
Description |
NON_INTERVENTION_FULL_INTERNET_MODELS |
A comma-separated list of model name regexes that Vivaria allows in fully automatic full-internet runs with no human supervision. |
AGENT_CPU_COUNT |
CPU limit for task environment Docker containers used in runs and task environments started by viv task start . |
AGENT_RAM_GB |
RAM limit in GiB for task environment Docker containers used in runs and task environments started by viv task start . |
TASK_ENVIRONMENT_STORAGE_GB |
Disk usage limit in GiB for task environment Docker containers used in runs and task environments started by viv task start . This only works if the Docker storage driver meets certain conditions: https://docs.docker.com/reference/cli/docker/container/run/#storage-opt If this environment variable is set when the Docker storage driver doesn't meet those conditions, then task environment creation will fail. |
TASK_OPERATION_TIMEOUT_MINUTES |
Maximum time allowed for a task operation (e.g. start, score, teardown). If an operation takes longer than this, an error will be thrown. Useful for limiting the impact of infinite loops and similar bugs in task code. |
NO_INTERNET_TASK_ENVIRONMENT_SANDBOXING_MODE |
If set to iptables , Vivaria will attempt to sandbox no-internet task environments using iptables rules. If set to docker-network , Vivaria won't attempt to sandbox no-internet task environments. Instead, it'll assume that it's running in a Docker container that's connected to no-internet task environments by an internal Docker network. |
SKIP_SAFETY_POLICY_CHECKING |
If set to true, Vivaria does NOT check agent-submitted actions in non-intervention full-internet actions using an LLM. Otherwise, Vivaria will check these actions using an LLM. |
JWT_DELEGATION_TOKEN_SECRET |
Secret for generating JWT delegation tokens for agent actions. For example, when a user uses the "Generate options" feature, Vivaria generates a delegation token, provides it to the agent, and uses the token to authenticate the agent's generation requests. This allows the agent to generate rating options even when the agent branch is paused, but only for 15 seconds and for one specific generation request. |
Middleman
Middleman is an internal, unpublished web service that METR uses as a proxy between Vivaria and LLM APIs. Vivaria can either make LLM API requests directly to LLM providers or via Middleman.
Variable Name |
Description |
VIVARIA_MIDDLEMAN_TYPE |
If this is set to builtin , Vivaria will make LLM API requests directly to LLM APIs (e.g. the OpenAI API). If set to remote , Vivaria will make LLM API requests to the Middleman service. If set to noop , Vivaria will throw if when asked to make an LLM API request. Note that if VIVARIA_IS_READ_ONLY is true , this value is ignored and treated as noop . |
CHAT_RATING_MODEL_REGEX |
A regex that matches the names of certain rating models. Instead of using these models' logprobs to calculate option ratings, Vivaria will fetch many single-token rating prompt completions and calculate probabilities from them. |
If VIVARIA_MIDDLEMAN_TYPE
is builtin
, Vivaria can talk to one of several LLM API provider APIs:
OpenAI
Variable Name |
Description |
OPENAI_API_URL |
The URL of the OpenAI API. |
OPENAI_API_KEY |
The API key for the OpenAI API. |
Anthropic
Variable Name |
Description |
ANTHROPIC_API_KEY |
The API key for the Anthropic API. |
ANTHROPIC_API_URL |
The URL of the Anthropic API, not including version. |
Google GenAI
Variable Name |
Description |
GEMINI_API_KEY |
The API key for the Gemini API. |
GEMINI_API_VERSION |
The version of the API, e.g. v1beta . |
Additional providers supported by LangChain can be added pretty easily.
If VIVARIA_MIDDLEMAN_TYPE
is remote
:
Variable Name |
Description |
MIDDLEMAN_API_URL |
The URL of the Middleman service. |
OPENAI_API_URL |
You may also set OPENAI_API_URL to change where the OpenAI clone API will forward requests to. |
Airtable
Variable Name |
Description |
AIRTABLE_API_KEY |
An API key for Airtable. Vivaria uses this key to sync data to Airtable. |
AIRTABLE_MANUAL_SYNC |
If set to true, Vivaria will sync data to Airtable, even if NODE_ENV is not 'production'. |
Authentication
Variable Name |
Description |
USE_AUTH0 |
Controls whether or not Vivaria will use Auth0 to authenticate users. If Auth0 is disabled, Vivaria will use static access and ID tokens. |
VIVARIA_IS_READ_ONLY |
If set to true , Vivaria will not require any authentication but will also only allow GET requests, creating a public-access read-only instance of Vivaria. ACCESS_TOKEN must also be configured in this case. |
VIVARIA_ACCESS_TOKEN_MIN_TTL_MS |
Optional. Vivaria will refuse to start runs using access tokens that expire sooner than this time-to-live. |
See here for more information on how to set up Auth0.
If USE_AUTH0
is true:
Variable Name |
Description |
ID_TOKEN_AUDIENCE |
The Client ID from the Settings tab on your Single Page Application's page in the Auth0 admin dashboard. |
ACCESS_TOKEN_AUDIENCE |
The Identifier on your Auth0 API page in the Auth0 admin dashboard. |
ISSUER |
The Domain from the Settings tab on your Auth0 application page in the Auth0 admin dashboard, converted to an HTTPS URL with a trailing slash. |
JWKS_URI |
ISSUER plus .well-known/jwks.json , e.g. https://test.us.auth0.com/.well-known/jwks.json. |
VIVARIA_AUTH0_CLIENT_ID_FOR_AGENT_APPLICATION |
Optional. The Client ID from the Settings tab on your Machine to Machine application's page in the Auth0 admin dashboard. |
VIVARIA_AUTH0_CLIENT_SECRET_FOR_AGENT_APPLICATION |
Optional. The Client Secret from the Settings tab on your Machine to Machine application's page in the Auth0 admin dashboard. |
If USE_AUTH0
is false, set ID_TOKEN
and ACCESS_TOKEN
to unique, randomly-generated values for each Vivaria deployment that doesn't use Auth0. Vivaria gives ACCESS_TOKEN
to both agents and users but gives ID_TOKEN
only to users. If agents can access ID_TOKEN
as well as ACCESS_TOKEN
, then they can use it to call any Vivaria API endpoint.
Git operations
Variable Name |
Description |
ALLOW_GIT_OPERATIONS |
When false, Vivaria will throw an error if a user tries to use functionality that requires local Git operations (e.g. cloning or fetching a repo from GitHub). |
If ALLOW_GIT_OPERATIONS
is true:
Variable Name |
Description |
GITHUB_AGENT_ORG |
The GitHub organization that contains the agent repos. |
GITHUB_AGENT_HOST |
Can be used to override the default host for cloning agent repos, e.g. to use SSH or an access token. |
TASK_REPO_URL |
Can be used to override the default host for cloning the task repo, e.g. to use SSH or an access token. |
TASK_REPO_HTTPS_URL |
HTTPS URL used to construct links to the task repo in the Vivaria UI. |
Multi-node setup
You can configure Vivaria to start task environments requiring GPUs on 8xH100 servers running on Voltage Park. Vivaria connects to these servers by over Tailscale.
Variable Name |
Description |
ENABLE_VP |
If set to true, enables the Voltage Park integration in Vivaria. |
VP_SSH_KEY |
Path to the SSH key to use for connecting to Voltage Park machines. |
VP_USERNAME |
A username for logging into the Voltage Park UI. |
VP_PASSWORD |
A password for logging into the Voltage Park UI. |
VP_ACCOUNT |
A Voltage Park account ID, e.g. ac_... . |
VP_NODE_TAILSCALE_TAGS |
A list of tags to apply to Voltage Park machines in Tailscale. |
VP_VIV_API_IP |
Where an agent running on a VP machine should find the Vivaria server. |
TAILSCALE_API_KEY |
A Tailscale ephemeral API key, e.g. tskey-api-... . |
Slack
Variable Name |
Description |
SLACK_TOKEN |
OAuth token for Vivaria Slack Notifications app. |
SLACK_CHANNEL_RUN_ERRORS |
The Slack channel to send notifications to. |
SLACK_BOT_USER |
The user ID of the Slack bot user. |
Other configuration
Variable Name |
Description |
DONT_JSON_LOG |
If DONT_JSON_LOG is set to 0, Vivaria will log JSONL-formatted logs to a log file. |
SSH_PUBLIC_KEYS_WITH_ACCESS_TO_ALL_AGENT_CONTAINERS |
A list of SSH public keys that will be added to .ssh/authorized_keys in all agent containers. The list separator is a space, then three pipes, then another space. If this environment variable is unset, then by default the list is empty. |
DEFAULT_RUN_BATCH_CONCURRENCY_LIMIT |
If a user creates a run but doesn't specify a run batch, Vivaria automatically creates a default run batch for the user. The goal is to prevent users from accidentally starting hundreds or thousands of runs without specifying a concurrency limit for them. This environment variable sets the concurrency limit of the default run batch. |
VIVARIA_RUN_QUEUE_INTERVAL_MS |
When a user requests that Vivaria start a non-k8s run, Vivaria puts the run in a queue. This controls how often Vivaria will check the queue for new runs, in milliseconds. Vivaria will always pull one non-k8s run from the queue at a time. For k8s runs, VIVARIA_K8S_RUN_QUEUE_INTERVAL_MS controls how often Vivaria will check the queue for new runs and VIVARIA_K8S_RUN_QUEUE_BATCH_SIZE controls how many k8s runs Vivaria will pull at once. |
RUN_SUMMARY_GENERATION_MODEL |
The model to use for generating run summaries using the "Summary" tab on the runs page. |
RUNS_PAGE_QUERY_GENERATION_MODEL |
The model to use for generating queries in the runs page query editor. |