Skip to content

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

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.
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.

Kubernetes

Variable Name Description
VIVARIA_USE_K8S If set to 'true', Vivaria will use Kubernetes for task environments and agent containers.
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.

EKS

Variable Name Description
VIVARIA_EKS_CLUSTER_ID The name of the EKS cluster used by Vivaria.
VIVARIA_EKS_CLUSTER_AWS_REGION The AWS region where the EKS cluster is located.
VIVARIA_AWS_ACCESS_KEY_ID_FOR_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 The AWS secret access key for the IAM user with permission to create and delete Pods in the EKS cluster.

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.
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.
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:

Variable Name Description
OPENAI_API_URL The URL of the OpenAI API.
OPENAI_API_KEY The API key for the OpenAI API.

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.

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-....

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.
SLACK_TOKEN OAuth token for Vivaria Slack Notifications app.