A local-first multi-agent app development platform, built on PenguinHarness
title: Settings description: Manage your profile, preferences and password, and, as an admin, users, the proxy, upload limits, company mode, the Agent API and plugins.
Settings is one dialog for the settings that belong to neither a Project nor an agent: your profile, your interface preferences and password, and, for an admin, the server's users, proxy, upload limits, company mode, Agent API and plugins, the sandbox among them.
- Your own settings: Profile, General, Appearance, Keyboard shortcuts and Account.
- Server settings, for admins: Users, Proxy options, Upload limits, Company mode, Agent API and Plugins.
Open Settings
- At the bottom of the sidebar, select your user row, or your avatar when the sidebar is collapsed. The account menu opens.
- Select Settings.
How the dialog is organized
The dialog shows a rail of pages on the left. Each page is a list of rows, with the title on the left and the control on the right. On a narrow screen the rail becomes a horizontal strip above the page.
The rail is grouped into Personal and Server:
| Page | Group | Who sees it |
|---|---|---|
| Profile | Personal | Everyone |
| General | Personal | Everyone |
| Appearance | Personal | Everyone |
| Keyboard shortcuts | Personal | Everyone |
| Account | Personal | Only where a password exists to change |
| Users | Server | Admin only, and not in the desktop app |
| Proxy options | Server | Admin only |
| Upload limits | Server | Admin only |
| Company mode | Server | Admin only |
| Agent API | Server | Admin only |
| Plugins | Server | Admin only |
Personal preferences apply the moment they are touched. There is no Save button and nothing to lose by closing the dialog. The nickname on the Profile page is the one exception: typed text needs a commit, and its Save sits beside the field rather than under the page.
Where your personal preferences are stored:
- In this browser: language, currency, notifications, theme, terminal theme, font size, accent, the shortcuts launcher, and tool short names.
- With your account on the server: your profile, your keyboard shortcuts and your personal Company mode switch.
The Server pages are admin-only and server-global. A non-admin sees neither those entries nor any hint that they exist: they are left with the Personal pages alone, and the rail draws no group headings at all.
In the desktop app the Users page is absent, because the server runs single-user. The desktop app's own window also has no Account page: it signs in through the shell's token and holds no password to change. A browser signed into the same server with a password keeps the page.
A "?" beside a row's title opens that row's explanation. A "?" beside a page heading explains the whole page.
Checking for updates is not a page here. See Updates.
Profile
The Profile page holds your Avatar and Nickname. It is personal and appears in every session, including the desktop app's own window, because neither field needs a password to change.
The page has no footer. Every control writes when it is used, and the button that writes a value stands next to that value.
Both fields start unset. Until you set them, your account shows your user id and a letter tile on the sidebar's bottom user row, on the collapsed rail's avatar, and at the head of the account menu they open.
Once set, your avatar and nickname replace that pair in all three places. Your user id stays visible under the nickname at the head of the account menu. The nickname also shows under the id in the Users list.
Change your avatar
Before you begin
- An image in PNG, JPEG, or WebP format.
- On the Profile page, select Change avatar.
- Choose a PNG, JPEG, or WebP image.
The avatar applies at once. It is centre-cropped to a square and re-encoded at 128×128.
To put the letter tile back, select Restore default beside Change avatar.
Change your nickname
- On the Profile page, in Nickname, enter a nickname of 1–32 characters.
- Select Save.
The limit counts characters, so a Chinese name may be 32 characters. Saving a blank nickname clears it.
Restore default, next to Save, puts your nickname back to its default, which is your user id. Both buttons write on click, and each is disabled when it would write what is already stored.
General
The General page is personal.
| Setting | Options | What it does |
|---|---|---|
| Language | English / 中文 / System | System follows the browser. |
| Currency | USD $ / CNY ¥ | The display currency for prices. Storage is always USD. Conversion happens only at the edge of the screen. |
| Task completion notifications | On / Off (off by default) | Shows a system notification when a Task finishes while the window is hidden or unfocused. Clicking the notification opens that Session. |
| Company mode | On / Off (on by default) | Shown only while an admin has turned company mode on for the server. Off hides your own Development / Company switch and nothing else; organizations keep running. See Company mode. |
| Import Trace | — | Turns a Trace file into a conversation. The row is there only if you own a Project. See Import a Trace. |
[!NOTE] Turning on Task completion notifications asks the system for permission on the spot. The system asks only once: after a refusal the switch stays off with a hint, and the only way back is the system's own notification settings. A browser without system notifications shows the switch disabled.
Import a Trace
Import Trace turns a .jsonl Trace file into a conversation of an agent.
Before you begin
- A
.jsonlTrace exported from another install, at most 14MB. - You must be an owner of the destination Project.
You choose both the destination Project and the destination agent. The agent is asked for because a Trace file cannot name a local agent of its own. The Project is asked for because this dialog does not show which Project is open, which also means a Trace can go to a Project other than the open one. The picker lists only the Projects you own, since importing is an owner's action; with none owned, the row is absent.
- On the General page, in Import Trace, select the destination Project. It defaults to the open Project when you own it, and otherwise to the first Project you own.
- Select the destination agent. It defaults to the open Project's
default_agent. - Select Choose file and pick your
.jsonlfile. The import starts at once.
The Trace becomes a new conversation of that agent. An import is refused when that agent already has a Session with the same id.
Exporting is the other direction of the same road. It lives with the file it downloads, in a conversation's Trace panel.
Appearance
The Appearance page is personal.
| Setting | Options | What it does |
|---|---|---|
| Theme | Primer, Frost, Console, plus whatever this machine imported | The interface's overall style: layout, lines, type and motion change with it. Each card paints that theme's own canvas, surface, ink and accent, so you can see a choice before picking it. |
| Color mode | Light / Dark / System | The light or dark version of the theme. |
| Terminal theme | App / Light / Dark | The terminal panel keeps its own light or dark and follows the app theme by default. Pin it to Light or Dark to decouple the two, for prompts and TUIs tuned to one screen. |
| Font size | S / M / L | The interface font size. |
| Accent | Neutral, Blue, Green, Violet, Rose or Amber, plus the ones the current theme brings | The interface accent color. |
| Shortcuts launcher | On / Off | The round button floating on the conversation's right edge that fans out shortcuts to the workbench's panels and the terminal. The fan's Hide launcher entry does the same. |
| Tool short names | On / Off | Tool cards in a conversation name built-in tools by a short alias (read_file reads as "read"). Every other tool, MCP tools included, and the Trace viewer keep the tool's own name. Hovering a short name shows it. |
| Tray icon | On / Off (on by default) | Desktop app only. See below. |
About imported themes: a theme is only a set of values, which is why a machine can have its own. Drop a theme's .json file into the data root's themes/ folder and choose Read again under the theme list: it appears as a card in the Imported group, painted with its own colors. The "?" beside those two actions says where the folder is and what a file looks like, and an admin can instead press Import a theme… and upload the file without walking to the folder. A file may set only part of the values: the names it leaves out keep the default theme's, and the lines under the list say how many token names went unrecognised and how many keep the default — click one to see the names themselves.
About the theme library: an admin sees one more row of cards under the theme list — a remote catalogue of themes the server reads. Each card paints what that theme looks like in both light and dark: canvas, surface, ink and accent. Press Import and the server fetches that theme's file, checks it the same way it checks an imported file, and writes it into this machine's themes/ folder, so it appears in the Imported group above straight away; a card already installed says so, and pressing it again asks before replacing anything. The default catalogue is the @lmliheng/adelie-themes package on npm (the mainland mirror first, jsDelivr's GitHub copy when that does not answer yet); point ADELIE_THEME_REGISTRY at your own mirror to use another. A library with nothing you want, or a machine with no route to it, leaves the themes and imports above untouched — the library is one more way in, not a dependency.
About Tray icon: the desktop app keeps an icon in the system tray: the Windows notification area, the macOS menu bar, or the Linux tray. It stays there for as long as the app runs. Click the icon to come back to the window. Right-click it to start a new Session or quit.
Turning it off removes the icon at once, with no restart. Closing the window then no longer hides it there: the app stays in the Dock on macOS, and quits on Windows and Linux.
Keyboard shortcuts
The Keyboard shortcuts page is personal. It lists every command you can rebind, by group, each with its current key combination as your platform writes it: ⌥⌘S on a Mac, Ctrl+Alt+S elsewhere. The defaults are listed under Keyboard shortcuts in Chat.
- Select the combination on a row. The button waits for a new one.
- Press the new combination. Esc cancels, and Backspace or Delete clears the binding. A combination needs Ctrl or Alt (⌘ or ⌃ on a Mac) unless it is an F key: Shift alone, and Option alone on a Mac, is typing.
A changed row gets a Restore default button, and Reset all restores every row at once. A change applies at once in every tab of this browser; your other browsers and the desktop app pick it up the next time they load. Bindings are kept per platform, so a Mac and a Windows machine each have their own.
As soon as a binding is set, the line under its row says what stands in its way:
- Another command on the same combination: which of the two fires.
- A combination the browser keeps for itself, such as Ctrl+W or ⌘W: it only works in the desktop app. This note is amber.
- In the desktop app, a combination its menu also carries: the binding overrides that menu item.
- A combination the browser also uses, such as Ctrl+P or ⌘P for printing: in a browser tab, the binding takes over that browser function.
Bindings are shared by your browsers and the desktop app, so the browser's notes show in the desktop app too. No default sits on a combination the browser keeps. Save keeps Ctrl+S / ⌘S and takes over the browser's Save Page while an editor has focus, so its row carries a note; on a Mac so do the two rows whose defaults Chrome also uses, ⌥⌘P and ⌥⌘N.
Account
The Account page holds the Change password action.
The page exists only where a password exists to change. The desktop app's own window signs in through the shell's one-shot token and never sees a password, so it has no Account page. A browser signed into the same server with a password keeps the page.
[!NOTE] A session signed in through the first-login link can set a password without entering the current one, because that account has never had a password anyone saw.
Change your password
- On the Account page, select Change password.
- In Current password, enter your current password. This field is not shown after a first-login link sign-in.
- In New password, enter the new password (at least 8 characters).
- In Confirm new password, enter it again.
- Select Save.
Users
The Users page lists the server's users. It is admin-only, and it is absent from the desktop app, where the server runs single-user.
From the page you add users, reset passwords, and delete users.
Add a user
- On the Users page, select Add user.
- Enter a Username (2–32 characters: a lowercase letter first, then lowercase letters, digits and underscores) and an Initial password (at least 8 characters).
- Select Create.
The new user gets a default Project named <userId>-default_project. A user who is still on an initial password carries an initial password badge.
Reset a user's password
- On the Users page, find the user and select Reset password.
- Enter a new Initial password and select Save.
The reset signs the user out of every sign-in session. They must sign in again with the new password.
Delete a user
[!WARNING] Deleting a user also deletes every Project they own, data directories included. It cannot be undone.
- On the Users page, find the user and select Delete.
- In the dialog, select Delete, then Confirm.
Users with the Admin role have no delete action, and the server refuses to delete the built-in admin.
Proxy options
The Proxy options page is admin-only and server-global. It controls which outbound traffic goes through a proxy.
| Setting | Default | What it covers |
|---|---|---|
| Application uses the proxy | On | The server's own outbound traffic: LLM requests, the update check, image fetches. |
| Agent environment uses the proxy | On | Agent command subprocess environments. |
| Proxy address | Empty | Optional, and shared by both switches. Empty means follow the proxy environment variables. |
Proxy address accepts any proxy URL undici's dispatcher takes: http://, https://, socks5://, or socks://, credentials allowed. A bare host[:port] is also accepted and stored normalized to http://…. Anything else is refused with the reason shown under the input.
Nothing is written until Save. Save applies the whole form in one PUT, so a rejected address writes none of it. A save rebuilds the outbound dispatcher and takes effect on new connections, with no restart. Loopback always goes direct.
Set a proxy and test it
Before you begin
- The address of your proxy, in one of the accepted formats above.
- On the Proxy options page, in Proxy address, enter your proxy address. Leave the field empty to follow the proxy environment variables.
- Toggle Application uses the proxy to send the server's own outbound traffic through the proxy. It is on by default.
- Toggle Agent environment uses the proxy to put the proxy into agent command subprocess environments. It is on by default.
- Select Save. If the address is invalid, nothing is written and the reason appears under the input.
- Below Save, select Test to run the Reachability test.
The test measures this server's own outbound hop to the model providers. It lists its targets before it runs: the model-list endpoints of OpenAI, Anthropic, Gemini, DeepSeek, Z.ai and BigModel. Test then sends each target one credential-free GET, and results appear one by one as they arrive. Each target waits at most five seconds.
- Any HTTP answer counts as Reachable, 401 and 403 included, because a refused credential still proves that DNS, TCP and TLS all completed. A reachable target shows the time it took.
- A failure is named: Timed out, DNS lookup failed, Connection refused, TLS handshake failed, or Unreachable.
[!NOTE] The test measures the saved settings, because only a save rebuilds the outbound dispatcher. If you edited the address, save it before testing.
Upload limits
The Upload limits page is admin-only and server-global. It sets two sizes, in whole MB:
| Field | Default | Allowed range |
|---|---|---|
| Max attachment size (MB) | 100MB | 1–200MB |
| Max total per message (MB) | 120MB | 1–200MB |
The total may not sit below the per-file cap, because that combination would make a legal single attachment unsendable. A value outside the range, such as "100GB" typed into a MB field as 102400, is refused with the reason shown under the input rather than accepted. Validation precedes every write: one bad field in a PUT leaves the other fields untouched too.
Change the upload limits
- On the Upload limits page, in Max attachment size (MB), enter a whole number of MB between 1 and 200.
- In Max total per message (MB), enter a whole number of MB between 1 and 200, and not below the per-file cap.
- Select Save.
Saving takes effect immediately, with no restart: the attachment validators and the request body cap both read the setting per request.
Company mode
The Company mode page is admin-only and server-global. It holds the Enable company mode master switch, off until an admin turns it on here.
The switch applies the moment it is flipped. There is no Save button.
Turning it off stops the organization scheduler and every organization route, and hides the mode switch for everyone. Organizations on disk are untouched. Turning it back on backfills no missed trigger.
[!NOTE] Company mode is a beta. See Company mode.
Agent API
The Agent API page (Settings › Server › Agent API) is admin-only and server-global. It holds the Allow the Agent API switch, on by default, over every agent's API: the HTTP API through which programs outside Adelie talk to an agent (see Agent API).
The switch applies the moment it is flipped. There is no Save button.
Turning it off asks first, because every program calling an agent fails from then on. Once it is off, every Agent API request is refused with 403 agent_api_disabled. Each agent's own switch, approval mode and keys are kept, and work again when the switch is back on. Meanwhile each agent's API tab shows its switch disabled, with a note saying why, to every member.
Plugins
The Plugins page is admin-only and server-global. It shows the options each loaded plugin declares, as a form drawn from the plugin's own schema. A plugin that declares no options has no card here. A save reaches the plugin at once, with no restart.
Sandbox
The sandbox is the first card on the page. It sets the policy a new Session is confined under. One policy governs the commands the agent runs, the hook scripts its Session runs, the MCP Servers it starts over stdio, and the file tools (read_file, edit_file, write_file):
- Enable: the switch at the top. Off (a fresh install), a new Session has full file and network access and is held only by its approval mode, and the composer's permission menu lists the approval modes alone. While it is off, the card shows the switch alone: the presets, the Advanced fold, the backends' own settings and the card's notices come back when it is turned on, as they were.
- Presets: the table of what the permission menu offers, one row per preset: its name, file mode (off, workspace, read-only), network (full, localhost, none) and approval mode, and an Action group: a pin for whether the menu lists it, a drag handle, and a "…" menu with Set as default and, on presets you added, Delete. The default row reads "(Default)" after its name, and each name's "?" says what the row is for — for a preset you added, or a built-in one whose values you changed, what each of its values does. Each header's "?" says what the column (or each icon) means. Drag a row's handle (or press the arrow keys on it) to reorder; the order is the menu's. Add preset adds a row; only added rows can be deleted, and not while they are the default. Workspace allows writes to the Session's Workspace, its scratchpad (the plan file, a goal's state file, attachments) and the temporary directory; read-only allows the temporary directory only. The network level applies to the image URLs
read_filefetches too, and localhost needs a backend that can enforce it. The default row is the one a new Session starts from while the switch is on — its file mode, network and approval mode; Workspace Write until changed. Settings saved before the presets table keep their own file mode and network until you set a default: the card marks as default the row that starts Sessions exactly where they do, and saving pins it. When no row does (a cut or localhost-only network, or masked paths with the file mode off), no row is marked, a notice at the top of the card says what is in effect, and saving other settings keeps it; set a row as default, or add a preset with those values and set it. - Under Advanced, folded by default:
- Temporary directory: whether it stays writable. On by default, in either confining mode, because shells and most tools cannot start without one. Turning it off needs a backend that can close it: with only DSH in use the switch is held on and says why (on Landlock the temporary directory is the host's shared
/tmp). - Masked paths: paths hidden from the agent's commands, hook scripts,
stdioMCP Servers and file tools, reads included; one absolute path per line, at most 64.
- Temporary directory: whether it stays writable. On by default, in either confining mode, because shells and most tools cannot start without one. Turning it off needs a backend that can close it: with only DSH in use the switch is held on and says why (on Landlock the temporary directory is the host's shared
Neither confining mode lets the agent write its Agent State: AGENTS.md, system_config.yaml, Skills, hook packages, memory, the vault and scheduled tasks. To let an agent write memory, write its own Skills or hook packages, or change its configuration, switch that conversation to full access with its Permissions button. An MCP Server started over stdio is confined the same way when it starts — at a context open or a reconnect — so a Server that must write outside those directories, or reach a network the level cuts, fails to connect in a confining Session; MCP Servers reached over http or sse are not processes of this machine and are not confined.
A sandbox backend installed as a plugin (bwrap, Seatbelt, WSL, DSH) enforces the policy on all of them: the file tools work through a helper process the same backend wraps (see File tools). The card's first line says what this machine enforces and by what — on a default Ubuntu, Enforced here: file writes, by Landlock (dsh-local) — and what it does not, with More info under it naming each installed backend that is not in use and why (Sandbox on Ubuntu); it says so when there is no backend. A network level or masked paths no backend here enforces are greyed out or refused rather than enforced in part. Without a backend, every mode but off refuses every agent command and file operation, fails every hook and connects no stdio MCP Server. Two backends need a word: DSH does not make the scratchpad writable and cannot close the temporary directory — More info lists what its rung leaves open, and what (partial) means on an older Landlock; WSL runs hook scripts and the file tools' helper on the nodejs the distro's initialization now installs — a distro initialized before that has to be initialized again, and until then hooks and file operations fail under it rather than running unconfined — and a stdio MCP Server runs there only if its command exists inside the distro.
A backend's own options, such as bwrap's program and its probe timeout of 1–30 seconds, or Seatbelt's program, are drawn inside the same card, and the card's one Save stores both. A backend that failed its check, for example on a wrong program path, is loaded again by that save, with no restart.
The settings apply to Sessions created after the save; each Session keeps the policy it was created with. A restart keeps the settings.