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

Files

T

Yaowei Zheng 45bfae6e94 Initialize repository with harness code and assets

Initial import of all source code, config, and README assets: the
packages workspace (cli, core, server, web, docs, landing, skills),
build scripts, tooling config, and CI workflows.

Includes the data-layout revision made on this branch: the local data
root defaults to ~/.penguin/data (PENGUIN_HOME still overrides; the
installer keeps its binaries in ~/.penguin), and every Agent lives
under <project>/agents/<agent>/ — path helpers, the three
agent-enumeration scans, the system prompt, built-in Skills, tests
and docs all follow the new layout.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018ihk8iQuo3kv2aPjAYEPuR

2026-07-19 14:06:53 +08:00

2.5 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://github.com/Prism-Shadow/penguin-harness/releases/latest/download/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 --model-id deepseek-v4-pro --api-key sk-... --set-default

When --provider is omitted, the Provider is inferred from the built-in catalog.
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 / admin123 — 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.5 KiB Raw Blame History