This is the complete list of environment variables the product reads. Variables that only tests, development builds or
the release scripts use are marked and kept at the end.
Where a table says Server, set the variable on the server’s container or process: in compose.yaml under
environment:, or in the environment of the process when you run it from source. A .env file next to compose.yaml
only fills in ${NAME} placeholders written in that file; it does not pass its variables to the container by itself.
Where a table says Desktop, it is read by the Atelier desktop app’s own processes. See
Setting a variable for the desktop app.
| Variable |
Default |
Meaning |
Example |
ATELIER_DATA_DIR |
/data in the image; .atelier-data in the current directory when run from source |
The data folder: database, attachments, settings.json, skills, secret.key. Keep it on a volume. On a server the config folder is this same folder. |
/data |
ATELIER_HOST |
127.0.0.1; 0.0.0.0 in the image |
The address the server listens on. Anything other than 127.0.0.1, ::1 or localhost makes it log a reminder to put HTTPS in front. |
0.0.0.0 |
ATELIER_PORT |
7340 |
The port it listens on. |
7340 |
ATELIER_UI_DIR |
the built web app next to the source tree; /app/ui in the image |
The folder holding the web app’s build. If it is missing the server logs “UI build not found; serving the API only”. |
/app/ui |
ATELIER_RUNNER_DIR |
/app/runner in the image; unset from source |
The folder with the runner builds and checksums.json, which the server puts into codespaces and its sandbox. Without it, codespaces and the chat sandbox cannot start a runner. After pnpm runner:build this is runner/bin. |
/app/runner |
| Variable |
Default |
Meaning |
Example |
ATELIER_BASE_URL |
unset |
The address people use to reach the server. When set, it decides what counts as “the same site” for sign-in, the live connection, passkeys and connector sign-ins, and whether cookies are marked Secure (when it starts with https). Only the origin is used; a path is dropped. An invalid URL stops the server from starting. |
https://atelier.example.com |
ATELIER_TRUSTED_PROXIES |
unset |
Comma-separated IP addresses or CIDR ranges of your reverse proxy. X-Forwarded-For, -Proto and -Host are believed only from these. Without it behind a proxy, every visitor looks like the proxy. An entry that is not an IP or CIDR stops the server from starting. |
172.16.0.0/12,192.0.2.10 |
ATELIER_SETUP_TOKEN |
a new random token at each start |
The token needed to create the first admin. It is printed in the server’s log while there are no accounts. Set it to choose your own. |
a-long-random-string |
ATELIER_SECRET_KEY |
a key file secret.key in the data folder, made on first start |
The key that encrypts stored secrets: exactly 32 bytes, as 64 hexadecimal characters or as base64. Anything else stops the server from starting. |
openssl rand -base64 32 |
The Compose file sets ATELIER_SANDBOX_HOST and ATELIER_SANDBOX_KEYS; the port and the number of accounts have defaults.
Without ATELIER_SANDBOX_HOST, chats on the server have no sandbox. Each account logs in to the sandbox as a Unix user of its
own (sbx000, sbx001, …); see the chat sandbox.
| Variable |
Default |
Meaning |
Example |
ATELIER_SANDBOX_HOST |
unset |
The sandbox container’s name on the Compose network. |
sandbox |
ATELIER_SANDBOX_KEYS |
unset |
The file the server writes its public SSH key to, in the volume the sandbox reads its authorized keys from. It also tells the sandbox, in a folder accounts/ next to it, which account each Unix user is for, so it is required. |
/sandbox-keys/authorized_keys |
ATELIER_SANDBOX_PORT |
2222 |
The sandbox’s SSH port. |
2222 |
ATELIER_SANDBOX_SLOTS |
256 |
How many accounts the sandbox can hold, 1 to 9999. Set the same number on the atelier service and, as an environment variable, on the sandbox service, then recreate both. |
512 |
ATELIER_SANDBOX_USER |
unset |
For a sandbox container you built yourself, without the account users: every account logs in as this one user and shares its folders. Leave it unset with the Compose file’s sandbox. |
dev |
| Variable |
Applies to |
Default |
Meaning |
Example |
ATELIER_COOP_RELAY |
Desktop |
https://coop.atelierhq.dev |
The relay co-op between computers goes through. The host and every guest must use the same one. Empty switches co-op between computers off on this computer. A team server’s co-op needs no relay. |
https://atelier.example.com/api/coop |
ATELIER_SERVE_COOP_RELAY |
Server |
unset |
1 runs a co-op relay on this server at /api/coop, for desktops that set ATELIER_COOP_RELAY to it. It passes encrypted traffic it can’t read. Behind a reverse proxy, set ATELIER_TRUSTED_PROXIES so its limits count each person’s address, not the proxy’s. |
1 |
| Variable |
Applies to |
Default |
Meaning |
Example |
ATELIER_UPDATE_FEED |
Server, Desktop |
https://updates.atelierhq.dev |
Where the newest version is looked up: the desktop app’s public update feed, and the server’s “newest version” check in Settings › Admin › Server. off removes that feed in both (test runs use it). The server ignores it for its check when ATELIER_UPDATES_REPO is set; with off and no repository, the Server page reads “Couldn’t check for a newer version: No update feed is set.” To stop a desktop app from checking by itself, use Settings › System › Check for updates automatically instead; see Updates. |
off |
ATELIER_UPDATES_REPO |
Server |
unset |
A GitHub repository (owner/repo) whose releases hold the desktop builds. It needs ATELIER_UPDATES_TOKEN as well to serve updates to desktop apps; alone it only decides which release the Server page calls the newest. A value that is not owner/repo stops the server from starting. |
acme/atelier-builds |
ATELIER_UPDATES_TOKEN |
Server |
unset |
A GitHub token that can read that repository’s releases (fine-grained, Contents: read-only). Never sent anywhere but GitHub’s API. |
github_pat_… |
ATELIER_UPDATER_URL |
Server |
unset |
The address of the updater service. Without it Update server is not offered and the page shows the manual command. |
http://updater:7341 |
ATELIER_UPDATER_SECRET |
Server, updater service |
/updater/secret |
The file holding the secret the server and the updater share. The server creates it on first use; the updater only reads it. |
/updater/secret |
ATELIER_UPDATER_PORT |
Updater service |
7341 |
The port the updater listens on. |
7341 |
ATELIER_IMAGE |
Server |
set in released images |
The registry image this build came from. Empty means built from source: Settings then tells the admin to update by rebuilding. |
ghcr.io/theoriuhd/atelier |
HOSTNAME |
Updater service |
the container’s id |
How the updater finds its own container, and through its labels the Compose project. Set by Docker. |
|
| Variable |
Default |
Meaning |
Example |
ATELIER_CONFIG_DIR |
~/.atelier |
The desktop’s config folder: settings.json, skills, prompts overrides. |
/Volumes/Work/atelier |
ATELIER_DATA_DIR |
<config folder>/data |
The data folder of the built-in backend. |
/Volumes/Work/atelier-data |
Both apply only to Run on this computer. Where the app keeps its own profile (sign-in, caches) is Electron’s user
data folder; the standard Chromium switch --user-data-dir=<folder> on the command line moves it. See
Data and files.
| Variable |
Default |
Meaning |
Example |
ATELIER_SSH |
ssh |
The ssh program used to reach SSH hosts (desktop) and the server’s sandbox container. |
/usr/local/bin/ssh |
ATELIER_GH |
gh |
The GitHub CLI used to connect to codespaces. |
/opt/gh/bin/gh |
ATELIER_MODEL_IDLE_TIMEOUT_MS |
900000 (15 minutes) |
How long a request to a plain http:// model server (Ollama, llama.cpp, LM Studio) may receive nothing before Atelier gives up with “sent nothing for too long” and retries. Raise it for models that go quiet for a long time while they write a large tool call. Servers reached over https:// are not affected. |
1800000 |
ANTHROPIC_API_KEY, OPENAI_API_KEY |
unset |
Only looked for, never used on their own: when one is set in the backend’s environment and no provider of that type has been added yet, Settings › Admin › Providers offers it as a one-click suggestion under Detected on this machine. Adding the provider then stores a reference (${ANTHROPIC_API_KEY}), not the key. |
|
any ${NAME} in settings.json |
|
A provider key, connector header or environment, or search key written as ${NAME} or ${NAME:-fallback} is read from the backend’s environment when it is used. |
"apiKey": "${OPENROUTER_KEY}" |
You do not set these. They are what the processes Atelier starts receive.
| Variable |
Set for |
Meaning |
ATELIER_PROJECT_DIR, CLAUDE_PROJECT_DIR |
hooks |
The root of the folder the session works in. |
GH_TOKEN, GH_PROMPT_DISABLED |
gh codespace ssh |
The signed-in person’s GitHub token, and no interactive prompts. |
SSH_ASKPASS, SSH_ASKPASS_REQUIRE, DISPLAY, ATELIER_ASKPASS_LOG, ATELIER_ASKPASS_TRUST, ATELIER_ASKPASS_PASSWORD, ATELIER_ASKPASS_PASSPHRASE |
ssh to a saved SSH connection |
The helper that answers ssh’s questions (a new host’s key, a saved password or key passphrase) and the log of the questions it was asked. |
GIT_CEILING_DIRECTORIES |
the runner of a scratch folder |
The scratch folder’s parent, so Git does not find a repository around it. |
ATELIER_RUNNER_DIR, ATELIER_TRUSTED_FOLDERS |
the desktop app’s backend and connection processes |
Where the bundled runner builds are, and the file listing the folders you trusted. Overwritten by the app. |
Other variables are read for platform reasons: PATH and SHELL (Atelier asks your login shell for its PATH, so
tools you installed are found even when Atelier starts from the Dock), HOME, DISPLAY (so ssh can ask for a password
with a helper), XDG_CONFIG_HOME (the Linux launch-at-login entry, and the runner’s global Git ignore file) and
APPIMAGE (Linux launch at login), and on Windows ComSpec, ProgramFiles, ProgramW6432, ProgramFiles(x86),
LocalAppData and PROCESSOR_IDENTIFIER (finding the shell and Git Bash, and describing the CPU). The server image sets HOME=/data/home and
NODE_ENV=production.
These are for people working on or building Atelier. In normal use they do nothing useful, and some make the app behave
oddly.
| Variable |
Used by |
Meaning |
ATELIER_DEV_URL |
desktop, development |
Loads the window from a dev server (http://localhost:5199) instead of the built web app. |
ATELIER_HIDE_WINDOW |
desktop, tests |
Keeps the window hidden and unthrottled, and the Dock icon away on macOS. |
ATELIER_SHOW_WINDOW |
end-to-end tests |
Shows the window of a test run that would otherwise be hidden. |
ATELIER_E2E_APP |
end-to-end tests |
Path of a packaged app to test instead of the development build. |
ATELIER_CHATGPT_CALLBACK_PORT |
tests |
Port of the short-lived listener on 127.0.0.1 that receives the ChatGPT Plan sign-in’s return (default 1455). Tests set 0 to pick a free port. |
ATELIER_SEARCH_BASE |
tests |
Replaces the search engines’ addresses with a local fake, and turns result-page reading off. |
ATELIER_LOOP_MIN_INTERVAL_MS |
tests |
The shortest loop interval, instead of one minute. |
ATELIER_LIVE_ANTHROPIC_MODEL, ATELIER_LIVE_OPENAI_MODEL, ATELIER_LIVE_OLLAMA_URL, ATELIER_LIVE_OLLAMA_MODEL, ATELIER_LIVE_LLAMACPP_URL, ATELIER_LIVE_COMPAT_URL, ATELIER_LIVE_COMPAT_KEY, ATELIER_LIVE_COMPAT_MODEL, ATELIER_LIVE_MISTRAL_MODEL, ATELIER_LIVE_MISTRAL_VIBE_MODEL |
live provider tests |
Which real model servers the opt-in provider tests talk to. The tests are skipped without them. |
ATELIER_PROMPT_CORPUS |
prompt originality check |
Folders to compare Atelier’s prompts against. |
ATELIER_UPDATE_KEY |
deploy/cloudflare/publish.mjs |
Path of the Ed25519 update-signing private key (default ~/.atelier-release/update-signing.key). See Updates. |
ATELIER_RELEASES_BUCKET |
deploy/cloudflare/publish.mjs |
The R2 bucket name (default atelier-releases). |
APPLE_KEYCHAIN_PROFILE |
package:mac |
The notarization login saved in the keychain (default atelier-notary). |
ATELIER_VERSION |
Docker build argument |
The version stamped into the runner builds in the image. |
An app started from the Dock, Launchpad or Start menu does not see variables you set in a shell profile. Use one of:
- macOS: start it from Terminal for that run,
ATELIER_DATA_DIR=/Volumes/Work/atelier-data /Applications/Atelier.app/Contents/MacOS/Atelier,
or set it for every app you start from now until you log out with launchctl setenv ATELIER_DATA_DIR /Volumes/Work/atelier-data.
- Windows: add a user environment variable (System Properties › Environment Variables, or
setx ATELIER_DATA_DIR D:\atelier-data), then quit and start Atelier again. Programs already running do not see it.
- Linux: start it with the variable in front (
ATELIER_DATA_DIR=/data/atelier atelier), or put env ATELIER_DATA_DIR=/data/atelier in front of the program in the Exec= line of a copy of its .desktop file.