Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

17.5 KB
Raw Blame

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 --provider and --model-id are 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_key and no base_url of its own (or one that is the vendor's official endpoint), AgentHub (the LLM gateway library) reads variables such as DEEPSEEK_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY and GEMINI_API_KEY. An entry pointed at a gateway or a server of your own needs --api-key. A .env file 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:

  • /compact compacts the context.
  • /clear starts a fresh Session. The old one can still be resumed.
  • /exit or /quit quits.
  • 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.

  1. On a connected machine, download the file that matches the target computer: penguin-<target>.tar.gz, or penguin-win32-x64.zip for Windows.
  2. Transfer that one file to the target computer and extract it.
  3. In the extracted directory, run the installer. On Windows, double-click install.cmd or 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_command runs in a POSIX shell, so Skills written for one keep working. The shell is picked in this order: bash on 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 under git\ and gives a machine without Git for Windows a POSIX shell, about sixty core utilities and git.exe; then PowerShell (pwsh, then powershell). Only npm installs, which bundle nothing, reach the PowerShell fallback. The ADELIE_SHELL environment 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_command with "\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 update is 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 penguin with this error, the blocked file is a penguin.ps1 launcher. It comes either from an install older than 0.1.6, which you fix by running the installer again (the upgrade replaces bin\ and removes it), or from an npm global install, where you call penguin.cmd explicitly or allow local scripts with Set-ExecutionPolicy -Scope CurrentUser RemoteSigned. The packaged install ships only penguin.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