Yaowei Zheng
d4faee3a1e
Branch-length batch covering tooling, the model layer, the Web App and the public surfaces. Highlights: - Changelog: a per-release `changelog/<version>/` tree, grouped by the surface each change touches, with a root CHANGELOG.md holding one line per release. - Dev startup: `scripts/dev-prebuild.mjs` serializes the skills+core prebuild behind a lock and keeps `pnpm install` current; `pnpm dev` runs server+web together. - AgentHub 0.3.3 -> 0.4.0: OmniMessage complete payloads carry one opaque `fidelity` object in place of item-level `signature`/`phase`, threaded verbatim through Trace, replay and resume; malformed classification adapted to the new error types. - Model layer: a model is always referenced by an explicit `(provider, model_id)` pair. The provider is never inferred, guessed or defaulted -- both the catalog inference and the unique-match config resolution are gone, and CLI, SDK, server routes and run_subagent all require the complete pair. Catalog gains the Qwen Token Plan, Qwen Pay-As-You-Go and Fireworks AI gateways, plus an expanded OpenRouter group. - Web App: catalog preset sync and per-group speed test on the Models page, positional slash commands, a markdown renderer, skill-library update reminders, and a vertically centred draft page whose upward menus size themselves to the room available. - Public surfaces: restructured READMEs, the penguin.ooo landing site and blog, refreshed benchmark results for both suites, and the demo videos playing on the landing page. Includes the fixes from a full review of the branch: 23 confirmed findings, among them a provider-inference bug that could send one vendor's API key to another vendor's endpoint, and an Escape handler that destroyed the composer's contents unrecoverably. Verified on the branch head: pnpm test (1127 passing, 7 packages), pnpm typecheck and pnpm format:check clean, Playwright e2e 14/14.
80 lines
2.9 KiB
Markdown
80 lines
2.9 KiB
Markdown
---
|
|
title: Installation
|
|
description: Install PenguinHarness via the install script, npm, or from source.
|
|
---
|
|
|
|
## Requirements
|
|
|
|
- Linux / macOS (x64 or arm64): the install script ships platform tarballs with an official Node.js runtime bundled — no local Node needed.
|
|
- Other platforms, or installing via npm / from source: system Node.js >= 24.
|
|
|
|
## Script install (recommended)
|
|
|
|
On Linux / macOS:
|
|
|
|
```bash
|
|
curl -fsSL https://penguin.ooo/install.sh | sh
|
|
```
|
|
|
|
The script downloads the matching `penguin-{linux,darwin}-{x64,arm64}.tar.gz`, which bundles an official Node.js runtime. Other platforms do **not** fall back automatically: the script exits and asks you to install Node.js >= 24 and re-run with `--universal`, which selects the runtime-less `penguin-universal.tar.gz`.
|
|
|
|
Verify the install:
|
|
|
|
```bash
|
|
penguin -v
|
|
```
|
|
|
|
### Install location and options
|
|
|
|
| Item | Details |
|
|
| --- | --- |
|
|
| Install dir | `~/.penguin` by default; override with the `PENGUIN_INSTALL_DIR` env var |
|
|
| Command entry | A symlink `~/.local/bin/penguin` is created (the script warns if `~/.local/bin` is not on PATH) |
|
|
| Version pin | `PENGUIN_VERSION=vX.Y.Z` env var, or the `--version vX.Y.Z` script flag; defaults to the latest Release |
|
|
| Integrity check | Downloads are sha256-verified when the Release ships checksum assets |
|
|
| Upgrade | Re-run the install script; files are swapped atomically |
|
|
|
|
Script flags go after `sh -s --`, e.g. `curl -fsSL https://penguin.ooo/install.sh | sh -s -- --universal`.
|
|
|
|
### Data directory
|
|
|
|
The data directory defaults to `~/.penguin/data` — under the install home `~/.penguin`, but never modified by install or upgrade — and is overridable with the `PENGUIN_HOME` env var. Model configuration, Session records, and other data are preserved across upgrades.
|
|
|
|
## npm install
|
|
|
|
Requires system Node.js >= 24:
|
|
|
|
```bash
|
|
npm install -g @prismshadow/penguin-cli
|
|
```
|
|
|
|
The npm package is `@prismshadow/penguin-cli`; the installed command is `penguin`. Web UI assets ship inside the `@prismshadow/penguin-server` package, so this single install yields a working `penguin web`.
|
|
|
|
## From source
|
|
|
|
Requires Node.js >= 24 and pnpm:
|
|
|
|
```bash
|
|
git clone https://github.com/Prism-Shadow/penguin-harness.git
|
|
cd penguin-harness
|
|
pnpm install && pnpm build
|
|
```
|
|
|
|
After the build, run `pnpm penguin <args>` inside the repo as the dev runner, or use the globally linked `penguin` command.
|
|
|
|
## Published npm packages
|
|
|
|
| Package | Description |
|
|
| --- | --- |
|
|
| `@prismshadow/penguin-cli` | Command-line tool providing the `penguin` command |
|
|
| `@prismshadow/penguin-core` | SDK for creating Agents and Sessions programmatically |
|
|
| `@prismshadow/penguin-server` | Web service, including the Web UI assets |
|
|
| `@prismshadow/penguin-skills` | Skill collection |
|
|
|
|
All packages are published under the Apache-2.0 license.
|
|
|
|
## Next steps
|
|
|
|
- [Quickstart](/quickstart): configure a model and run your first Task.
|
|
- [CLI Reference](/cli): the full list of commands and options.
|