penguin-harness/packages/docs/content/quickstart.en.md at c369e089a7acbc85dcef890f4b35a7ffa948eadf

Files

T

Yaowei Zheng d4faee3a1e Changelog, dev startup, README, AgentHub 0.4.0, model catalog, and landing site (#7 )

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.

2026-07-21 17:43:31 +08:00

2.6 KiB

Raw Blame History

title, description

title	description
Quickstart	Install PenguinHarness, configure a model, and run your first Task.

Install

One-liner for Linux / macOS:

curl -fsSL https://penguin.ooo/install.sh | sh

For other options (npm, from source), see Installation.

Configure a model

PenguinHarness ships with no built-in model credentials, so configure a model first. Use the Models page in the Web UI, or the CLI:

penguin config model add --provider deepseek --model-id deepseek-v4-pro --api-key sk-... --set-default

A model is always referenced as a (provider, model_id) pair, so --provider and --model-id are both required — the Provider is never inferred from the model id. See Models & Providers for the built-in groups.
The API key can also come from environment variables: when a model entry has no inline api_key, AgentHub (the LLM gateway library) reads variables such as DEEPSEEK_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, and GEMINI_API_KEY. A .env file in the working directory is loaded automatically.

Start the Web App

penguin web

The service runs at http://127.0.0.1:7364 and opens your browser (--no-open to skip). First login is admin / penguin-2026 — change it right away. penguin server starts the same process headless.

One-shot run

penguin run -m "Create hello.txt containing Hello, Penguin"

The Workspace defaults to the current directory; pass --workspace /path to change it. The target directory must already exist.

Interactive chat

penguin chat

Each input line starts a Task.
/compact compacts the context; /exit or /quit quits; Ctrl-C interrupts the running Task.
On exit it prints a penguin chat --resume <sessionId> hint for resuming this Session; --resume without an id resumes the Agent's latest Session.

SDK hello

After installing @prismshadow/penguin-core:

import { createAgent, isCompleteModelMessage, userText } from "@prismshadow/penguin-core";

const agent = await createAgent({ agentId: "default_agent" });
const session = await agent.createSession({ workspaceDir: process.cwd() });

for await (const output of session.run([userText("Create hello.txt containing hi")], {
  approve: async () => "allow",
})) {
  if (isCompleteModelMessage(output) && output.payload.type === "text") {
    console.log(output.payload.text);
  }
}

Next steps

Web App Guide: use PenguinHarness from the browser.
CLI Reference: the full list of commands and options.
Architecture Overview: how the pieces fit together.

2.6 KiB Raw Blame History