# Accounts and roles

> How people join an Atelier server, what admins and users can do and see, how sign-in sessions work, and the Account and Users pages control by control.

Every Atelier backend has accounts. On a [server](https://docs.atelierhq.dev/self-hosting/) there are as many as you invite; inside the desktop app
with **Run on this computer** there is exactly one, yours, with no password.

## The first admin

- **On a server**, the first account is created on the sign-in screen with the **setup token** the server prints in its
  log (`docker compose logs atelier | grep setupToken`). That account is the **admin**. The token works only while the
  server has no accounts. See [Run it](https://docs.atelierhq.dev/self-hosting/#run-it).
- **With Run on this computer**, the first screen asks only for your name. Atelier derives a username from it, gives the
  account a random password nobody sees, and signs you in by itself on every start.

## Roles

| Role | Can |
|---|---|
| **Admin** | Everything a user can, plus the **Admin** group in Settings: **Providers**, **Models**, **Capabilities** (web, instructions for everyone, memory editing, content safeguards), **Code** (permission rules and the system AGENTS.md for everyone), **Connectors**, **Plugins**, **Keys & secrets**, **Users**, **Server** and **Developer**. |
| **User** | Their own conversations, projects, memory, files and preferences: **General**, **Account**, **Privacy**, **Memory**, **Usage**, **Code**, **Folders**, **Cloud** and **Skills** in Settings. They see and can use whatever providers, models, connectors and plugins an admin set up, but cannot change them. |
| **Pending** | A person who asked for an account while sign-up was open and waits for an admin. They cannot sign in. |

A server needs at least one active admin. The last one cannot be demoted, disabled or deleted ("This is the only admin.
Make someone else an admin first."), and nobody can change their own role or delete themselves on the Users page.

### What admins can and cannot see

Every request to the backend is scoped to the signed-in account, so the screens for conversations, projects, files,
memory and artifacts show only your own.

What an admin **can** see in Atelier:

- The list of accounts: name, username, role, status and when each was last active.
- **Settings › Usage › Everyone**: requests, tokens and cost by day, provider, model and mode, added up across all
  accounts. It is not broken down by person.
- Which settings and connectors use a stored secret (**Keys & secrets**), though never the secret's value.
- **Settings › Admin › Activity**: who signed in (and failed to) from which address, and which admin changed what. See [the activity log](#the-activity-log).
- **Developer**: each connector's log, and, only while **Record provider requests** is on, the web address, status,
  timing and size of the requests the server sent to model providers, with credentials masked. Prompts and replies are
  never recorded there. It is not attributed to people.

What an admin **cannot** do in the app: read, search or open another person's conversations, memory or files; or see
another person's personal GitHub token or saved SSH passwords (these are hidden from admins).

What an admin **can** do to a person: reset their password. Whoever signs in first with the temporary password chooses
the new one, so an admin can take over an account and read what is in it. The person notices, since they are signed out
everywhere and their old password stops working, but it is possible. Likewise anyone who runs the server's host can read
the database. Treat admins as people you would trust with that, and see [Security](https://docs.atelierhq.dev/security/) and
[What leaves your machine](https://docs.atelierhq.dev/privacy/#who-can-see-what).

Admins also shape what models are told: **Instructions for every conversation** and the system **AGENTS.md** apply to
everyone, and **Content safeguards** can be switched on for everyone or per person.

## Adding people

There are three ways, and you can use all of them together.

### Invite codes

**Settings › Admin › Users › Create invite code**, then choose the **Role** the new account gets and **Create code**. The
code looks like `A1B2-C3D4-E5F6-G7H8`. It is shown once, with **Copy**: give it to the person privately.

- It creates **one account** and works **once**, for **7 days**.
- The person opens the server and chooses **I have a code** under the sign-in form, enters the code (**Join with a
  code**), then fills in name, username and password. It signs them in.
- Case, dashes and spaces do not matter. Codes never contain I, L, O or U, so a typed I or L counts as 1 and O as 0.
- The server stores only a hash of the code. The **Invite codes** list shows each open code as `••••-••••-••••-XXXX`
  with its role, creation and expiry, and **Revoke**. Used and expired codes drop out of the list.
- In a desktop app on **Run on this computer**, **Create invite code** only says "Invite codes need an Atelier server",
  because nobody else can reach that backend.

### Sign-up with approval

**Settings › Admin › Server › Sign-up** has two values: **Invite only** (the default) and **Open, with approval**. With
it open, the sign-in screen offers **Create an account**; the person fills in the form (**Request account**) and then sees
"Waiting for approval". The request appears under **Settings › Admin › Users › Waiting for approval**:

- **Approve** makes them a **User**. (Make them an admin afterwards from the role menu.) They sign in with the username and
  password they chose.
- **Reject** deletes the request.

There is no throttle on sign-up requests themselves, so an open server can collect pending requests from anyone who can
reach it. Leave sign-up on **Invite only** unless you need otherwise.

### Add user

**Settings › Admin › Users › Add user** asks for **Full name**, **Username** and **Role** and creates the account at once.
Atelier shows a **Temporary password** once: give it to the person. They sign in with it and are asked to **Choose a new
password** before anything else.

Usernames are 2 to 32 characters: lowercase letters, digits, dots, dashes and underscores, starting with a letter or
digit. Atelier lowercases what is typed. Passwords are 8 to 256 characters and are stored as scrypt hashes.

## The Users page

**Settings › Admin › Users** lists everyone who can sign in:

| Column | What |
|---|---|
| **Name** | Full name and username, with **You** on your own row. |
| **Role** | **User** or **Admin**. You cannot change your own. |
| **Safeguards** | **Default (on)** / **Default (off)** (follows **Settings › Admin › Capabilities › Content safeguards**), **On**, or **Off**, for this person. |
| **Status** | **Active**, **Disabled**, or **Temporary password** (the person has not yet chosen their own). |
| **Last active** | How long ago, or **Never**. |

Each row other than yours has a menu (**⋯**):

- **Reset password…** signs the person out everywhere and gives you a new temporary password, shown once. They must choose
  their own when they sign in with it.
- **Disable** / **Enable**: a disabled account cannot sign in, is signed out at once and shows "This account is disabled.
  Ask an admin to re-enable it." Nothing is deleted.
- **Delete…** removes the account and everything it owns: its chats, projects, files, memory, devices and passkeys. This
  cannot be undone. Usage records stay, no longer tied to a name. Scratch folders on disk are not deleted.

## Usage limits

On a server shared by several people, **Settings › Admin › Limits** keeps one person from using all of a model. Every
limit is off until you set it, and each applies to every person separately, across all of their chats and Code
sessions together (deleted ones too, because the count comes from the usage records, not from the chats).

| Limit | Counts |
|---|---|
| Tokens per day, tokens per 30 days | Input, output and cache tokens of every request, for every model, local ones included. |
| Cost per day, cost per 30 days | Dollars, for requests to models that have a price (Settings › Usage › Prices, or the provider's list price). A model without a price costs nothing here, so limit local models by tokens. |
| Requests per hour | Model requests in the last 60 minutes. Requests still under way count, so starting ten sub-agents at once doesn't get around it. |

A day is a **UTC day**, the same as the image limits, so a daily limit resets at 00:00 UTC whatever time zone the server or
the person is in. "30 days" is today and the 29 days before it; it lets requests through again as the oldest days leave. The
person sees their own times in their time zone on **Settings › Usage › Your limits**, where each limit has a bar.

- **Before every request.** A turn is checked before it starts and again before each model request in it, so a long
  agent turn (and the sub-agents it starts) stops soon after the limit is reached, overshooting by at most the requests
  that were already running. The reply is an error that says which limit, when it resets and which admin to ask. It is not
  retried and does not loop. A `/loop` that finds its person over a limit stops, saying so once.
- **Requests nobody asked for** (titles, suggested replies, memory updates, a page summary) count toward the limits, but
  when the person is over a limit they are skipped without an error: a title falls back to the first words of the message.
- **A warning at 80%.** Passing 80% of a limit shows one line above the message box, once per limit and day (for 30 days
  and requests per hour, again after usage fell back under 80%).
- **Per person.** On **Limits**, the pencil next to a person raises, lowers or lifts any one limit for them, or exempts them
  from all. Admins are limited like everyone else unless you exempt them. The table shows who is near or at a limit.

The desktop app running on this computer has one person, so it does not show the Limits page; limits written in its
settings file still apply.

## Signing in

- **Password**, from the sign-in screen (**Welcome back**).
- **Passkeys**, in a browser, from **Sign in with a passkey**: your device's screen lock or a security key instead of a
  password. They need an HTTPS address with a hostname; they are not offered on IP addresses or in the desktop app. Add one
  in **Settings › Account › Passkeys**.
- **An identity provider**, in a browser, from **Continue with** and its name, when an admin set one up
  (see [Single sign-on](https://docs.atelierhq.dev/self-hosting/#single-sign-on)). Not in the desktop app.
- **An invite code** or **Create an account** (above) for new people.
- The desktop app signs in with a password and keeps the sign-in in the system's secure storage (Keychain, Credential
  Manager, Secret Service). On a computer where Atelier can't use that, it signs you in for the session and says "You're
  signed in for now: This computer has no secure storage Atelier can use, so it can't keep you signed in."

### Signing in with an identity provider

An admin adds a provider such as Authentik, Keycloak or Google in **Settings › Admin › Server › Single
sign-on**. It works in browsers only: the desktop app keeps signing in with a password.

- **You already have an account:** sign in the usual way, in a browser or the desktop app, and press **Connect** and the
  provider's name in **Settings › Account › Connected sign-ins**, once. The desktop app opens the provider's sign-in in a
  small window; some providers, such as Google, refuse those, and **Open in browser** takes you to the same section there.
  After that **Continue with** signs you in to that account in a browser.
- **You don't have one:** what happens is the admin's choice for each provider: **Create an account an admin approves**
  (the default), **Create an account right away**, or **Turn them away**. A new account gets its name from the provider
  and a username from your username or email address there, with a number added when that one is taken.
- **The same name doesn't connect anything.** Atelier matches the provider's permanent id for you, never your username
  or email address, so someone who gets the name `ada` at the provider gets an account of their own and not Ada's. That
  is why an existing account has to connect the provider itself.
- **An account made this way has no password.** To use the desktop app, press **Set a password** in **Settings ›
  Account**. Without one, an admin's **Reset password** gives you a temporary one too.
- **Disconnecting** is refused when it is your only way in: set a password or add a passkey first. When an admin removes
  a provider, the connections go with it and the accounts stay.
- **Signing out** ends your Atelier sign-in, not your session at the provider, so **Continue with** may sign you straight
  back in on a shared computer. Disabling someone at the provider stops new sign-ins; a browser that is already signed in
  stays signed in until you disable the account in **Users** or their sign-in expires.

### Sign-in sessions

Each sign-in is a session. A browser holds it in a cookie that scripts cannot read, marked Secure on HTTPS. The desktop
app holds a token in secure storage. Only a hash of the token is stored on the server.

- **Lifetime.** A session lasts 30 days from its last use; each use pushes the end out. A browser's cookie lasts 30 days
  from sign-in and is not renewed, so in a browser you sign in again after 30 days. An expired session stops working at
  once and is deleted when the server next starts.
- **Log out** (**Settings › Account › Account**) ends this sign-in. In the desktop app it also revokes the app's sign-in
  on the server, deletes the saved one and returns to the first-run choice. To use another server or this computer
  instead, see **Settings › Connection** below.
- **Log out everywhere** ends every sign-in of your account, this one included.
- **Change password** keeps you signed in here and signs you out everywhere else.
- A password reset by an admin, disabling or deleting an account, and revoking a session end the sessions concerned at
  once; the open windows show the sign-in screen.

**Active sessions** (**Settings › Account**) lists every browser and app signed in to your account: **Device** (such as
"Chrome on macOS", "Atelier Desktop on Windows" or "Atelier CLI", with **Current** on this one), **IP address**, **Created** and **Last
seen**. **Revoke** signs one out. The IP address is the one Atelier sees; behind a proxy that needs
`ATELIER_TRUSTED_PROXIES` to be the visitor's, not the proxy's (see [Run a server](https://docs.atelierhq.dev/self-hosting/#atelier_base_url-and-atelier_trusted_proxies)).

### Signing in a terminal

[Atelier CLI](https://docs.atelierhq.dev/cli/) signs in through the browser, so it works for every account however it signs in (a password, a
passkey or an identity provider), and on a computer with no browser:

1. The terminal asks the server for a request and shows a code (`K7QF-3MZD`), a link to the server's **`#/link`** page
   and a QR code of it.
2. Signed in on that page, you see which computer asks, from which address and when, compare the code, and **Approve**
   or **Deny**.
3. The terminal's next look gets a sign-in of its own for your account, once. It shows under **Active sessions** as
   "Atelier CLI", like any other sign-in.

A request lasts 10 minutes and its code is 8 letters and digits; wrong codes count against you and your address, and
one address may have only a few requests open. What the page can't stop is someone sending you a code of theirs to
approve: that would sign *their* terminal in as you. Approve only a terminal you just started yourself, showing the same
code. Approvals and denials go into the [activity log](#the-activity-log) (`signin.terminal_approved`,
`signin.terminal_denied`). The terminal can also sign in with a password or an invite code.

### Signing in a phone

The Atelier app for iPhone and iPad signs in with a QR code. In **Settings › Account**, click the QR icon at the right of
the **Profile** heading (**Pair mobile app**); on the phone's sign-in screen choose **Scan QR code**. The phone signs in
as the account on your screen, with no address or password to type, and shows up under **Active sessions** like any other
sign-in. When it has scanned the code, the window turns into a confirmation: "Philipp’s iPhone is logged in!", with the
phone's model and the app's version underneath. The scanner has a flashlight button, and on a phone with several back
cameras a choice of lens for codes that are very near or far.

- **One use, five minutes.** The code works once; a new code ends the one before it, and one person can show 10 in 15
  minutes. The phone's sign-in is the account's own, so it ends with **Revoke**, **Log out of all devices** or a
  password change like any other.
- **Show it only to your own phone.** Whoever scans it before it runs out signs in as you. Showing a code goes into the
  [activity log](#the-activity-log) (`signin.pair_shown`).
- **Which address.** On a server, the code holds the address you opened Atelier at. Opened as `localhost` a phone can't
  reach it, and the page says so. In the desktop app it works while **Share on your network** is on (see
  [Connection](#settings--connection)); the code then holds the computer's network address, and the phone signs in
  for the account that shares it.

### Rate limits and lockouts

- **Wrong passwords:** after 8 failures for the same username from the same address within 15 minutes, further attempts
  are refused with "Too many attempts. Try again in a few minutes." (HTTP 429), whether or not the password is then right.
  The count is kept in memory, so restarting the server clears it.
- **Wrong invite codes:** the same limit, counted per address.
- **Unknown usernames** cost the same time as wrong passwords, so the sign-in screen does not reveal which usernames exist.
- **The screen lock** on a computer running its own backend has its own limit: 5 wrong tries, then waits of 30 seconds
  doubling up to an hour, also across restarts. See [Security](https://docs.atelierhq.dev/security/#screen-lock-on-this-computer).

## The activity log

**Settings › Admin › Activity** is an append-only record of who changed what on a shared server. Only admins see it, and
only on a server: a desktop app running its own backend has one person, so it records nothing and has no such page.

What it records, newest first:

- **Sign-ins**, with the username, the time and the address as the server saw it, and failed ones with the name that was
  tried and why (unknown username, wrong password, disabled account, waiting for approval). A run of failures that hits
  the [rate limit](#rate-limits-and-lockouts) shows as one **blocked** entry, not one per attempt. No password is ever
  written.
- **Accounts:** created (by an admin, an invite, open sign-up or single sign-on), disabled, enabled, approved, role
  changed, password reset, deleted. **Invites** created, revoked and used.
- **Settings:** the path and who changed it. A small value that is not a secret, such as a switch, a number or a short
  word, is kept as old → new; anything else is recorded as changed without its value.
- **Providers** (text and image) added, changed and removed; **secrets** created, replaced and deleted by their id,
  never their value; **connectors**, **plugins** and **skills** installed, changed and removed; models **hidden** and
  shown; **limits** changed; **server updates** started; and each **export** of this log.

Each row opens to show everything it carries. Filter by type, by person (events by them or about them) and by date;
older events load as you scroll. **Export JSON** saves everything the filters match (at most the newest 50,000) as a
file.

**Keep activity for** sets how long events are kept, from 7 to 365 days (90 by default). Older events are deleted once a
day and when the server starts. As a safety net against a flood of failed sign-ins from many addresses, the log also
never holds more than 500,000 events: the oldest go first.

What it is not: it holds no conversations, prompts, file contents or passwords, and it is not tamper-proof. It is a table
in the server's database, so anyone who runs the server's host can change it, as they can everything else. A change made
by editing `settings.json` on disk, not through the app, is not in it. Writing never holds anything up: if an event
can't be written, the change itself still goes through and the server logs that it could not be written.

## Settings › Account

On a server (in a browser or in a desktop app connected to one), top to bottom:

| Section and row | What it does |
|---|---|
| **Profile › Profile photo** | **Upload** / **Change** / **Remove**. PNG, JPEG, GIF or WebP, up to 5 MB. |
| **Full name** | Shown in the sidebar and to admins. |
| **What should Atelier call you?** | Used in greetings and shared with the model. Your full name is used when empty. |
| **Instructions** | Preferences the model keeps in mind, added to the system prompt of every new chat (up to 20,000 characters). |
| **Personality** | A style preset for new conversations, or your own **custom mode** (**Add custom mode**, **Edit mode**, **Delete mode**: up to 20, each with a name and up to 4,000 characters of style instructions). Style only, not a different model. |
| **Response style** | **Default**, **Concise**, **Explanatory** or **Formal**. |
| **Content safeguards** | Appears only when an admin switched safeguards on for you: "On, set by your administrator", with what they cover. Read-only. |
| **Instructions for Code and tasks › Your ATELIER.md** | Your own conventions for Code sessions and chats in a folder, and their sub-agents, in Markdown (up to 60,000 characters), saved on the server so it works from every device. Where a project's ATELIER.md disagrees, yours wins. |
| **Session access › Remote control** | On by default. Whether your other browsers and devices can open this account's conversations. See [Remote control](https://docs.atelierhq.dev/remote-control/). |
| **Account › Username** | What you sign in with. Fixed. |
| **Password › Change password** | Asks for the current password and a new one (8 characters or more). On an account made through an identity provider it says **Set a password** and asks only for the new one. |
| **Log out** | See above. |
| **Log out of all devices › Log out everywhere** | Ends every sign-in, after confirming. |
| **Passkeys** | Browser only. **Add passkey** names it and asks your browser where to keep it. The list shows **Name**, **Added** and **Last used**; removing one here does not delete it from your device or password manager. |
| **Connected sign-ins** | When the server has identity providers. **Connect** and the provider's name goes through its sign-in and back here; in the desktop app that happens in a small window, with **Open in browser** for providers that refuse one. The list shows **Provider**, **Signed in as** and **Last used**. |
| **Devices** | Computers running the Atelier desktop app for your account: **Name**, **Platform**, **Added**, and **Online** or when last seen. **This computer** marks the one you are on; the others can be removed. |

On **Run on this computer** the page is shorter, because there is no sign-in to manage: **Profile**, **Instructions for
Code and tasks** and **Screen lock**.

## Settings › Connection

Desktop app only: where Atelier runs. The profile menu at the bottom of the sidebar says it too (**Running on this
computer** or **Connected to atelier.home**) and opens this page.

| Option | What it does |
|---|---|
| **This computer** | Atelier runs its own backend here. From a server, **Switch…** and **Switch to this computer** log this app out of the server and reload it on this computer. |
| **An Atelier server** | Enter the server's address, or pick one under **Found on your network**, and **Connect**. The app checks that a server answers there first: if none does it says so and nothing changes. Then it asks you to sign in to the server. On a server already, **Change…** switches to another one the same way. |

Switching deletes nothing: chats on this computer stay here, chats on a server stay there, and switching back brings
them back.

### Share on your network

On **This computer**, **Share on your network** lets your other devices (a phone, a tablet, another computer) use
Atelier on this computer as they would a server: in a browser, or in the Atelier app there under **Found on your
network**. They sign in as you, with your username and a password you choose here, and work in your chats, with your
models and keys, and in the folders you added on this computer. There are no other accounts: everyone who signs in is
you.

| Control | What it does |
|---|---|
| **Let other devices use Atelier here** | Asks for the password (8 characters or more) and a port (7340 unless you change it; Atelier apps look for 7340 on the network), then answers on every network this computer is on. Off signs every device out and closes the port. |
| Addresses | What to open on the other device, local network first (`http://192.168.1.20:7340`), then others such as Tailscale, then the computer's name. Each has a copy button. |
| **Change port…** | Moves it to another port, when 7340 is taken (another program, or an Atelier server on the same computer). |
| **Change password…** | A new password signs every device on the network out. |
| **Sign everyone out** | Ends every sign-in from the network; sharing stays on. |

From the network, Atelier here signs in with the password only (no passkeys, invites or identity providers), and
whatever belongs to this computer stays here: sharing itself, the screen lock, and adding folders. Folders are added at
this computer; the other devices use the ones it has. The screen lock is for whoever sits at this computer: devices on
the network signed in with the password and are not locked out by it. See [Security](https://docs.atelierhq.dev/security/#sharing-this-computer-on-your-network).

If this computer asks whether Atelier may accept incoming connections (macOS, or Windows' firewall), allow it, on
Windows for private networks.

Related pages in Settings: **Privacy**, **Memory**, **Usage** and **General**. See
[What leaves your machine](https://docs.atelierhq.dev/privacy/) and [Data and files](https://docs.atelierhq.dev/data-and-files/).

## Screen lock

On **Run on this computer** only, **Settings › Account › Screen lock** sets a PIN (4 to 8 digits) or a password (6
characters or more) that Atelier asks for when it starts and whenever you lock it: **Lock now** in Settings, or **Lock
Atelier** in the File menu, the sidebar's profile menu and the command palette (⇧⌘L on a Mac, Ctrl+Shift+L elsewhere). **Lock when inactive** can lock after 5, 15, 30 or 60 minutes without
typing or clicking in any Atelier window. What it does and does not protect is in
[Security](https://docs.atelierhq.dev/security/#screen-lock-on-this-computer).

## Devices

When you sign in on a desktop app connected to a server, the app registers its computer as one of your **devices**. A
device lends the folders you trusted on it to your sessions on that server: in a browser, choose **Remote Control** in the
environment menu above the Code composer (or **+ › Add folder** in a new chat), and pick the computer. Devices belong to your account, so a shared
computer shows up once per person who signs in on it. A device shows **Online** while its app is open and linked.
Removing a device from the list forgets it; it registers again the next time its app connects.

The desktop refuses to open any folder you did not pick in its own folder picker, but a trusted folder lets the server's
sessions run commands there as you. See [Run a server](https://docs.atelierhq.dev/self-hosting/#connecting-browsers-and-desktop-apps) and
[Code](https://docs.atelierhq.dev/code/).

## One person on this computer

**Run on this computer** is a single-owner mode. The built-in backend has no network socket; only the app's own windows can
talk to it, and it signs the owner in without a password. You can add accounts under **Settings › Admin › Users**, but
nobody can sign in with them: the app always signs in the owner. If several people need accounts, run a
[server](https://docs.atelierhq.dev/self-hosting/) and connect to it.

<!-- screenshot: Settings › Admin › Users with the invite codes list and the row menu open -->
