Installation and upgrades

Install Harness UICopy Anchor Link

Use uv to keep Harness UI in an isolated tool environment:

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

No source checkout or Node.js is required. If your shell cannot find the command, run uv tool update-shell and restart the shell.

Optional Bash/Zsh shortcut: alias anui='a13n-harness-ui' in your shell profile.

UpgradeCopy Anchor Link

For a uv-tool installation, run a13n-harness-ui update or uv tool upgrade a13n-harness-ui, then restart Harness UI. a13n-harness-ui update needs uv on PATH and runs the upgrade without another prompt. For other installations, use their original package manager.

Startup can check for updates, but never installs one without confirmation. Disable the check for a single invocation with --no-update-check, or permanently with process.terminal_update_check: false in a13n-harness-ui.yaml. See update and failure behavior.

Dependency compatibilityCopy Anchor Link

uv resolves the application and dependencies against its published requirements. Harness UI releases independently against compatible versions of a13n-harness, a13n-stream-protocol, a13n-envd-client and a13n-logging. Upgrade Harness UI itself if an old package's requirements block a dependency update; check any constraints you supplied rather than forcing an incompatible version.

Sandbox runtimeCopy Anchor Link

Full Control needs no Envd download. Sandbox acquires a daemon matching the installed a13n-envd-client version when needed, including after an upgrade. Source builds with version 0.0.0 need an explicit, validated a13n-envd executable for Sandbox. See Envd installation.

Run from sourceCopy Anchor Link

Use the repository's locked environment rather than mixing local code with manually installed dependencies:

git clone https://github.com/converge-ai-labs/agent-foundation.git
cd agent-foundation
make a13n-harness-ui

Follow the repository contribution guide for development prerequisites. The Make target synchronizes dependencies and disables the published-package startup check. After switching branches, run it again or use make sync. After editing UI documentation or navigation, run make a13n-harness-ui-skills to refresh the bundled configuration Skill; the launch target already includes that dependency.

Source documentation tracks main. When using a published wheel, consult the documentation and metadata for that release if an API or setting differs.

WebUICopy Anchor Link

The installed package includes both the TUI and WebUI. Start WebUI with:

a13n-harness-ui webui

Open the printed login link in your browser to configure Models, start conversations, and work with trusted collaborators. The foreground server owns active execution; keep it running while you use WebUI. Native host file and terminal sharing are enabled by default; use --no-share-computer to disable them. See WebUI for access controls, collaboration boundaries, containers, and listener configuration.

Next stepCopy Anchor Link

Complete setup, then find your configuration.