Skip to content

Get started

Atelier is a workspace for language models. Its two modes share one set of conversations, settings and models:

  • Chat for conversations, with artifacts, projects, attachments, memory and web search, and for longer tasks that end in files you can open, worked through in a sandbox of the chat’s own or in a folder you give it. See Chat.
  • Code for an agent that works in a repository: it reads and edits files, runs commands in a terminal and shows its changes as diffs, under the permission rules you choose. See Code.

It runs on the models you choose: a local server such as Ollama or llama.cpp, a hosted API with your own key, or a ChatGPT, GitHub Copilot or Mistral Vibe plan you already pay for. No model comes with Atelier.

There is one backend with two ways in. The desktop app (macOS, Windows and Linux) can run the backend inside itself or connect to a server. The web app is the same interface in a browser, served by an Atelier server you host (Self-hosting). There is no Atelier cloud; your conversations stay on the machine that runs the backend. Atelier is in beta; macOS is the most tested platform, Windows and Linux less so.

Download it from atelierhq.dev/download; the install guide has the details for each system. If someone gave you an Atelier server’s address, you don’t need to install anything: open it in a browser, or choose Connect to a server in the desktop app. Prefer the terminal? Atelier CLI is a Code session there, with a server or on its own.

The first time the desktop app opens, it asks Where should Atelier keep your chats?

Choice What it means
Run on this computer Atelier runs its own backend here; chats and settings stay on this computer. Pick this to try Atelier or to use it alone.
Connect to a server Use an Atelier server, for example in your home lab, and sign in with your account there. Your chats live on the server, which you can also open from a browser.

Either way the desktop app can open folders on this computer for Code and for chats. In a browser there is no such choice: you open your server’s address and sign in.

Atelier starts its own backend inside the app and asks one thing: What should Atelier call you? Type your name and choose Continue. There is no password, because only the app itself can reach this backend. You can add a PIN or password as a screen lock later in Settings › Account (see Security).

Being “the owner” on this computer means:

  • You are the first account on this backend, which makes you the admin: the sidebar shows “Admin” beside your name, and Settings has an Admin group (listed below).
  • Your chats, settings and memory are in ~/.atelier on this computer, and your provider keys are encrypted with the operating system’s secure storage. See Install.
  • There is no sign-in to manage: Settings › Account has no password, sessions or devices, Log out becomes Lock Atelier, and Setup lets you switch to a server later.

Choose Connect to a server and type the address in Server URL. The field accepts atelier.example.com, 192.0.2.20:7340 or a full URL.

  • Without https://, Atelier tries https:// first and, if nothing answers within 4 seconds, plain http://. Plain http:// is only accepted for this computer, your local network and Tailscale (*.ts.net); any other server must use https://.
  • With a scheme typed, that exact address is used.
  • If nothing answers, you get “No Atelier server answered at …”. Check the address and that the server is running.

Found on your network lists Atelier servers that answered on this computer or its local networks (port 7340, within about 3 seconds), with address and version; click one to connect. Most people use the field above instead. On a Mac, the first time you connect to a server on your network, macOS asks whether Atelier may find devices on your local network. Allow it, or Atelier can’t reach the server (see Troubleshooting).

Then sign in on the server’s screen:

  • Sign in with your username and password, or Sign in with a passkey in a browser.
  • I have a code if an admin gave you an invite code: enter it, then your name, username and password.
  • Create an account appears only when the admin opened sign-up; the account waits for an admin to approve it.
  • On a brand-new server you create the first account, the admin, with the one-time setup token from the server’s log (see Self-hosting).

A desktop connected to a server lends the folders you open to that server’s sessions, which then run commands on this computer as you. See Accounts for roles and sign-in, and Security for what a lent folder allows.

Nothing you choose here deletes anything. Before sign-in, Use a server instead (on this computer) or Change server goes back to the choice. Afterwards, Settings › Connection switches between this computer and a server, or to another server; the profile menu at the bottom of the sidebar opens it too. Your chats on this computer stay where they are; switch back to get back to them.

