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.
77 lines
2.6 KiB
Markdown
77 lines
2.6 KiB
Markdown
---
|
|
title: Quickstart
|
|
description: Install PenguinHarness, configure a model, and run your first Task.
|
|
---
|
|
|
|
## Install
|
|
|
|
One-liner for Linux / macOS:
|
|
|
|
```bash
|
|
curl -fsSL https://penguin.ooo/install.sh | sh
|
|
```
|
|
|
|
For other options (npm, from source), see [Installation](/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:
|
|
|
|
```bash
|
|
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](/models) 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```ts
|
|
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](/web-app): use PenguinHarness from the browser.
|
|
- [CLI Reference](/cli): the full list of commands and options.
|
|
- [Architecture Overview](/architecture): how the pieces fit together.
|