.env.example

# Copy this to `.env` and edit. `npm start` and `npm run dev` load it automatically
# (--env-file-if-exists=.env). Every variable is optional; the defaults below are what you get
# with no .env at all.
#
# ── API KEYS DO NOT GO HERE ──────────────────────────────────────────────────────────────────────
#
# The OpenRouter key and the Claude credential live in the data directory as provider-keys.json and
# credentials.json, written 0600 and ACL'd on Windows, and are set in Settings inside the app.
# Nothing in the code reads a provider key from the environment, so a key put in this file is a key
# sitting in your repo doing nothing. Keeping them out of .env also keeps them out of your shell
# history and out of any process listing.

# Where Ferrum keeps the database, credentials, sandboxes and generated scripts.
# Default: %LOCALAPPDATA%\ferrum on Windows, ~/.local/share/ferrum elsewhere.
#
# Keep this OFF a OneDrive / Dropbox / iCloud path. SQLite in WAL mode keeps a -wal sidecar that a
# file-sync client will happily upload mid-write and later restore out of step with the main file,
# which corrupts the database. The health check warns if it detects one.
FERRUM_DATA_DIR=

# The old name, from when this was called ClayCode. Still honoured so an existing install does not
# silently start against an empty directory — which does not look like a misconfiguration, it looks
# like every sheet you ever made has vanished. FERRUM_DATA_DIR wins if both are set.
CLAYCODE_DATA_DIR=

# Full path to the database FILE, overriding the one inside the data directory.
# Default: ferrum.db in the data directory — or an existing claycode.db if there already is one,
# because renaming the file on upgrade would start an empty database beside the real one.
FERRUM_DB=

# The old name for FERRUM_DB. FERRUM_DB wins if both are set.
CLAYCODE_DB=

# Engine and API port. The Vite dev server proxies /api to 127.0.0.1:4317, so if you change this,
# change web/vite.config.ts too. A second engine started on a port already in use exits with an
# error rather than appearing to start: the survivor may be pointed at a different data directory,
# and then the app answers on the right port out of the wrong database.
PORT=4317

# Address the engine listens on. Default 127.0.0.1: only this machine can reach it, and there is no
# sign-in because there is nobody else to sign in.
#
# Set it to an address other machines can reach (0.0.0.0, or one interface) and Ferrum switches to
# shared mode: accounts and sign-in come on, and the localhost-only guard is dropped, because a
# server has to answer to its own name. Two consequences worth knowing before you set it:
#
#   1. Sign-in only exists once the first account is created, so a fresh shared instance is OPEN
#      until somebody claims it — anyone who can reach the address has every table and every saved
#      key. The engine says so in red on boot. Claim it immediately.
#   2. The session is a cookie and Ferrum does not terminate TLS. Put it behind HTTPS, a VPN or a
#      private network before you hand the address to anyone.
FERRUM_HOST=127.0.0.1

# The old name for FERRUM_HOST. FERRUM_HOST wins if both are set.
CLAYCODE_HOST=

# Base URLs of the local runtimes, for when one of them is on a non-default port. Local models are
# the only free model lane. Ferrum probes each address and lists whatever models answer there.
#
# llama.cpp and LocalAI both default to port 8080, and vLLM and Modular MAX both default to 8000, so
# those are one address each rather than four — only one process can hold a port.
OLLAMA_URL=http://127.0.0.1:11434/v1
LMSTUDIO_URL=http://127.0.0.1:1234/v1
LLAMACPP_URL=http://127.0.0.1:8080/v1
VLLM_URL=http://127.0.0.1:8000/v1
JAN_URL=http://127.0.0.1:1337/v1
GPT4ALL_URL=http://127.0.0.1:4891/v1
LITELLM_URL=http://127.0.0.1:4000/v1
ANYTHINGLLM_URL=http://127.0.0.1:3001/api/v1/openai

# Set to 1 to allow POST /api/scripts/run-direct, which runs code straight out of the request body
# with no review and no approval gate. It exists for scripts/bench-script.mjs and
# scripts/test-injection.mjs, it is not reachable from the UI, and a missing value means OFF.
# Leave it unset on any engine you actually keep data in.
FERRUM_DEV_SCRIPTS=