Hydra

Hydra is an AI orchestration platform designed to manage and run autonomous agents ("heads") in a project environment. Each agent runs in an isolated OS sandbox on its own Git worktree, so heads work in parallel without touching the parent checkout or each other.

It consists of a Go backend and a React frontend. The frontend is bundled into the binary, so it can be shipped as a single binary.

Project direction

Hydra's core agent, sandbox, worktree, review, and test-gating workflows are in place. Current development is focused on polishing project-directory chats and the native desktop experience, strengthening cross-platform sandbox isolation, and simplifying the diff and review workflow. See the open roadmap for the remaining ideas and known gaps.

Hydra stores agent and conversation history in one user-scoped database shared by CLI, browser-server, and desktop clients. Its native locations are $XDG_STATE_HOME/hydra/db.sqlite3 on Linux (falling back to ~/.local/state/hydra), ~/Library/Application Support/Hydra/db.sqlite3 on macOS, and %LOCALAPPDATA%\Hydra\db.sqlite3 on Windows. The same state root holds project-specific worktrees, caches, artifacts, logs, and sidecars under projects/<stable-project-id>/. Development uses the checkout's .hydra/local as that state root through HYDRA_STATE_DIR.

$ hydra help
Hydra is an AI agent orchestrator.
It manages AI coding agents running in OS sandboxes and git worktrees.

Usage:
  hydra [command]

Available Commands:
  attach         Attach to a running agent with the ID given
  completion     Generate the autocompletion script for the specified shell
  config         Manage project configuration
  help           Help about any command
  host-run       Request the user's approval to run a command on the host (outside the sandbox)
  kill           Kill the head with the selected ID
  list           List all Hydra agents
  merge          Merge a head's changes into the current branch and kill it (unless --keep)
  server         Run a web server
  set-base       Change a head's base branch (metadata only; does not rebase commits)
  spawn          Spawn a new sandboxed AI agent for the given prompt
  tui            Open the interactive agent dashboard

Flags:
      --debug     Print full stack traces on error
  -h, --help      help for hydra
  -v, --version   version for hydra

Use "hydra [command] --help" for more information about a command.

Platform support

• Linux: fully supported. Sandboxing uses bubblewrap (mount namespaces + seccomp), and hard network egress filtering uses pasta + nftables; Hydra provisions these helper binaries automatically (mage tools:ensure).
• macOS: builds and cross-compiles cleanly; the Seatbelt sandbox backend is partially implemented. See docs/macos-support.md for the audit and implementation plan.
• Windows: not yet supported natively (the binary builds; sandboxing and PTY sessions are stubbed). Running Hydra inside WSL2 works with the full Linux feature set. See docs/windows-support.md for the audit and implementation plan.

Getting Started

Prerequisites

• Go
• Mage
• Node.js 24+ (for the frontend; runs the build scripts directly via its native TypeScript support)
• npm (ships with Node) or, optionally, aube - see below
• Git

Building the experimental standalone Linux desktop shell additionally requires GTK 4 and WebKitGTK 6 development files. On Ubuntu 24.04 and derivatives:

sudo apt install libwebkitgtk-6.0-dev

The frontend's package installs and package.json scripts run through npm by default, since it ships with Node and needs no extra setup. If aube is on your PATH, mage uses it instead for a faster install - it reads and writes the same web/package-lock.json, so the choice never affects the repo. Any npm-compatible package manager (aube, pnpm, yarn, bun) works if you run the web build by hand; only npm and aube are auto-detected.

Running

Build the entire project (backend and frontend bundled in single hydra binary):

mage build

Run the server:

mage run

The development server stamps the current HEAD into its build information, which is shown in Settings -> About alongside the development runtime details.

Build the experimental Linux desktop shell separately, then open a registered project. It reuses the user-global daemon or starts the bundled backend:

go build -tags hydra_desktop -o hydra-desktop ./cmd/hydra-desktop
./hydra-desktop -project /path/to/project

For Linux desktop performance investigation, add --devtools to enable the WebKit Web Inspector and its Timelines recorder. Add --compositing-indicators to draw accelerated-layer borders and repaint counters. The same options work with mage runDesktopLocal through HYDRA_DESKTOP_DEVTOOLS=1 and HYDRA_DESKTOP_COMPOSITING_INDICATORS=1.

For normal development, build or build-and-run the native app for the current operating system:

mage buildDesktop
mage runDesktop
mage runDesktopLocal

Installed desktop builds can be activated with constrained hydra:// links; see Desktop deep links for the supported grammar, examples, platform status, and security rules.

buildDesktop selects the current host. Release builders and platform-specific development can select explicitly with mage buildDesktopLinux, mage buildDesktopMac, or mage buildDesktopWindows; mage buildDesktopAll invokes the complete native build matrix and therefore belongs on an orchestrator with matching platform builders/toolchains.

mage runDesktop uses the stable production runtime socket and OS-standard global database, but owns its development backend: every launch loads the newly built binary, and closing the app or pressing Ctrl+C stops that backend. It actively clears inherited development database, runtime, and listener variables, so this remains true when it is invoked from a terminal opened by a development Hydra. mage run and mage runDesktopLocal instead use the checkout-local development database and the same checkout-specific runtime socket and generated-state subtree, so they can intentionally share one development backend without touching production heads. A directly launched Linux desktop build also defaults to production state; local mode requires the marker supplied by runDesktopLocal. Runtime sockets stay in the OS runtime directory rather than persistent database storage; on Linux these are $XDG_RUNTIME_DIR/hydra/daemon.sock for production and a checkout-keyed child of $XDG_RUNTIME_DIR/hydra/ for development. The desktop backend uses an OS-assigned loopback port. Windows builds additionally require HYDRA_PORTABLE_GIT to point at an extracted official PortableGit distribution. On Linux, closing either Mage desktop runner or pressing Ctrl+C stops the desktop daemon owned by that command. runDesktopLocal still leaves an existing mage run daemon alive.

The separate build keeps the normal hydra CLI free of GTK/WebKit runtime dependencies. The project flag is optional; without it the app opens the global service in Hydra's built-in Chat project. -url http://127.0.0.1:<port> remains available for shell development. Ctrl+N opens another native window sharing the same WebKit profile and backend. External HTTP(S) links open in the system browser; cross-origin redirects and non-web schemes are blocked in the WebView.

Install it as a systemd --user service, so it comes up on login and survives your terminal closing:

mage deploy:setup     # once - generates the auth key for non-localhost access
mage deploy:service

From then on the web UI's update button rebuilds and restarts the server for you: it builds while the running server keeps serving, and only swaps the binary once the build succeeds and the new one is proven to start. See docs/deployment.md.

For frontend work, mage devFast runs Vite with hot-module-replacement in front of the Go API, and mage demo does the same against mock data.

See AGENTS.md/CLAUDE.md/GEMINI.md for more instructions.

Documentation

• Diff Artifacts - render screenshots and videos of a checkout and compare them across a diff (including .webm video diffing).
• Test gate - per-project test runners, the tests panel, and how results gate merging.
• Screenshots - how the automated UI screenshot pipeline works and how to add a screenshot.
• Agent page internals - the diff viewer, sticky headers, and per-agent view state in the web UI.
• Chat mode - how Claude and Codex chat-mode heads work: the normalized event log, the socket protocol, and how the chat renders.
• macOS support - darwin sandbox audit and plan.
• Windows support - Windows audit and plan.