A local-first multi-agent app development platform, built on PenguinHarness
title: CLI and Web App description: Install the penguin command, configure a model, open the Web App, and run your first Task from the terminal or the browser.
Install the penguin command with one line, configure a model, and run your first Task from the terminal or the browser. penguin web opens the same interface as the desktop app, in your browser.
Before you begin
- Linux or macOS (x64 or arm64), or Windows 10 or later (x64) with PowerShell 5.1 or later. The installers for these platforms bundle an official Node.js runtime, so you don't need Node.js on the machine.
- Node.js >= 24, if you install with npm, build from source, or use another platform.
- An API key for one model provider.
Install the CLI
Run the installer for your platform. The Linux / macOS and Windows installers bundle their own Node.js runtime; the npm route needs Node.js >= 24 already installed.
curl -fsSL https://github.com/lmliheng/Adelie/releases/latest/download/install.sh | sh
irm https://github.com/lmliheng/Adelie/releases/latest/download/install.ps1 | iex
npm install -g @adelie/cli
Check the install:
penguin -v
The command prints the version you installed.
For offline installs, building from source, install locations, version pinning and Windows details, see the Installation reference at the end of this page.
Configure a model
Adelie ships with no model credentials, so add a model before your first Task. This command adds DeepSeek's deepseek-flash and makes it the default:
penguin config model add --provider deepseek --model-id deepseek-flash --api-key sk-... --set-default
You can also add models later on the Models page of the Web App.
- A model is always named by a
(provider, model_id)pair, so--providerand--model-idare both required. Adelie never infers the provider from the model id. See Models & Providers for the built-in groups. - The API key can also come from an environment variable, for the vendor's own endpoint. When a model entry has no inline
api_keyand nobase_urlof its own (or one that is the vendor's official endpoint), AgentHub (the LLM gateway library) reads variables such asDEEPSEEK_API_KEY,ANTHROPIC_API_KEY,OPENAI_API_KEYandGEMINI_API_KEY. An entry pointed at a gateway or a server of your own needs--api-key. A.envfile in the working directory is loaded automatically.
Start the Web App
penguin web
The service starts at http://127.0.0.1:7364 and opens your browser. Add --no-open to skip opening the browser. penguin server starts the same process headless.
The account is admin, and it has no password yet. The server prints a first-login link in a framed notice. Open the link: the browser signs in, and you set a password.
[!NOTE] The first-login link works until a password is set, for at most 30 days. You can open it as often as you need, and a restart prints a fresh one.
To find your way around the interface, see Web App.
Run your first Task
Run a single Task from the terminal, or start a chat. Both work the same way underneath, described in How terminal Sessions work.
Run a single Task
penguin run -m "Create hello.txt containing Hello, Penguin"
The command streams the agent's work and exits when the Task ends. The Task runs in the current directory, which becomes its Workspace. Pass --workspace /path to use another directory; it must already exist.
Chat in the terminal
penguin chat
Each line you enter starts a Task. While chatting:
/compactcompacts the context./clearstarts a fresh Session. The old one can still be resumed./exitor/quitquits.- Ctrl-C interrupts the running Task.
When you quit, the chat prints a penguin chat --resume <sessionId> command that resumes this Session. --resume without an id resumes the agent's latest Session.
How terminal Sessions work
run, chat and the other Session commands are thin clients of the server. They attach to the local server when one is running, and quietly start one when none is. On the local machine they need no login; the CLI Reference describes the connection rules.
Everything these commands create also shows up in the Web App, and penguin ls, penguin logs and penguin input work with those Sessions from the terminal. The CLI Reference lists every command and option.
Installation reference
The install commands above cover nearly every case. This section holds the remaining options and details.
Install script details
On Linux and macOS, the script downloads the bundle for your platform, penguin-{linux,darwin}-{x64,arm64}.tar.gz. This is the canonical installer bundle. It seals the program payload (with an official Node.js runtime), the payload's SHA256 checksum, and a copy of this same installer. The script verifies the download against its published .sha256, then verifies the sealed payload checksum before it stages anything. On Windows, the installer downloads penguin-win32-x64.zip, which bundles the runtime in the same way.
Other POSIX platforms do not fall back automatically. The script exits and asks you to install Node.js >= 24 and run it again with --universal, which selects the runtime-less penguin-universal.tar.gz bundle. Windows has its own installer and does not use --universal.
Download source and version
The installer downloads from this repository's GitHub Releases. PENGUIN_DOWNLOAD_SOURCE accepts auto, the default, and github; they mean the same thing here, because Adelie publishes to one source. Upstream's oss mirror is not one of them: a script that still names it stops before downloading anything and says so.
To download through a mirror, point PENGUIN_DOWNLOAD_BASE_URL at a directory holding the release assets — the same layout a GitHub Release has — and optionally PENGUIN_DOWNLOAD_FALLBACK_BASE_URL at a second one. When the primary fails, the installer tries the fallback for the same version, so a mirror can never quietly install a different tag. Downloads are verified against the published .sha256 either way.
Version handling is unchanged by the source: the releases/latest/download entry resolves the current stable version each time it runs, and an installer downloaded from a versioned Release is stamped with that Release's tag and installs the same version by default, which keeps the installer and the package format matched. To override the version, set PENGUIN_VERSION, or pass --version on POSIX systems. On Windows, set the variable before you run the installer:
$env:PENGUIN_VERSION = "vX.Y.Z"; irm https://github.com/lmliheng/Adelie/releases/latest/download/install.ps1 | iex
Offline install
Offline installs use the same Release files as online installs; there is no separate offline package.
- On a connected machine, download the file that matches the target computer:
penguin-<target>.tar.gz, orpenguin-win32-x64.zipfor Windows. - Transfer that one file to the target computer and extract it.
- In the extracted directory, run the installer. On Windows, double-click
install.cmdor run.\install.ps1. On Linux and macOS, run./install.sh.
.\install.ps1
./install.sh
The extracted bundle holds the installer, the program payload (payload.tar.gz / payload.zip) and the payload's .sha256. The installer finds the payload next to it by itself, always verifies the sealed checksum, and makes no network requests, so you don't need to transfer a separate checksum file.
You can also point the installer at a file explicitly: install.sh --archive <file>, PENGUIN_ARCHIVE=<file>, install.ps1 -ArchivePath <file>, or $env:PENGUIN_ARCHIVE. Each accepts a Release bundle, its inner payload, or a legacy program archive from before 0.1.6.
Install from source
Building from source requires Node.js >= 24 and pnpm:
git clone https://github.com/lmliheng/Adelie.git
cd Adelie
pnpm install && pnpm build
After the build, run pnpm penguin <args> inside the repository as the dev runner, or use the globally linked penguin command.
The dev entry points (pnpm penguin, pnpm dev, pnpm desktop) default to a separate data root, ~/.penguin/dev-data, while the linked or installed penguin keeps ~/.adelie/data. Set ADELIE_HOME to override. The desktop dev run also uses its own app identity (Adelie-Dev), so it can run alongside an installed desktop app without conflicts.
Install location and options
| Item | Details |
|---|---|
| Install directory | ~/.adelie by default; override it with the PENGUIN_INSTALL_DIR environment variable |
| Command entry | A symlink, ~/.local/bin/penguin. The script warns if ~/.local/bin is not on PATH. The --no-modify-path flag leaves the link alone, for a second installation beside the one penguin belongs to |
| Version | The PENGUIN_VERSION=vX.Y.Z environment variable, or the --version vX.Y.Z script flag. The stable entry installs the latest Release by default; a versioned Release installer installs its own tag |
| Download source | PENGUIN_DOWNLOAD_SOURCE=auto (default) or github — Adelie publishes to GitHub Releases only, and anything else stops the script. A mirror goes in PENGUIN_DOWNLOAD_BASE_URL, with PENGUIN_DOWNLOAD_FALLBACK_BASE_URL beside it |
| Local archive | PENGUIN_ARCHIVE=<file> or --archive <file>. Accepts a Release bundle, which verifies itself with its sealed payload checksum, or a payload or legacy program archive with a <file>.sha256 next to it. A renamed legacy file may use the platform asset's canonical .sha256 |
| Integrity check | Always on. Online downloads are verified against the published .sha256, and bundle payloads against the checksum sealed inside the bundle |
| Upgrade | Run the install script again; files are swapped atomically |
Script flags go after sh -s --, for example curl -fsSL https://github.com/lmliheng/Adelie/releases/latest/download/install.sh | sh -s -- --universal.
Windows specifics
| Item | Details |
|---|---|
| Install directory | %USERPROFILE%\.adelie by default; override it with the PENGUIN_INSTALL_DIR environment variable |
| Command entry | The bin\penguin.cmd launcher. There is deliberately no .ps1 launcher: batch files are exempt from the PowerShell execution policy, so penguin works even under the default Restricted policy. The installer adds %USERPROFILE%\.adelie\bin to your user Path and broadcasts the change. Open a new terminal window once; a new tab of an already-running terminal keeps the old Path. The -NoModifyPath switch leaves the Path alone, for a second installation beside the one penguin belongs to |
| Version pin | Set $env:PENGUIN_VERSION = "vX.Y.Z" before running the installer |
| Local archive | $env:PENGUIN_ARCHIVE = "<file>" or -ArchivePath <file>. Accepts the Release bundle, which verifies itself with its sealed payload checksum, or a payload or legacy zip with a <file>.sha256 next to it. A renamed legacy file may use penguin-win32-x64.zip.sha256 |
| Integrity check | Always on. Online downloads are verified against the published .sha256, and bundle payloads against the checksum sealed inside the bundle |
| Upgrade | Run the installer again. It swaps bin/lib/web/node and never touches data |
Other differences on Windows:
- Agent shell: the agent's
exec_commandruns in a POSIX shell, so Skills written for one keep working. The shell is picked in this order:bashon PATH, which is preferred because your own Git for Windows carries the full MSYS userland; then the bundled bash, since the Windows zip ships MinGit undergit\and gives a machine without Git for Windows a POSIX shell, about sixty core utilities andgit.exe; then PowerShell (pwsh, thenpowershell). Only npm installs, which bundle nothing, reach the PowerShell fallback. TheADELIE_SHELLenvironment variable overrides the pick, and the Session's system prompt tells the model which shell is active. The bundled shell's licensing is recorded in THIRD-PARTY-NOTICES.md. - Ctrl-C: sending Ctrl-C to a running command session (
input_commandwith"\u0003") terminates the whole command session tree instead of interrupting the foreground command. Windows cannot deliver a console Ctrl-C to a piped child process, so the interrupt becomes a hard kill of the tree. - In-place update:
penguin updateis not yet supported on Windows. To upgrade, run the installer again. - Config file permissions: on POSIX systems, config and credential files are written with
0600(owner-only) permissions. Windows has no such mode bits, so these files fall under your profile's default NTFS ACLs. - "running scripts is disabled": if PowerShell refuses to run
penguinwith this error, the blocked file is apenguin.ps1launcher. It comes either from an install older than 0.1.6, which you fix by running the installer again (the upgrade replacesbin\and removes it), or from an npm global install, where you callpenguin.cmdexplicitly or allow local scripts withSet-ExecutionPolicy -Scope CurrentUser RemoteSigned. The packaged install ships onlypenguin.cmd, which runs under any execution policy.
Data root
The data root is ~/.adelie/data by default (%USERPROFILE%\.adelie\data on Windows). It sits under the install directory, but installing and upgrading never modify it. Set the ADELIE_HOME environment variable to use another directory. Model configuration, Session records and other data are kept across upgrades.
Sandbox on Ubuntu
On Linux, turning the sandbox on installs two backends. @adelie/sandbox-bwrap confines commands with bubblewrap: file writes, the network and masked paths. @adelie/sandbox-dsh confines file writes only, through Landlock where bubblewrap cannot run. Where both work, bubblewrap serves every command.
Ubuntu 23.10 and later, including a default Ubuntu 24.04, grant unprivileged user namespaces only to programs that have an AppArmor profile allowing it (kernel.apparmor_restrict_unprivileged_userns is 1), and bubblewrap needs them. The desktop .deb installs such a profile for the app. The install script, the npm install and the release archive run without root and cannot, so on those installs bubblewrap is refused and the sandbox works through Landlock with no step from you. The Sandbox card says so: Enforced here: file writes, by Landlock (dsh-local). Not enforced here: network isolation, localhost-only network and masked paths. Every built-in preset leaves the network open, so all of them are enforced. A preset with No network is greyed out on the card, and masked paths are refused rather than run with less confinement. More info under that line shows why bubblewrap is not in use (setting up uid map: Permission denied) and the bwrap path it tried.
To add network isolation and masked paths, let bubblewrap run with an AppArmor profile for the copy the backend ships. This step is optional and takes root once:
sudo tee /etc/apparmor.d/adelie-sandbox-bwrap >/dev/null <<'EOF'
abi <abi/4.0>,
include <tunables/global>
profile adelie-sandbox-bwrap @{HOME}/.adelie/**/plugins/node_modules/@adelie/sandbox-bwrap/vendor/linux-*/bin/bwrap flags=(unconfined) {
userns,
}
EOF
sudo apparmor_parser -r /etc/apparmor.d/adelie-sandbox-bwrap
Then select Save on the Sandbox card: the backends are checked again without a restart, and the card names bubblewrap. The profile loads again at every boot. Its pattern matches every place the backend's bubblewrap is unpacked under ~/.adelie: a download into the data root (~/.adelie/data/plugins/), the installation's bundled plugins (~/.adelie/lib/plugins/) and the plugins a hot push carries (under ~/.adelie/data/hmr/). An upgrade replaces the package at the same path, so later versions stay covered. If ADELIE_HOME (its pre-rename name is PENGUIN_HOME) or PENGUIN_INSTALL_DIR points outside ~/.adelie, load a copy of the profile under another name with @{HOME}/.adelie replaced by that directory.
The profile applies to whatever program is at that path, and you can write to that path. On a machine shared with users you do not trust, set the bwrap program on the Sandbox card to a root-owned copy, such as /usr/bin/bwrap from apt install bubblewrap, and name that path in the profile instead. The other option is to lift the restriction for every program with sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0. To keep that setting after a reboot, add the same line without sudo sysctl -w to a file in /etc/sysctl.d/.
Published npm packages
| Package | Description |
|---|---|
@adelie/cli |
Command-line tool that provides the penguin command |
@adelie/core |
SDK for creating agents and Sessions from code |
@adelie/server |
Web service, including the Web App assets |
@adelie/* |
The built-in plugins, one package each (Skills and session hooks); core loads them |
All packages are published under the Apache-2.0 license.
Next steps
- Web App: use Adelie from the browser.
- CLI Reference: every command and option.
- Update Adelie: check your version and upgrade.
- SDK: embed the engine in your own program.