Only admins connect providers. A new install opens on the Chat home like any other day; the model menu under the message box says Choose a model and offers Add a provider, which opens Settings › Admin › Providers. There Atelier lists what it found by itself:

  • Local servers on their usual ports: Ollama on 11434, llama.cpp on 8080 and LM Studio on 1234. Only an answer in the server’s own shape counts, so another app on the same port isn’t mistaken for a model server.
  • API keys in the environment: ANTHROPIC_API_KEY and OPENAI_API_KEY. Atelier sees only the environment it was started with. An app opened from the Dock or a launcher doesn’t read your shell profile (only its PATH), so a key exported in ~/.zshrc alone won’t be found; start Atelier from a terminal, set the variable system-wide, or add the provider by hand.

The scan runs on the machine that runs the backend: your computer in “Run on this computer” mode, the server when you are connected to one.

Press Set up next to what it found: the provider’s form opens filled in, and Add provider tests and saves it. A key found in the environment is copied into Atelier’s encrypted secret store, and only a masked ending is shown afterwards. Scan again looks again. Once a provider is there, its first model is chosen in the model menu until you pick another. If Ollama runs but has no models, pull one (for example ollama pull qwen3) and try again.

Add provider on the same page offers the full list:

Provider What you need Notes
Ollama Ollama running, default http://localhost:11434 No key.
llama.cpp llama-server running, default http://localhost:8080 No key. For tool calls start it with --jinja, or switch the model to prompted tools.
OpenAI-compatible A base URL (default http://localhost:1234/v1, LM Studio’s) and a key if the server asks LM Studio, vLLM or any server with an OpenAI-compatible API.
Anthropic An API key Claude models through the Anthropic API.
OpenAI An API key GPT models through the OpenAI API.
Mistral An API key from Mistral’s console, with billing on Mistral’s models, priced per token. For EU-only processing, change the base URL to https://api.eu.mistral.ai.
Mistral Vibe A Le Chat Pro or Team plan and a key for Vibe Create the key in Le Chat under Code › Vibe CLI and paste it; uses the plan’s Vibe allowance instead of per-token billing. On a server, everyone using the provider spends the admin’s plan.
ChatGPT Plan A ChatGPT plan; you sign in Uses your plan’s limits instead of per-token billing. Unofficial. Desktop on this computer: your browser opens. On a server: a one-time code to enter on OpenAI’s page within 15 minutes, and everyone using the provider uses the admin’s plan.
GitHub Copilot A Copilot plan; you sign in with GitHub A code to enter at github.com/login/device; counts against the plan’s allowance. Unofficial.
ChatGPT Chat A ChatGPT account Experimental. ChatGPT itself, driven through a signed-in browser window. Desktop app only: on a server, each person adds it as their own model from their desktop app.
OpenRouter An OpenRouter account or key Connect with OpenRouter creates a key for you. Models marked free are limited to 50 requests a day (1,000 once you have bought 10 credits).
OpenCode Zen An OpenCode Console key Billing may be required; its free models may only work inside OpenCode itself.

Providers covers every field, Local models the local servers, ChatGPT the two ChatGPT options, and Models how models are listed, hidden and overridden.

Settings › Admin › Providers, with a detected provider, a connected Ollama server and Add provider

If you are not an admin, the model picker says “No models available” and “Ask an admin to connect a provider.”

Choose New in the sidebar (⌘N or Ctrl+N), type in the message box and press Enter; Shift+Enter starts a new line. The model picker and effort setting are at the bottom right of the box.

A Chat answering a question with a comparison table

  • While you have fewer than five chats, ideas under the box fill it with an example prompt.
  • Attach images, PDFs and text files by dropping or pasting them, with ⌘U or Ctrl+U, or from the + menu.
  • Research in the + menu is a per-conversation switch, off by default: each message then searches broadly and cites its sources. Plain web search is on from the start (see Web search).
  • The ghost button at the top right starts a temporary chat that never appears in your history.
  • Something a reply builds (a page, component, diagram or document) opens in a panel beside the conversation; see Artifacts.

Hover a message to copy it, retry a reply or edit your own message; the earlier versions stay, one click away.

  1. Choose the Code tab at the top of the sidebar, then New.

  2. Above the message box, the folder chip says No folder until you open one (Select folder… when the desktop app is connected to a server). Open it and choose Open folder…. If the folder is inside a Git repository, Atelier works in the repository’s top level.

  3. When a folder is new to your list, Atelier asks Trust this workspace? Its agent may read, write or run commands there, as you, so choose Trust workspace only if you trust what is in the folder.

  4. Pick how much it may do with the mode at the bottom left of the box. Auto mode is the default.

    Mode What it does
    Auto mode The model reviews each action that would ask, in a separate request, and blocks risky ones.
    Ask permissions Asks before editing files or running commands.
    Accept edits Edits without asking, still asks before commands.
    Plan mode Reads and plans only; changes wait until you approve the plan.
    Bypass permissions Never asks, not even for risky commands.

    Shift+Tab, with the message box empty, cycles Auto, Ask, Accept edits and Plan. Auto mode reduces prompts; it does not replace review of sensitive work. See Permissions.

  5. Describe a task and press Enter. When something needs your approval you choose Deny, Allow once, or Always allow (for this project; the arrow beside it offers this session or everywhere).

  6. Open the Diff pane (and Terminal, Browser, Files; the Browser is in the desktop app only) from the buttons at the top right to review what changed, commit, or reject a single hunk. More has Background tasks, Plan, Artifact and Side chat.

A Code session asking permission before running a git commit

No folder (first in the folder menu in the desktop app, on this computer or connected to a server) gives each new session an empty folder of its own, a safe way to try Code. In a browser, Code works in a folder lent by one of your desktop apps or in a GitHub codespace; the server never runs commands on its own machine. See Code.

A chat that is asked for a piece of work (a document, a spreadsheet, sorting files, reading a stack of PDFs) works through it as a task.

  1. Choose New in the Chat sidebar. To work on files you have, pick their folder with + › Add folder before you send; the first time, Atelier asks Trust this workspace?. Without a folder, the chat works in a sandbox of its own.
  2. Describe the result you want and press Enter.
  3. Watch its steps. Its to-do list and the files it writes appear beside the conversation once there are some, and it ends with cards for the files it wrote, each with Open.
  4. Turn on Notify me when a task finishes and Notify me when a task needs me in Settings › General to get a system notification while you are in another window.

The chip at the bottom left of a chat’s message box sets what asks you first: Auto mode, Ask permissions, Accept edits or Bypass permissions. It starts at the default mode from Settings › Admin › Code (Auto, unless an admin changed it). See Tasks.

  • The header has the sidebar toggle (⌘B) and two tabs, Chat and Code.
  • Search (⌘K) finds chat titles and message text, and offers actions such as a new chat.
  • In Chat: New, Projects, Artifacts, Customize (skills, connectors and plugins) and More (Settings, Usage, Keyboard shortcuts), then pinned items and your recent chats by day. In Code: New, Customize, More, then your sessions by folder.
  • At the bottom: your name with “Admin” or “Member” and a menu (Settings, theme, Lock Atelier or Log out).
  • A line above the profile shows an update’s download progress, then Restart. See Updates.
  • The + button opens Upload or add files, Add folder (on a new conversation), Skills, Connectors (switch them on or off for this conversation), Add plugins (admins) and Research. / lists commands and skills, and @ mentions a file in Code. See Shortcuts.
  • The model picker lists the visible models by provider.
  • The effort control (⌘⇧E or Ctrl+Shift+E) sets how hard the model works. Every model has the same stops (Low, Medium, High, Extra, Max), starting at the one marked Recommended for that model; ChatGPT Chat takes the stops of ChatGPT’s own picker. Higher stops think and check more, take longer and use more tokens; Max warns that it uses about 3.5 times more. In Code the last stop is Ultracode, where the model plans and has sub-agents investigate and check in parallel; an admin can switch it off. Models that can only turn thinking on or off get a Thinking switch in the same popover. See Effort.
  • The context ring shows how full the model’s context window is. Click it for the figures and your usage: the cost on a priced hosted API, for a ChatGPT Plan the plan’s own limit windows, for Mistral Vibe its monthly allowance. In Chat older messages are summarized automatically before it fills; in Code the popover also shows what fills the window, the session’s tokens, and Compact session.

Open Settings with ⌘, (Ctrl+, elsewhere), from More, or from the profile menu. The search box finds any setting by name. The pages in the Settings group are for everyone:

Page What it is for
General Theme, chat font, transcript text size and width, motion; your own Default model for new chats; task notifications.
Computer use (desktop app only) Enable computer use, how the assistant uses the apps you allow, the apps allowed for good, and Atelier for Chrome. See Computer use.
Account Your photo, name, what Atelier calls you, personal Instructions, Personality, Response style and Your ATELIER.md. On this computer also Screen lock and Setup; on a server your password, passkeys, active sessions, devices, Remote control and Log out.
Privacy Keep conversations (automatic deletion after a number of days), Temporary chats, Export your data, Delete all conversations.
Memory What Atelier remembers across chats, and whether it may. See Memory.
Usage Requests, tokens and cost by day, mode and model.
Code Permission rules you approved with Always allow, code appearance and font, the default transcript view, the interface font, and the commit author.
Folders The folders you opened for Code and chats, and your SSH connections.
Cloud Your GitHub connection and the codespaces that become folders.
Skills The skills sessions can use, and installing them from GitHub (admins).
System (desktop app only) The version, updates (Check now, Check for updates automatically and the update channel), Launch at login, and the Data folder.

The Admin group appears only for admins: you, on this computer; whoever has the admin role, on a server. Users and Server matter mainly on a server; the server’s version and Update server appear only there.

Page What it is for
Providers What was detected, and adding, editing, disabling or removing providers.
Models The Default model for everyone, the Small model that writes titles, summaries and memory, every model with its overrides, and aliases for agent files that ask for opus, sonnet, haiku or fable.
Capabilities Web search and web fetch, Instructions for every conversation, hand-editing memory, and extra safeguards.
Code The default permission mode, allow, ask and deny rules, additional directories, Ultracode, Claude Code compatibility, hooks, how long checkpoints are kept, and the system AGENTS.md.
Connectors MCP servers that give sessions tools from other services, and each tool’s permission (Always allow, Ask or Block).
Plugins Installed plugins and adding marketplaces.
Keys & secrets The API keys and tokens Atelier stores encrypted.
Users People, approvals for self sign-ups and invite codes.
Server The server’s version, Update server, and the sign-up policy.
Developer The request inspector, connector logs and a reload.

Every setting, with its description, is listed in Settings reference.

Atelier has no telemetry: no analytics, no crash reports, and nothing that sends your chats, settings or keys to its makers. What it does send:

  • Model providers and connectors you set up receive what you send them. A local model on your own machine receives it there.
  • Update checks (desktop app). At start and every 5 minutes the desktop app asks updates.atelierhq.dev for the newest version’s update file. Connected to a server whose admin set up updates, it asks that server first. Settings › System › Check for updates automatically turns this off, and Check now still looks. See How do I stop Atelier from checking for updates?
  • Web search and web fetch, on by default. A search sends its query text to search engines (the built-in search tries DuckDuckGo, Brave and Bing in turn, and Wikipedia when they refuse; news searches also go to Bing News and Google News, programming searches to Stack Overflow, Hacker News and GitHub), and the first result pages are fetched from your computer, or from the server. Settings › Admin › Capabilities turns them off or points them at your own SearXNG, Brave Search or Tavily.

Details are in What leaves your machine, Web search and Updates.

The docs home has three reading orders: getting productive, building with agents, and running your own setup. Every page, by topic:

Start here: Install · Providers · Models · Local models · ChatGPT

Using Atelier: Chat · Artifacts · Projects · Code · Permissions · Effort · Sessions · Loops · Shortcuts · Web search · Memory

Extend it: Customize · Connectors · Hooks and plugins

Running it: Self-hosting · Accounts · Remote control · Security · What leaves your machine · Data and files · Environment variables · Updates · Troubleshooting

Under the hood: How it works · Claude Code compatibility · Prompts · Settings reference · Tools reference

About: FAQ · License