Run a server
The Atelier server is the same backend the desktop app runs inside itself, reached from a browser and from desktop apps set to Connect to a server. Run one when you want the web app, several people on one install, or one place for your chats and settings.
What the server is, and what it is not
Section titled “What the server is, and what it is not”- One process, one data folder. A single Node.js process keeps everything in one folder (SQLite and files). Do not run replicas; run one server per data folder.
- It never runs commands on its own machine. Code sessions and chats run in a folder on a person’s desktop app (lent over a secure link, the device link) or in a GitHub codespace; a chat without a folder runs in a separate sandbox container. If the server cannot reach a runner, a session says so, for example “This server does not run commands on its own machine. Open the desktop app to add a folder on your computer.”
- The models run elsewhere. The server forwards prompts to the providers an admin configured. It needs network access to them, not a GPU.
- It is not a multi-tenant service. Admins configure providers, instructions and connectors for everyone. Treat the people you invite as members of one team. See Accounts and Security.
Install it with the setup wizard
Section titled “Install it with the setup wizard”On a Linux or macOS machine, one line starts a full-screen wizard:
curl -fsSL https://updates.atelierhq.dev/install | sudo shThe script downloads atelier-setup for your system, checks its checksum against the one written into the script, and
starts it. To read it first, or to check it against the checksum on the release page, download it with
curl -fsSLO https://updates.atelierhq.dev/install and run sudo sh install.
sudo lets the wizard fix Docker by itself on Linux: when Docker is missing it installs it with Docker’s own installer
(get.docker.com), when it is stopped it starts it, and when the Compose plugin is missing it adds it, each on a screen
of its own. Without sudo it works the same where Docker already runs for your user, and otherwise says what to run.
On a Mac, install Docker Desktop or OrbStack first.
The wizard:
- Looks at the machine: Docker and Compose (and, with
sudo, installs or starts them), disk, memory, and whether Ollama or Tailscale are there. If it set up Atelier here before, it says so and offers to reinstall over it (keeping accounts and chats), remove it, or leave it. - Asks how people will reach the server: by default this machine’s address (
http://192.168.x.x:7340, no domain, nothing else to set up); a domain with HTTPS handled by Caddy in the same Compose project (needs ports 80 and 443 free); your own reverse proxy (Caddy, nginx, Traefik, Nginx Proxy Manager or a Cloudflare Tunnel: it writes Atelier’s side and gives you the exact settings for yours, saved inproxy/in the install folder); or Tailscale. - Shows every file before writing it, then writes
compose.yamland.env(a copy of anything it replaces is kept as.bak-<time>), pulls the images and starts them. - Tests the address like a browser would: DNS, the certificate, the server, the live WebSocket connection and a sign-in request. A failure comes with one sentence naming what to change.
- Creates your account in the terminal, so you never handle the setup token.
Afterwards, in the same program:
| Command | What it does |
|---|---|
atelier-setup doctor |
Runs the address test again, shows the container state and any refusals from the server’s log. Use it first when a page loads but spins. --url tests another address. |
atelier-setup update |
Pulls newer images and recreates what changed. |
atelier-setup status |
Shows the containers. |
atelier-setup plan --mode … --url … |
Prints the files and steps for answers given as flags and changes nothing. install --yes with the same flags installs without the wizard. |
The wizard does not touch a server that is already running; it finds it, says where it lives and installs next to it only if you choose another folder and port. To put an existing server on the released images, see Images and tags.
Run it
Section titled “Run it”You need Docker with the Compose plugin, a host that stays on, and a hostname that points at it.
- Copy
deploy/compose.yamlanddeploy/Caddyfilefrom the repository to the host. Put your hostname in both:ATELIER_BASE_URLin the Compose file and the site address at the top of the Caddyfile. - Start it:
docker compose up -d. The first start downloads four images and takes a minute. - Read the setup token from the log:
docker compose logs atelier | grep setupToken. It is one JSON line:No accounts yet. Create the admin in the browser with this setup token. - Open
https://your-hostname/. A fresh server asks for Setup token, Full name, Username (2 to 32 characters: letters, digits, dots, dashes, underscores) and Password (at least 8 characters). That account is the first admin. - Add a model: Settings › Admin › Providers. See Providers.
The token is random at every start unless you set ATELIER_SETUP_TOKEN, and it works only while the server has no
accounts. If you lose it, restart the container and read the new one. Without the token nobody can claim a fresh server
(“That setup token is wrong. It is printed in the server log.”), and once an admin exists the server refuses any second
setup (“This server already has an admin. Sign in instead.”).
From here: invite people (Accounts), open Settings › Admin › Server to choose whether sign-up is Invite only (default) or Open, with approval, and read the hardening checklist.
What the Compose file runs
Section titled “What the Compose file runs”| Service | Image | What it does |
|---|---|---|
atelier |
ghcr.io/theoriuhd/atelier |
The server. Listens on 7340 inside the Compose network and is not published to the host. Data in the atelier-data volume at /data. |
sandbox |
ghcr.io/theoriuhd/atelier-sandbox |
A small Debian container with Git, Python, Node and build tools, where Chat runs commands, each account as a Unix user of its own. Limited to 2 CPUs, 2 GB of memory and 512 processes. |
updater |
ghcr.io/theoriuhd/atelier-updater |
Optional. Lets an admin press Update server. It holds the Docker socket; see the updater. |
caddy |
caddy:2 |
Gets and renews the certificate, terminates HTTPS on ports 80 and 443, and forwards to atelier:7340. Certificates live in the caddy-data volume. |
The server image has a health check; docker compose ps shows healthy once it is up.
Images and tags
Section titled “Images and tags”Each release publishes the three images for linux/amd64 and linux/arm64, as ghcr.io/<owner>/<name>:<tag> and :latest
(a prerelease gets only its tag):
| Image | Contents |
|---|---|
ghcr.io/theoriuhd/atelier |
The server, the web app, the Linux runner builds and the GitHub CLI (for codespaces). Node 24. |
ghcr.io/theoriuhd/atelier-sandbox |
The Chat sandbox. |
ghcr.io/theoriuhd/atelier-updater |
The optional updater service. |
- The tag is the Git tag, including the
v::v<version>, not:<version>. :latestmoves with everyv*tag, including prereleases such asv0.3.0-beta.1. If you do not want to follow prereleases, pin a release tag in the Compose file.- To build the server yourself from the repository root:
docker build -f apps/server/Dockerfile -t atelier .(--target sandboxand--target updaterbuild the other two). It needs BuildKit, the default in Docker 23 and later. An image built this way has no registry name, so Settings › Admin › Server tells you to update by rebuilding it.
Connecting browsers and desktop apps
Section titled “Connecting browsers and desktop apps”Browsers need nothing: open the address and sign in. The sign-in cookie lasts 30 days and is not renewed.
Desktop apps choose Connect to a server on first run (or Settings › Account › Switch… later) and enter the Server URL. Accepted forms:
atelier.example.com,192.0.2.20:7340, or a fullhttps://atelier.example.com. Without a scheme, Atelier trieshttps://first and, if nothing answers within 4 seconds,http://. Plainhttp://is accepted only for this computer, private network ranges (10.x, 172.16 to 31.x, 192.168.x), link-local and Tailscale addresses (100.64.0.0/10), single-word names such asnas, and names ending in.local,.localhostor.ts.net. For anything else you get “Use https:// for … Plain http:// is only allowed for this computer, your local network and Tailscale (*.ts.net).”- The server must answer
GET /api/healthwith{"ok":true,"app":"atelier",…}. If it does not, you see “No Atelier server answered at …”.
Under the field, Found on your network lists servers the app finds by asking every address in the private /24
networks of this computer’s interfaces (at most two networks; VPN, Tailscale, container and virtual interfaces skipped)
for http://<address>:7340/api/health within about three seconds. It always checks this computer too.
- Only servers on port 7340 over plain HTTP are found. A server behind Caddy on 443 that does not publish 7340 to the network is not listed; type its address.
- It sends only a health check, and only on the local network.
- On macOS the first scan makes the system ask whether Atelier may find devices on your local network. Answer yes, or see Troubleshooting.
After you sign in, the desktop app registers itself as one of your devices (Settings › Account › Devices) and keeps a link to the server open. While it is up, your sessions on the server can use the folders you trusted on that computer; the desktop refuses any folder you did not open in its own folder picker. Trusting a folder lets the server’s sessions run commands as you on that computer, and so could the server if it were compromised. A different feature, Remote control, decides whether your own other devices can open your conversations.
Addresses, HTTPS and proxies
Section titled “Addresses, HTTPS and proxies”ATELIER_BASE_URL and ATELIER_TRUSTED_PROXIES
Section titled “ATELIER_BASE_URL and ATELIER_TRUSTED_PROXIES”Atelier decides what “the same site” means from two settings:
ATELIER_BASE_URL: the address people type, for examplehttps://atelier.example.com. When set, it is the answer: only its origin (scheme, host and port) is used.ATELIER_TRUSTED_PROXIES: a comma-separated list of IP addresses or CIDR ranges of your reverse proxy. Atelier believesX-Forwarded-Proto,X-Forwarded-HostandX-Forwarded-Foronly on connections that come from these.
Without ATELIER_BASE_URL, the origin is taken from the request: the Host header, with the scheme and host from the
proxy’s headers if the proxy is trusted. The client’s address (used for rate limits and the Active sessions list) is
the connection’s address, or, through a trusted proxy, the nearest address in X-Forwarded-For that is not itself a
trusted proxy.
The Compose file sets both: the public address, and 172.16.0.0/12, the range Docker uses for its networks. Check yours
with docker network inspect and adjust if your Compose network is outside it.
Set both whenever there is a proxy. Without ATELIER_TRUSTED_PROXIES every visitor appears to come from the proxy, so
wrong passwords for one username from anyone count together and anyone can lock that username out (see
Accounts).
What breaks when they are wrong
Section titled “What breaks when they are wrong”| If | You see |
|---|---|
The address people use differs from ATELIER_BASE_URL (a different host, http against https in either direction, a missing port, the server’s IP address on your LAN instead of its name) |
In a browser, sign-in answers Cross-site request refused. and the live connection is refused with HTTP 403 (“Cross-site WebSocket refused.”): the page loads and then spins. The server refuses requests whose Origin it does not recognise. |
No ATELIER_BASE_URL, a TLS-terminating proxy, and the proxy is not in ATELIER_TRUSTED_PROXIES |
The same, because Atelier sees an http request while the browser says https. |
The hostname in ATELIER_BASE_URL changes after people added passkeys |
The passkeys no longer work: they are bound to the hostname (see below). |
| A connector (an MCP server) signs in with OAuth through your server | The sign-in returns to <ATELIER_BASE_URL>/oauth/callback. If that address is not reachable from the admin’s browser, the sign-in cannot finish. An authorization server that reads Atelier’s client metadata fetches <ATELIER_BASE_URL>/oauth/client-metadata.json, so that address has to be reachable from it. |
ATELIER_TRUSTED_PROXIES is missing behind a proxy |
Rate limits and the sessions list see only the proxy’s address. |
Desktop apps send no Origin header, so a wrong ATELIER_BASE_URL does not stop them, but a proxy that does not pass
WebSockets does. The server refuses to start with an invalid ATELIER_BASE_URL, or with a ATELIER_TRUSTED_PROXIES entry
that is not an IP address or CIDR range (ATELIER_TRUSTED_PROXIES: "x" is not an IP address or CIDR range.).
To test a proxy without a browser, open a WebSocket to /api/ws with Origin set to your public address: 101 means
accepted, 403 means refused.
Passkeys need a hostname
Section titled “Passkeys need a hostname”Passkeys (WebAuthn) are offered only in a browser, over HTTPS (or on localhost), on an address with a hostname:
not on an IP address such as https://192.0.2.20. The relying party is the hostname of the server’s public address, so
every device that uses a passkey must reach the server at that hostname. Changing the hostname orphans the passkeys; people sign in with their password and add them again. The desktop
app signs in with a password.
Reverse proxies other than Caddy
Section titled “Reverse proxies other than Caddy”Caddy needs no extra configuration. Anything else must:
- Pass WebSockets on
/api/ws(the app) and/api/devices/link(desktop devices). Without this, the page loads and spins, and desktop apps say “The server answers, but refuses the live connection.” - Keep the connection open. The app’s live connection carries every reply as it streams and has no ping of its own
between replies. A proxy that closes idle connections after 60 seconds (nginx’s default
proxy_read_timeout) cuts it and interrupts replies in flight. Use an hour or more. The device link pings every 10 seconds and is not affected. - Forward
Host,X-Forwarded-ForandX-Forwarded-Proto, and not stripOriginorAuthorization. - Not buffer or rewrite the responses, and not add a second
Content-Security-Policy(see Security). Uploads travel inside the WebSocket as base64 (up to 32 MB per file), so request-body limits do not apply to them.
An example for nginx:
map $http_upgrade $connection_upgrade { default upgrade; '' close; }
server { listen 443 ssl; server_name atelier.example.com; # ssl_certificate and ssl_certificate_key here
location / { proxy_pass http://127.0.0.1:7340; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; proxy_read_timeout 3600s; proxy_send_timeout 3600s; }}Set ATELIER_BASE_URL=https://atelier.example.com and put nginx’s address in ATELIER_TRUSTED_PROXIES. If the proxy runs
on the same host and you publish the port for it, publish it on loopback only (127.0.0.1:7340:7340).
On a tailnet, use the machine’s *.ts.net name; Tailscale and Caddy can get a certificate for it
(tailscale cert).
On a LAN without HTTPS
Section titled “On a LAN without HTTPS”For a home network you control, plain HTTP works. Publish the port instead of using Caddy, and leave ATELIER_BASE_URL
unset, or set it to exactly the address people type (http://192.0.2.20:7340):
services: atelier: image: ghcr.io/theoriuhd/atelier:latest restart: unless-stopped ports: ['7340:7340'] volumes: [atelier-data:/data]volumes: atelier-data:What you give up: passwords, sign-in cookies and every conversation cross the network in clear text, and passkeys are not
available. Browsers on other computers can use it; desktop apps accept http:// for private addresses. Do not
expose this to the internet.
Single sign-on
Section titled “Single sign-on”People can sign in through an OpenID Connect identity provider such as Authentik, Keycloak, Authelia, Pocket ID, Google or Microsoft Entra ID. It is for browsers: the desktop app signs in with a password. See what it means for accounts.
Two addresses have to be right first. Set ATELIER_BASE_URL when the
server runs behind a proxy, because the redirect URI is built from it. And the server itself reaches the provider to read
its configuration and finish each sign-in, so the issuer’s address must work from inside the container, not only from
your browser. A provider with a certificate from your own authority needs NODE_EXTRA_CA_CERTS; plain http:// issuers
work, for a provider on your own network.
Without ATELIER_BASE_URL, each address people reach the server at has its own redirect URI, and the provider has to list
all of them. The dialog shows the one for the address you are on. A browser on https://atelier.example.com and a desktop
app on http://192.168.1.10:7340 are two addresses, so list both.
- Open Settings › Admin › Server › Single sign-on › Add provider and type a name. The dialog shows the Redirect URI, which follows the name until you add the provider and then stays. Copy it.
- Create an application at your provider with that redirect URI, the authorization code flow and the scopes
openid,profileandemail. Atelier always uses PKCE. - Back in the dialog, fill in Issuer, Client ID and Client secret (empty for a public client), and choose what happens to someone without an account here. Atelier reads the provider’s configuration before it saves, so a wrong address shows there. The client secret is encrypted with the secrets key.
- Connect your own admin account in Settings › Account › Connected sign-ins, in a browser or the desktop app. Continue with does not find an existing account by itself: it would make you a new one.
When a sign-in fails after the provider, people see that it didn’t work and the server’s log says why.
Authentik
Section titled “Authentik”- In the Admin interface, open Applications › Applications and press New Application. Give it a name and a slug,
such as
atelier. - Choose OAuth2/OIDC as the provider type, and put the redirect URI from Atelier in Redirect URIs.
- Copy the Client ID and Client Secret to Atelier. The issuer is
https://authentik.example.com/application/o/atelier/, ending in the application’s slug and a slash; Atelier also takes it without the slash, or the address of its OpenID configuration.
Authentik applications are open to every Authentik user until you bind a group or policy to them. Bind one, or keep Create an account an admin approves, which is the default for this reason. Issuer mode has to stay on its default, one issuer per provider: with one for all providers, the issuer’s address has no configuration for Atelier to read.
The secrets key
Section titled “The secrets key”Provider API keys, connector tokens and other secrets are encrypted at rest with AES-256-GCM. The key is exactly 32 bytes:
ATELIER_SECRET_KEY(recommended): 64 hexadecimal characters or base64 of 32 random bytes.openssl rand -base64 32makes one. Anything else, a shorter passphrase included, stops the server from starting with “ATELIER_SECRET_KEY must encode 32 bytes (hex or base64)”. The check only counts bytes: a typed passphrase of 43 or 44 letters and digits also decodes to 32 bytes and is accepted as a key, so generate the key instead of choosing one.- Without it, the server makes a key on first start and keeps it in
/data/secret.key(base64, mode 0600).
Consequences:
- The key and the secrets it protects are in the same volume unless you set the variable. A copy of the volume is then a
copy of your API keys. Setting
ATELIER_SECRET_KEYfrom a secret store, or encrypting backups, keeps them apart. - Restoring a backup on another host needs the same key. Restore the volume with its
secret.key, or set the sameATELIER_SECRET_KEY. A different key does not damage anything else; stored secrets simply cannot be read and are entered again in Settings › Admin. - Setting
ATELIER_SECRET_KEYon a server that already has asecret.keymakes the variable win from then on: secrets encrypted with the file’s key cannot be read until you set the variable to the same value (the file is base64 of the key). - A damaged
secret.key(not 32 bytes after decoding) stops the server from starting with “Secret key must be 32 bytes”.
Environment
Section titled “Environment”The variables you will most often set on a server. The complete list, including every default, is Environment variables.
| Variable | Default | Meaning |
|---|---|---|
ATELIER_DATA_DIR |
/data in the image |
Database, files, settings and the secrets key. Keep it on a volume. |
ATELIER_BASE_URL |
none | The address people use. Origin checks, passkeys, connector sign-ins and Secure cookies follow it. |
ATELIER_TRUSTED_PROXIES |
none | IPs or CIDRs of your reverse proxy. X-Forwarded-* is believed only from these. |
ATELIER_HOST, ATELIER_PORT |
0.0.0.0, 7340 in the image; 127.0.0.1, 7340 from source |
Where it listens. |
ATELIER_SECRET_KEY |
a key file in the data folder | See The secrets key. |
ATELIER_SETUP_TOKEN |
random at each start | The one-time token for creating the first admin. |
ATELIER_SANDBOX_HOST, ATELIER_SANDBOX_KEYS, ATELIER_SANDBOX_PORT, ATELIER_SANDBOX_SLOTS, ATELIER_SANDBOX_USER |
none, none, 2222, 256, none |
The chat sandbox and how many accounts it holds. Leave out the host and chats have no sandbox. |
ATELIER_UPDATES_REPO and ATELIER_UPDATES_TOKEN |
none | Serve desktop updates from a GitHub repository’s releases. Both are needed. |
ATELIER_UPDATER_URL |
none | The updater service, for Update server. |
ATELIER_UPDATE_FEED |
https://updates.atelierhq.dev |
Where the server looks up the newest version; off stops the lookup, unless ATELIER_UPDATES_REPO is set. |
ATELIER_IMAGE |
set in released images | What image this is; empty means built from source. |
Put a value in compose.yaml under environment:, or write a placeholder there and keep the value in a .env file next to
it, which is how Compose fills in ${NAME}:
environment: ATELIER_SECRET_KEY: ${ATELIER_SECRET_KEY} # the value is a line in .env: ATELIER_SECRET_KEY=...A .env file alone passes nothing to the container. Prefer it to your shell: the updater recreates services from the files
in that folder, and a value that lived only in your shell would be lost.
The chat sandbox
Section titled “The chat sandbox”A chat without a folder runs its file and command tools in a sandbox: a folder of its own, under fixed rules and
without permission prompts, to clone repositories, run code and write files. Without the sandbox service, such a chat
has no file or command tools until it is given a folder (Chat). On a server that folder is in the sandbox container. It:
- holds none of the server’s data or secrets;
- is reached by the server over SSH with a key the server makes itself the first time a chat needs it (in
/data/sandbox, published to the sharedsandbox-keysvolume); - keeps each chat’s folder under
chats/<account>/in its own volume (sandbox-home); - is shared by everyone on the server, but each account runs as a Unix user of its own in it (
sbx000,sbx001, …), with a home and chat folders that only that user can enter, so one person’s commands cannot read or change another’s folders. Its sshd runs as root only to log each account in as its user, and the compose file takes away every other root power; - has normal outbound network access and sits on the same Compose network as the server.
Accounts and users. The first time an account’s chat needs the sandbox, the server gives it the lowest free user, for
good, keeps that in sandbox/slots.json in the data folder, and tells the sandbox which account the user is, through the
sandbox-keys volume (where the accounts themselves cannot read it). The sandbox remembers the first account each user was
given to, in .slots/ in sandbox-home, and refuses logins as a user the server later hands to another account, so a lost
slots.json cannot give one account another’s folders: restore sandbox/slots.json from your backup (back it up with the data
folder) or, if you mean to start over, remove the files in /home/sandbox/.slots. The pool has 256 users. For more accounts
set ATELIER_SANDBOX_SLOTS to the same number on the atelier and the sandbox service and recreate both; an account that
finds the pool full gets a message that says so. A deleted account keeps its user and its folders, so the pool counts every
account that ever used the sandbox.
Updating from a version where all accounts shared one user. Pull and recreate both images together
(docker compose pull && docker compose up -d, or Update server). The compose file you already have keeps working; the new
one only adds hardening you can copy (security_opt, cap_drop and cap_add of the sandbox service). Chats made before keep
their folders and their paths: when the new sandbox starts, everything the old shared user left in sandbox-home is locked to
root, so nobody can read it, and the first time an account’s chat uses the sandbox again its chats/<account>/ folder is handed
to that account’s user, files and all. The folders of accounts that never come back stay locked. What else sat in the old shared
home (caches, old runner copies, anything outside chats/) is locked too; delete it when you no longer want it, for example
docker compose exec sandbox sh -c 'cd /home/sandbox && rm -rf .cache .npm .atelier'. If only one of the two containers was
updated, chats fail with “Permission denied” from the sandbox; update both. ATELIER_SANDBOX_USER (for a sandbox container you
built yourself, without account users) makes everybody log in as that one user, as before, without any of this separation.
Leave out the sandbox service and the ATELIER_SANDBOX_* variables and chats simply have no sandbox. See
Security for its limits.
Code in the browser
Section titled “Code in the browser”Code, and a chat given a folder, need somewhere to run commands, and the server never offers its own machine. A browser session can use:
- A desktop app’s folders. Your signed-in desktop app, online, lends the folders you trusted. In the browser, choose Remote Control in the environment menu above the Code composer and pick the computer, or pick one of its folders under + › Add folder in a new chat.
- A codespace. In Settings › Cloud, people connect GitHub with a personal access token (scopes
codespaceandrepo), or, if an admin sets GitHub OAuth app (the client id of an OAuth app with device flow enabled), with a device code. Then Cloud in the environment menu lists their codespaces. Codespaces have not been verified against a real account.
Without either, a browser can still use Chat (including its sandbox), but Code has no folder to open: its start page says “Open the desktop app to work in a folder on your computer, or use a codespace.”
Data, backup and restore
Section titled “Data, backup and restore”Everything is in the data folder (/data in the image): the SQLite database, attachments and files, settings.json, the
secrets key. Back up the atelier-data volume with the server stopped. The exact commands, what to keep together, and how
to restore are in Data and files.
Updating
Section titled “Updating”Settings › Admin › Server shows the server’s version, and the newest one it knows of (“Atelier 0.1.10 is
available.” or “Up to date. Checked 2 minutes ago.”). The newest version comes from stable/latest.yml on the public
update feed, or, with ATELIER_UPDATES_REPO set, the newest non-draft, non-prerelease GitHub release of that repository.
The answer is cached for 10 minutes; Check now skips the cache. The server asks only when an admin opens the page or
presses Check now; with no internet it keeps showing the last version it saw.
What the page offers depends on how the server was installed:
| Install | What Settings › Admin › Server does |
|---|---|
The Compose file with the updater service |
Update server pulls the new atelier and sandbox images and recreates those two containers. A bar shows how much of the new version is down (“40% · 120 MB of 300 MB”), then the restart. Everyone is disconnected for a minute or so and reconnects by themselves; replies being written stop. Your volumes are kept. |
| Compose without the updater | Shows the command to run on the host, in the folder with compose.yaml: docker compose pull && docker compose up -d. |
| An image built from source (no registry name) | “This server was built from source; update it by rebuilding its image.” |
Desktop apps and open browser tabs say so when their version and the server’s differ; the messages are in Updates.
Back up before updating. Database migrations run when the new version starts and only move forward; Atelier has no rollback, and does not stop an older version from opening a database a newer one has migrated.
The updater service
Section titled “The updater service”A container cannot replace itself, so the Compose file has a small optional service, updater. It gets the Docker socket,
which is root on the host, so it is deliberately limited:
- It answers only
GET /statusandPOST /update, on the Compose network (port 7341, not published). - Both need a secret the server makes on first use in the
updater-secretvolume (mode 0600; the updater mounts it read-only). It is never in an environment variable or a committed file. - An update runs
docker compose pullanddocker compose up -d --no-depsfor theatelierandsandboxservices of the updater’s own Compose project, using the Compose file and.envfrom the folder mounted read-only at/project. Nothing in a request names another command, image, service or project. For the progress bar it first reads the images’ layer sizes from the registry (docker manifest inspect); when that fails or takes over 20 seconds, the bar estimates the layers that haven’t started. - The server itself never gets the socket.
If that trade is not for you, delete the updater service and ATELIER_UPDATER_URL from the Compose file; everything
else works, and the Server page shows the manual command. Things to know:
- It updates the images the Compose file names. With
:latestthat means the newest; with a pinned tag (:v<version>) it pulls the same tag again and nothing changes. To move a pinned server, edit the tag and rundocker compose up -d. - It does not update itself.
docker compose pull && docker compose up -don the host updates it with the rest. An updater from before 0.7.1 shows no progress bar, only the last line Docker printed, until it is updated this way. - With private images, the updater needs a registry login: mount the host’s
~/.docker/config.jsonat/root/.docker/config.json:ro. - A server on host networking cannot reach
http://updater:7341. Publish the updater on loopback only (ports: ['127.0.0.1:7341:7341']) and setATELIER_UPDATER_URL=http://127.0.0.1:7341. - When it cannot do its job, the Server page says why: “The updater refused this server’s secret: both must mount the
same
updater-secretvolume.”, “The updater can’t be reached at …”, “The updater found noatelierservice in its compose project.”, “The compose file … is outside the project folder the updater can see.”
Serving desktop updates from your server
Section titled “Serving desktop updates from your server”Desktop apps connected to your server can update from it instead of from Atelier’s public feed. Set both:
ATELIER_UPDATES_REPO: your-org/atelier-builds # owner/repo whose Releases hold the desktop buildsATELIER_UPDATES_TOKEN: github_pat_... # fine-grained, Contents: read-only on that repositoryThe server then serves electron-updater’s feed at /updates/stable/ and /updates/beta/, mirroring the files of that
repository’s newest release (stable skips prereleases, beta includes them, drafts never count). The release list is cached
for five minutes, and only signed-in people get files. The log says “Serving desktop updates from GitHub releases”.
- Both variables are required. With only
ATELIER_UPDATES_REPO, the feed answers 404: “This server has no update feed: set ATELIER_UPDATES_REPO and ATELIER_UPDATES_TOKEN to serve one.” (To signed-out callers it answers 401.) A desktop app that gets a 404 from its server falls back to Atelier’s public feed. - Every package needs a signature. Apps install only packages with a valid
<file>.signext to them, made with the key whose public half is built into the app (see Updates). The release workflow creates them when the repository has theUPDATE_SIGNING_KEYsecret; otherwise runnode deploy/cloudflare/sign-release.mjs <folder>on the packages and attach the.sigfiles to the release as extra assets, or the app reports “Atelier … is not signed, so it was not downloaded.” A fork that builds its own apps uses its own key pair; the steps are in Updates. - The repository’s release workflow (
.github/workflows/release.yml) builds the macOS, Windows and Linux packages for eachv*tag and attaches them with theirlatest*.ymlfiles. A tag containing-becomes a prerelease.
Docker without Compose
Section titled “Docker without Compose”The server alone, behind a proxy you run yourself:
docker run -d --name atelier --restart unless-stopped \ -p 127.0.0.1:7340:7340 \ -v atelier-data:/data \ -e ATELIER_BASE_URL=https://atelier.example.com \ -e ATELIER_TRUSTED_PROXIES=<your proxy's address as the container sees it> \ -e ATELIER_SECRET_KEY=<64 hex characters or base64 of 32 bytes> \ ghcr.io/theoriuhd/atelier:latestWithout the other services there is no chat sandbox and no Update server button; update with docker pull and
recreate the container. To see your proxy’s address as the container sees it, open Settings › Account › Active sessions: the IP address
column shows it.
Running from source
Section titled “Running from source”You need Node.js 24 or later and pnpm.
pnpm installpnpm --filter @atelier/ui buildpnpm --filter @atelier/server buildnode apps/server/dist/server.mjs # http://127.0.0.1:7340, data in ./.atelier-data- It listens on
127.0.0.1:7340and keeps data in.atelier-datain the current directory unless you setATELIER_HOST,ATELIER_PORTandATELIER_DATA_DIR. SettingATELIER_HOSTto anything but loopback logs “Listening on … Put Atelier behind HTTPS (a reverse proxy such as Caddy) before exposing it beyond your machine.” - The web app is found next to the source tree;
ATELIER_UI_DIRpoints elsewhere. Without a build the server serves only its API. - For codespaces, build the runners (
pnpm runner:build, needs Go) and setATELIER_RUNNER_DIR=runner/bin. Chat’s sandbox needs the Compose setup. pnpm dev:webrebuilds and restarts the server as you edit.- Keep it running with whatever you use for services. A minimal systemd unit:
[Service]User=atelierWorkingDirectory=/opt/atelierEnvironment=ATELIER_DATA_DIR=/var/lib/atelier ATELIER_HOST=127.0.0.1EnvironmentFile=/etc/atelier.envExecStart=/usr/bin/node apps/server/dist/server.mjsRestart=on-failureAn install from source has no ATELIER_IMAGE, so Settings › Admin › Server tells you to update by rebuilding it.
Sizing and limits
Section titled “Sizing and limits”Atelier does not publish measured requirements. What is known:
- The server itself is light: one Node.js process and a SQLite database; the models run on other machines. Memory and CPU grow with the number of people active at once and with long conversations.
- Disk is the thing that grows. Conversations, attachments, tool outputs and file versions for Rewind (30 days by
default) accumulate in
/data. Settings › Privacy can delete old conversations per person. Thesandbox-homevolume grows with the repositories chats clone. - Containers in the Compose file: the sandbox is capped at 2 CPUs, 2 GB and 512 processes, the updater at 256 MB. The server has no limit.
- One data folder, one process. Do not point two servers at the same folder: SQLite will wait up to five seconds for its lock and then fail.
- Limits that matter to people: uploads are 32 MB per file (avatars 5 MB); a device can run up to 32 workspaces at once; a session lasts 30 days from last use, but a browser’s cookie ends 30 days after sign-in; an invite code lasts 7 days; 8 wrong passwords for one username from one address, or 8 wrong invite codes from one address, in 15 minutes are refused for a while; temporary chats that nobody left open are removed after a day.
Hardening checklist
Section titled “Hardening checklist”- HTTPS in front, with
ATELIER_BASE_URLset to the exact public address. AddStrict-Transport-Securityat the proxy. -
ATELIER_TRUSTED_PROXIESset to your proxy only. -
ATELIER_SECRET_KEYset, kept in a secret store, and not stored in the backup it protects. - Sign-up left on Invite only unless you want strangers able to request accounts.
- Each identity provider limited to the people it should let in, or left on Create an account an admin approves.
- The first admin created, and a second admin added, so that losing one account does not lock you out of administration. The last admin cannot be demoted, disabled or deleted.
- Port 7340 not published to the internet: only the proxy is.
- Backups tested by restoring them.
- Docker’s
updaterservice kept only if you accept the Docker socket trade-off. - Image tags pinned if you want to decide when updates happen.
- Providers’ keys scoped and spend-limited at the provider; everyone on the server shares them.
- Admin account sign-ins reviewed under Settings › Account › Active sessions.
- Consider putting the
sandboxcontainer on a network of its own: by default it shares the Compose network with the server and can reach it.
Troubleshooting a server
Section titled “Troubleshooting a server”| Symptom | Cause and fix |
|---|---|
| The page loads and then spins | The live connection is refused. Check ATELIER_BASE_URL against the address in the browser’s bar, and that the proxy passes WebSockets. See what breaks. |
| Sign-in works and you are signed out at once | The browser blocks cookies for the site. |
| “Too many attempts. Try again in a few minutes.” | 8 failures for one username from one address in 15 minutes. Wait, or check that ATELIER_TRUSTED_PROXIES is set so one person’s failures do not count against everyone. |
| The container exits at start with “ATELIER_SECRET_KEY must encode 32 bytes (hex or base64)” | The key is not exactly 32 bytes. Generate one with openssl rand -base64 32. |
It exits with ATELIER_TRUSTED_PROXIES: "…" is not an IP address or CIDR range. |
One entry is a hostname or has a typo. |
It exits with ATELIER_UPDATES_REPO must be owner/repo |
The value has a different shape. |
It cannot write /data |
The volume or bind-mounted folder must be writable by the container’s atelier user (docker compose exec atelier id). |
| “UI build not found; serving the API only” in the log | ATELIER_UI_DIR points at a folder without a build. |
| No setup token in the log | The server already has an account, so none is printed. There is no command-line password reset: another admin resets a forgotten password in Settings › Admin › Users, and a passkey still signs you in. If the only admin forgot the password and has no passkey, the app offers no way back in, so keep a second admin. |
| Chats say they have no sandbox | ATELIER_SANDBOX_HOST is not set, or the sandbox service is down. docker compose logs sandbox. |
| Chats say “The sandbox can’t be reached: … Permission denied” | The sandbox container is older than the server (update both), or it refused the account’s user because the server gave it to a different account than before (docker compose logs sandbox says which; see the chat sandbox). |
| Chats say “The sandbox has no free account left” | Every user of the sandbox is taken; raise ATELIER_SANDBOX_SLOTS on both services. |
| “This app has no runner builds to put into a codespace.” | ATELIER_RUNNER_DIR is not set (only from source; the image sets it). |
| Update server is missing, or the page says “This server has no updater service.” | The button appears only when a newer version exists and the updater answers. Otherwise ATELIER_UPDATER_URL is not set, or the updater is down. |
| A desktop app says “The server doesn’t offer updates for this computer yet. Its admin sets them up with ATELIER_UPDATES_REPO.” | The server’s feed is off (it answers 404) and the app has no public feed to fall back to (ATELIER_UPDATE_FEED=off on the desktop). See Serving desktop updates. |
| A desktop app cannot connect | See Troubleshooting. |
Look at the server’s log first: docker compose logs -f atelier. It is mostly one JSON object per line, with level,
message and sometimes error.