---
title: "Configuration"
description: "Files, folders and environment variables OMS reads."
url: https://barestate.xyz/docs/reference/configuration
---

# Configuration

> Files, folders and environment variables OMS reads.

This page lists the files, folders and environment variables OMS reads, plus the fields in a task requirements file. Use it when you need to know where something is stored, or which variable changes a behavior.

## Files and folders

| Path | What it holds |
|---|---|
| `~/.oms/tools/surfpool-1.7.0/surfpool` | The Surfpool binary installed by `oms doctor --install` |
| `~/.oms/starter` | The persistent starter workspace for bare `oms` |
| `agent/auth.json` in the OMS state root | Provider credentials |
| `agent/oms-account.json` in the OMS state root | The OMS account token |
| `agent/inference.json` in the OMS state root | Preferences. It can also override the account service address (`gatewayOrigin`) |
| `config.json` in the OMS state root | `{"web":"off"}` turns web tools off |
| `<workDir>/checkpoints/<name>.json` | Local chain checkpoints |

The credential and preference files must be private: owned by you, with no group or other access, and not a symlink. OMS writes them with mode `0600`, and it refuses a file that is group or world readable rather than repairing it. [Credentials](https://barestate.xyz/docs/security/credentials) explains how OMS saves and checks them.

## Environment variables

| Variable | Used for |
|---|---|
| `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `DEEPSEEK_API_KEY` | Checked by `oms doctor` as a sign that model access exists |
| `OMS_SANDBOX=docker` | Docker sandbox mode |
| `SURFNET_RPC_URL` | Makes doctor check a Surfnet RPC |
| `OMS_SEARCH_URL`, `OMS_SEARCH_TOKEN` | Hosted search override. The URL must be `https`, or loopback `http` |
| `EXA_API_KEY`, `FIRECRAWL_API_KEY`, `TAVILY_API_KEY`, `PARALLEL_API_KEY`, `TINYFISH_API_KEY` | Web search backends |

Setting these in your shell does not hand them to the model. Commands that the model runs start from an empty environment plus a short allowlist, so API keys and `AWS_*` never reach them. See [Sandbox](https://barestate.xyz/docs/security/sandbox) for the allowlist.

## Requirements file for a task

`oms task create` takes a requirements file with these fields:

| Field | Meaning |
|---|---|
| `contract` | The task contract |
| `verifierPaths` | Verifier files, pinned at creation |
| `codePaths` | Code the checker takes as inputs |
| `snapshotPath` | Optional chain snapshot |
| `testTimeoutMs` | Optional test timeout |

A `done` condition is one of `tests`, `account` or `tx`. [The independent checker](https://barestate.xyz/docs/concepts/independent-checker) explains how each one is checked.

## Not available

The pack does not give the location of the OMS state root, so this page does not either.