penguin-harness/packages/docs/content/web-app.en.md

title, description

title	description
Web App Guide	A page-by-page guide to the Web App — login, chat, Agent management, models, usage, and traces.

PenguinHarness ships with a ready-to-use Web App: multi-user login, streaming chat, Agent configuration, model and usage management all happen in the browser. This guide walks through the app page by page. For installation and first launch, see the Quickstart.

Source layout

packages/web/src
├── api/          # fetch wrapper · one function per API (DTOs type-only from @prismshadow/penguin-server/api) · SSE wrapper
├── state/        # auth / project / sessions / theme / locale contexts
├── lib/omni/     # OmniMessage stream → view-model reducer; connect-first + dedup stream controller
├── components/   # ui primitives (modal / drawer / select …) and the app layout
└── features/     # chat / agents / skills / models / usage / traces / benchmark / admin pages

Startup and Login

penguin web
# open http://127.0.0.1:7364

The initial account is admin / penguin-2026. There is no self-registration: accounts are created by an admin on the user-management page, and every new user automatically gets an independent initial Project named <userId>-default_project. While the initial password is still in use, a banner prompts the user to change it.

Logins persist for 7 days with sliding renewal; an admin password reset invalidates all of that user's login sessions.

The interface language (中文 / English / system) and theme (light / dark / system) can be switched at any time.

Chat (/chat)

Creating a Conversation

A new conversation starts as a draft: pick the Agent, the Workspace (via a server-side directory browser), the approval mode, the model, and the thinking level before sending the first message. The Session is created on first send, and from then on its model and Workspace are locked. Switching the thinking level or the model in the draft makes the switched-to value the new default: the level is written back to the selected Agent's model.thinking_level immediately, and the picked model carries over as the next conversation's default. Inside an active session the thinking level is a per-turn parameter: the composer's picker starts out showing the Agent config's level and auto-follows it until touched (sends omit the level, so config edits keep taking effect); a pick sticks for the session and rides on every subsequent send (never written back to the Agent config); the model stays locked per session — the /model command switches models the way the @ handoff does: it opens a new session for the same Agent on the picked model, keeping the current Workspace, whose first message carries a [model_switch_from] source block (source session id, Trace file path, previous model) followed by whatever was left in the composer (an interface-language auto-line when empty). In the new session that block collapses into a "switched model" banner linking back to the source conversation, and the model reads the source Trace file itself when it needs the earlier history.

There are four approval modes: allow-all, deny-all, read-only (only read-only tools pass), and always-ask. See Tools and Approvals.

Streaming Rendering

• Model text renders token by token; thinking blocks are collapsible;
• Tool cards expand to show arguments and output, with a live timer while running;
• Subagents appear as nested cards; context compaction shows a banner;
• After each Task, a stats line shows tokens, TPS, elapsed time, and cost.

Input and Shortcuts

• Enter sends, Shift+Enter inserts a newline, and images can be pasted;
• Typing / opens the slash menu: trigger context compaction (/compact) or toggle installed Skills — chosen Skills are sent along with the message in a [use_skills] block;
• While a Task is running the input stays live and the toolbar keeps a single action button: an empty composer shows Stop, and typing turns it into Send, whose behavior follows the mid-run send mode from the toolbar's More-settings popover (a compact extensible settings panel, also available in draft state; the choice is remembered): Steer (default) delivers the text mid-run as a [user_steering] user message with the next turn, Queue holds the whole message server-side as a follow-up and auto-sends it as an ordinary new message when the run finishes (an "N queued" hint shows near the input until then; the queue survives page reloads);
• Typing @ mentions another Agent to hand the conversation over to it;
• When human approval is required, tool calls show inline allow/deny buttons in the message stream; the approval mode can be changed mid-Session.

Files Panel

The files panel browses the Workspace tree, previews files (Markdown / HTML rendered), uploads files (≤ 14MB each), and downloads them.

Agent Management (/agents)

The list page creates and deletes Agents; clicking through opens the /agents/:agentId settings page, organized into tabs:

Tab	Contents
Overview	Basic info, export / import of Agent State snapshots, and restoring the default configuration (overwrites customizations, keeping only name/description)
Prompt	AGENTS.md and system_prompt
Runtime	Runtime parameters such as max_turns, model., compaction.
Tools	Built-in tool table (incl. per-tool call_description switches) and MCP server JSON configuration
Vault	Environment-variable entries with masked values
Schedule	Scheduled tasks (TOML-defined): create, edit, toggle, delete

Scheduled tasks fire on a fixed period (minimum 5 minutes) and run only while the service is running.

Skill Library (/skills)

Browse the Skill library by group, install Skills onto an Agent, or quick-invoke one into a chat draft.

Model Configuration (/models)

A per-Project model table grouped by provider. Models can be added and edited: identity is the (provider, model_id) pair, credentials are masked, and context window, max output tokens (a per-model cap overriding the Agent's model.max_tokens — lower it for small-context models), pricing, and the vision flag are configurable. You can set the default model and the vision model (which reads images on behalf of session models without image input), and run a connectivity test on any entry. Only Project owners can edit. For concepts, see Models and Providers.

Usage (/usage)

• Filters: Agent, model, date range;
• Summary cards: today / last 7 days / cumulative;
• Charts: per-Agent share, per-model success rates, daily Token and cost trends;
• A server error panel summarizing recent server-side error records.

Trace Browser (/traces)

Drill down Agent → date → Session → Trace file. Per-turn cards show a context-occupancy donut and a cache breakdown, alongside a lane-based execution timeline and the full event list. For the storage model, see Sessions and Traces.

Benchmark (/benchmark)

Read-only scoreboards per Benchmark: switch the metric (score / cost / duration), drill into each Case's runs, and jump to the linked Session and Trace. Works together with the Self-Improvement workflow.

User Administration (/admin/users)

Admin only: list and create users, reset passwords, and delete users (the built-in admin cannot be deleted).

Projects and Members

The sidebar provides a Project switcher and supports creating new Projects. Members have two roles, owner and member: owners manage membership and exclusively edit models, Vault, and Schedules, as well as perform deletions.

Production Deployment

The server hosts the built SPA itself (same origin, SPA fallback), so a single penguin web or penguin server process is all production needs. The npm package bundles the frontend build; to serve a custom static directory, override it with PENGUIN_WEB_DIST — see the Configuration Reference.