A local-first multi-agent app development platform, built on PenguinHarness
title: Desktop app description: Install the Adelie desktop app, configure a model, and run your first Task, with no terminal required.
The desktop app is the full Web App as a standalone application. It embeds the server and opens already signed in, so there is no login page, no initial password to copy, and nothing to install from a command line. It also installs the penguin command, so the terminal is there when you want it.
Before you begin
- macOS 11 or later, Windows 10 or later (x64), or Linux (x64).
- An API key for one model provider.
Download and install
Download the installer for your platform from the latest Release; every GitHub Release carries the same files.
| Platform | Installers |
|---|---|
| macOS 11+ | dmg (Apple Silicon / Intel) |
| Windows 10+ | installer (.exe, x64) |
| Linux (x64) | AppImage / deb |
Install the app and open it. On macOS, drag the app into Applications and open it from there.
The macOS builds are Developer ID signed and notarized, and the Windows installers are Authenticode signed, so neither platform needs a first-launch unblock. Linux is the one exception:
[!INFO]- Double-clicking the Linux AppImage does nothing
Browsers download AppImages without the execute permission. Grant it once, and the app starts normally from then on. The deb package installs through the package manager and is not affected.
chmod +x penguin-desktop-linux-x86_64.AppImage
The app opens signed in. The window signs itself in, so there is no password to type or to change: in the app's window, Settings has no Account page with Change password.
Configure a model
Adelie ships with no model credentials. Give it an API key for the model you want to use:
- In the sidebar, select Models. Models are listed in one group per provider, and the default model is marked Default.
- In your provider's group, click Enter key, enter the API key, and click Confirm. The key is written to every model in that group. TokenDance, Penguin Go and ModelScope can also get a key for you: click Connect on their group.
- If you want a model other than the default, open that model and click Set as default model.
To add a model that is not listed, click Add model in the Custom group (or a group you create) and fill in the Model ID, Custom base URL and API key. The other built-in groups hold their built-in models only.
A model is always referenced as a (provider, model_id) pair: the provider is never inferred from the model id. See Models & Providers for the built-in groups.
Use API keys from your shell profile
API keys already exported in your shell profile (ANTHROPIC_API_KEY, OPENAI_API_KEY, …) work without entering them again. On macOS and Linux, when you launch the app from the Dock or the desktop, it imports the login shell's environment, filling in only the variables the launch itself did not set. The agent shell's PATH benefits the same way. Set PENGUIN_NO_LOGIN_SHELL_ENV to turn this off.
For an official provider's model with no stored key, the Models page shows the detected variable's value masked, just as it shows a stored key: on the model's card, and in the model's dialog, which marks the key as Read from environment variable. Gateway groups, and custom or vLLM rows with a base URL of their own, are not matched against these variables — a model there needs its own key.
Run your first Task
- In the sidebar, click New chat.
- Pick the agent, the Workspace and the approval mode. You choose the Workspace with the server-side directory browser.
- Send a first message, for example "Create hello.txt containing Hello, Penguin".
Tool calls appear inline as cards; open one to inspect its arguments and output. With the Ask every time (always-ask) approval mode, every file write waits for you to click Allow. Tools & Approval describes the four approval modes.
[!INFO]- On macOS, the directory browser can't read Desktop, Documents or Downloads
macOS protects these folders. Click Allow access in the directory browser: the app asks macOS for the folder in its own name, and once you allow it, your agents can read the folder too. If macOS doesn't allow it, Open System Settings takes you to Privacy & Security; if Adelie is not listed under Files and Folders, add it under Full Disk Access. A development build started from a terminal counts as that terminal to macOS, so allow the terminal there instead.
The penguin command
The app installs the penguin command itself, at every launch, from the CLI bundled inside it. The app and the command always come from the same build, so updating the app updates the command too. No system Node.js is involved: the launcher runs the bundled CLI on the app's own runtime.
| Platform | Where the command goes |
|---|---|
| macOS | /usr/local/bin/penguin, linked to the app. Creating that directory can need an administrator password. macOS asks only when the plain write is refused, and if you decline, the command is not installed. |
| Windows | The app's bin directory is appended to your user Path. Open a new terminal window afterwards; a terminal that is already running keeps the old Path. |
| Linux (deb) | /usr/bin/penguin, created by the package's own install script. |
| Linux (AppImage) | ~/.local/bin/penguin, a wrapper that runs the AppImage. Most distributions put that directory on PATH at login. |
The app never replaces an existing penguin. If something else already provides the command, such as a CLI install, a global npm package or a script of your own, the app leaves it exactly as it is and installs nothing. To replace it deliberately, choose Install 'penguin' Command… from the application menu. The same menu item installs the command if you declined the macOS administrator prompt.
On macOS, the app does not install the command while it runs from the mounted dmg, because the link would break the moment you eject the disk image. Drag the app into Applications and open it from there.
Share the data root with the CLI
The desktop app uses the same data root as a CLI install, so you can use the two side by side.
Only one server can use a data root at a time. If one is already running on yours — a penguin web or penguin server instance, or an older copy of the app that is still open — the app attaches to that server instead of starting a second one, and signs its own window in against it, so the window still opens with no login page. Being able to read the data root is what lets it do that, so a root it cannot read leaves the window on the login page instead, behind a dialog naming the data root and the server that holds it. The window signs itself in but cannot set a password on a server it only attached to: for a password you can type, such as for a browser reaching that same server, stop the server and run penguin server reset-admin-password.
If you later serve that data root over the network with penguin server, first give its admin a password you can use, because the desktop app deliberately seeds one that nobody can read. Stop the server, then run:
penguin server reset-admin-password
The admin account returns to the unclaimed state. When you start the server again, it prints a first-login link where you set the new password.
That command is also the way out if a window ever does show the login page: the password the desktop app created for itself is random and was never shown, so there is nothing to type there.
Next steps
- Web App: find your way around the interface.
- Update Adelie: how the desktop app updates itself.
- CLI and Web App: a standalone install, for a server or a remote machine. On the same machine you don't need it: the app already provides
penguin, and installing the CLI puts a second copy on yourPATH. - Architecture: how the pieces fit together.