Harness UI

Harness UI is a TUI and WebUI workbench built on Harness. It is for individuals and trusted small teams working with Agents, Models, tools, Skills, and local projects. Both interfaces use one process-local HarnessUiApp; saved conversations support continuation, but active work is not a durable job queue. For managed access and worker recovery, use Service.

Install and Run

Install the published application with uv:

uv tool install a13n-harness-ui
cd your-repository
a13n-harness-ui

For WebUI, run a13n-harness-ui webui and open the printed login link. Neither installed interface requires a checkout or Node.js. If the command is not on PATH, run uv tool update-shell and reopen your shell.

Upgrade a uv-tool installation with a13n-harness-ui update or uv tool upgrade a13n-harness-ui, then restart it. Use the original package manager for other installations. For source development, run make a13n-harness-ui from the repository root; see CONTRIBUTING.md.

First Use

First launch guides you through a Model connection, model selection, and execution permissions. Setup saves editable files and opens chat; no model call occurs until you send a prompt. To rerun setup later, use a13n-harness-ui setup (outside chat). Run a13n-harness-ui setup --advanced for optional context, reasoning, shell-review, subagent, and instruction choices. To add another resource, use a13n-harness-ui add model or a13n-harness-ui add agent.

Full Control runs commands as your host account. Sandbox requires supported local isolation and never silently falls back; built-in Windows execution is Full Control only. Start with a read-only prompt if you are exploring a repository:

Explain the entry point and the relevant tests. Do not change files.

Inside chat, /help lists actions, /agent changes the complete Agent, /model selects a Model, /resume opens saved conversations, and /environment changes execution permissions. For a one-shot task (which cannot answer an interactive approval), run:

a13n-harness-ui run "Review the current diff" --format json

See the user guide, terminal workflow, and CLI command reference.

Configuration

Use a13n-harness-ui config path, then edit the selected root YAML and its sibling models/, agents/, projects/, mcp/, and extensions/ directories. The default root on Unix-like systems is ~/.a13n-harness-ui/a13n-harness-ui.yaml. An explicit --config PATH selects a separate tree; --data-root PATH selects its data store. Validate edits with a13n-harness-ui config validate. Valid edits affect subsequent Runs, not a Run already in progress. See configuration recipes and precedence.

Automatic Model Prices

The App starts with bundled prices and can update them for later Agent builds. To disable background downloads, set process.pricing_auto_update: false in the root YAML and restart. This does not alter existing usage records or provider prices. See Harness pricing.

Content Plugins

Content Plugins distribute Skills and Markdown subagents from a Git repository; they do not execute plugin Python code. Inspect and trust the source before installing it:

a13n-harness-ui plugin install /path/to/plugin-repository
a13n-harness-ui plugin list
a13n-harness-ui plugin uninstall plugin-reviewer

Uninstall deletes the installed content, including local edits. For the marketplace layout, registration and selection rules, see Skills and Content Plugins.

Built-in Configuration Skill

An Agent with the skills Capability discovers the bundled harness-ui-configuration Skill under /environment/builtin-skills/harness-ui-configuration. It contains release-matched configuration guidance and a generated documentation index; it does not grant extra permissions. The read-only mount also works in projectless and Sandbox conversations.

Source development regenerates the bundle with make a13n-harness-ui-skills after changes to docs/a13n-harness-ui/ or navigation. Generated output is not the source of truth. The build and launch targets prepare it; uv sync alone may leave an editable installation's bundle stale. See bundled Skill.

Local Store Development

Harness UI owns its SQLite schema separately from Service. Generate reviewed revisions against a disposable database from the repository root:

make a13n-harness-ui-db-migrate msg="describe the schema change"

Application startup applies committed migrations, never autogenerates against user data. Storage changes must preserve compatible readers and writes when older processes share the data root; see the storage compatibility contract.

CLI Validation

Select focused checks using Local validation. CLI tests use isolated homes and deterministic models; they need no provider account. Real Local Envd approval tests are opt-in and need a matching native binary and working isolation:

make rust-build
A13N_HARNESS_UI_TEST_SANDBOX=1 A13N_ENVD_EXECUTABLE="$PWD/target/debug/a13n-envd" \
  uv run --locked pytest packages/a13n-harness-ui/tests/test_interactive_run_control.py -k pending_shell

Dependencies

The source version is 0.0.0 with unversioned workspace dependencies. Publishable bounds live in [tool.a13n.release-dependencies]; Harness UI releases independently from Harness and Stream Protocol. Check the manifest and release policy before changing bounds.

Packaging

The wheel and sdist include the CLI, App, WebUI server, compiled WebUI assets, configuration Skill and license; installed users need no Node.js. make a13n-harness-ui-build builds the private browser frontend for release preparation. Sandbox can lazily acquire a native Envd matching the installed client version; Full Control does not need Envd. See installation.

Versioning

The release tag is release/a13n-harness-ui-v<version>. Harness UI and its container image share the application version; the frontend has no separate release. See the release policy and installation/upgrade guide. The Harness UI specification owns the architecture.

Browser UI

a13n-harness-ui webui
a13n-harness-ui webui --host 127.0.0.1 --port 9000
a13n-harness-ui webui --no-share-computer

WebUI serves shared conversations, live output, approvals, setup, configuration, and native Files/Git/terminal panels. Native computer access is enabled by default and operates as the server account, independently of Agent permissions; disable it with --no-share-computer. Participants share instance authority rather than separate authenticated identities. Keep the server running for active work. For access-key options and browser workflows, see Use WebUI; for integration, see the HTTP API.

Docker

The development image packages the same WebUI. The default container command exposes the container account's files, terminals, and mounted paths; select --no-share-computer if that is not wanted.

docker compose -f deploy/docker/compose/a13n-harness-ui.yaml up -d
docker compose -f deploy/docker/compose/a13n-harness-ui.yaml logs harness-ui

The Compose file uses persistent configuration, data, and work volumes. Bind-mounted directories must be writable by UID/GID 10001:10001. Keep startup output private (it may contain a generated login link) and do not run down --volumes to preserve data. See the distribution specification for image build and deployment details.

Windows Local Execution

Built-in Windows execution supports Full Control, not Sandbox. Explicit Sandbox selection fails rather than running with host authority; custom and remote Providers have their own requirements. See execution permissions.

Source Environment Troubleshooting

After switching source branches, run make sync or make a13n-harness-ui to use the checkout's locked dependencies. Installed users should upgrade through the package manager that owns their installation.

TUI defaults

Startup can offer an update; it does not install one without confirmation. Use --no-update-check or process.terminal_update_check: false to disable the check. Run a13n-harness-ui update to request an immediate upgrade. For TUI controls, diagnostics, and recovery, see Use the TUI and Troubleshooting.