Installation

Install, wire up an agent, and connect an external MCP client.

Install

One-liner. Fetches the latest signed release and runs it.

macOS & Linux

curl -fsSL https://hyperia.nuts.services/install.sh | sh

Windows

powershell -c "irm https://hyperia.nuts.services/install.ps1 | iex"

Prefer to grab the artifact yourself? All signed builds live at github.com/DeepBlueDynamics/hyperia/releases.

What actually ships

Update

No auto-update yet — updating is re-running the same one-liner:

curl -fsSL https://hyperia.nuts.services/install.sh | sh          # macOS / Linux
powershell -c "irm https://hyperia.nuts.services/install.ps1 | iex"  # Windows

The pane Chooser shows your running version in its footer. When the site has a newer build, that footer flags vX.Y.Z available. Two buttons sit next to it:

[copy] copies the update command to your clipboard. [run] opens a shell with the command already typed at the prompt. Neither one auto-executes — you press Enter to update.

First launch

Hyperia opens with an empty pane and the sidecar (hyperia-sidecar) starts on port 9800. The Chooser — the picker that opens whenever you split or add a tab — has three rows:

Hotkeys work immediately from the Chooser — no click required.

Auto-detected shells

PowerShell, CMD, Git Bash, and every installed WSL distro on Windows. zsh, bash, and fish on macOS / Linux (whichever are on PATH).

Auto-detected agents

Any of these on your PATH show up in the New Agent picker:

Claude Code   ·   Nemesis8   ·   Nemesis8 Danger
Antigravity   ·   Codex     ·   OpenCode
Grok          ·   Hermes    ·   Pi

Missing ones live under install an agent — copy the install command or open it in a shell. Nothing auto-runs.

Agent setup

The built-in Ghost agent is configured through a dedicated panel — no more pasting keys into the terminal.

Open the config panel

From the New Agent row of the Chooser, click the gear icon next to Hyperia in the pulldown. That opens the config panel at:

http://localhost:9800/agent/config

You can also reach it from any install view's [configure] button.

What lives in the config panel

One page, four blocks:

Provider & model — Anthropic, OpenAI, Gemini, or Ollama, with a curated model picker per provider (current tags only; stale IDs are pruned automatically).

API keys — one field per configured provider. Keys never leave your machine except to the provider you selected. Stored in ~/.hyperia/hyperia.json.

Services — toggles for the DBD service fleet: nemesis8, shivvr, grub, transcription, sailfish.

nuts.services login — attach a NUTS ahp_ token so services that require identity (grub, shivvr, transcription) authenticate without you re-pasting.

Readiness

Open the Doctor dashboard at any time to see what's wired up and what's missing:

http://localhost:9800/dashboard

Connect an external MCP agent

Hyperia's sidecar publishes a streamable-HTTP MCP endpoint that any external MCP client can point at:

http://localhost:9800/mcp

Claude Code

claude mcp add --transport http hyperia http://localhost:9800/mcp

Add --scope user to make it available across every project.

OpenAI Codex

Add to ~/.codex/config.toml:

[mcp_servers.hyperia]
url = "http://localhost:9800/mcp"

Google Antigravity

Settings → MCP → Add Server, paste the URL. Or edit the Antigravity MCP config directly with serverUrl set to http://localhost:9800/mcp.

Tool surface

Hyperia exposes roughly ~124 tools today, hidden behind doors — a progressive-disclosure model. Clients see a small core surface plus open_tools-style entry points that reveal categories on demand. Nothing dumps 100+ schemas at connect time.

Identity & consent

Two tiers, and the difference matters:

Read-only tools — status, screen reads, search — work anonymously. No token needed.

State-changing tools — run commands, type keys, open panes, read someone else's sticky — require identity plus human consent. Every one of these shows a prompt in the Hyperia UI before it executes.

In-pane agents (like the Ghost, or a Claude Code session launched inside a Hyperia terminal) get HYPERIA_AGENT_TOKEN injected into their environment automatically. Your MCP client picks it up and attaches it as the Authorization header — nothing to configure.

External agents (running outside a Hyperia pane) call the request_token tool once to mint a persistent hyp_agent_… token, then set Authorization: Bearer <that token> on the MCP client and reconnect:

claude mcp add --transport http --scope user hyperia \
  http://localhost:9800/mcp \
  --header "Authorization: Bearer hyp_agent_..."

After reconnect, state-changing tools work — subject to the user approving the specific action in the Hyperia UI.

What agents can do once connected

Beyond terminal control, the current tool surface includes:

Spoken summaries — hyperia_spoken_summary renders a short text-to-speech summary using the local Kokoro voice model, so long-running work can talk to the room instead of blocking on the pane.

Sticky notes — floating scratchpads shared between humans and agents. Create, search (BM25 over name + body), read, open, schedule. Handy for handoffs and running lists.

Pane pulses & watchdogs — pane_pulse_set plus pane_on_idle / pane_busy / pane_idle for waiting on human input without polling.

Web-pane browsing — open_web_pane, web_pane_content, web_pane_eval, web_pane_mouse for driving embedded browser tabs.

Config file

All state lives in a single JSON file:

~/.hyperia/hyperia.json                # macOS / Linux
%USERPROFILE%\.hyperia\hyperia.json    # Windows

The shape:

{
  "config": {
    "agent":   { "provider": "anthropic", "model": "claude-sonnet-5" },
    "providers": {
      "anthropic": { "token": "sk-ant-...", "endpoint": "https://api.anthropic.com" },
      "openai":    { "token": "sk-..." },
      "gemini":    { "token": "..." },
      "ollama":    { "endpoint": "http://localhost:11434" }
    },
    "tts": { "recipient": "base" },
    "defaultProfile": "PowerShell 7.5.5",
    "profiles": [
      { "name": "My Agent", "kind": "agent",
        "config": { "shell": "cmd.exe", "shellArgs": ["/c", "claude"] } }
    ],
    "fontSize": 16,
    "fontFamily": "Menlo, Consolas, monospace",
    "cursorShape": "BEAM",
    "stickyFontSize": 14,
    "sidecarPort": 9800
  }
}

Edit the file directly or open it via Settings → Edit Config. Hyperia watches the file for changes; most keys take effect immediately. Sidecar port and shell profiles require a restart.

Other paths

Sidecar port

The sidecar defaults to 9800. Override with the HYPERIA_PORT environment variable or config.sidecarPort. The MCP endpoint and the /dashboard URL follow whichever value is active — update any MCP client registrations when you change it.

Uninstall

Windows: uninstall from Settings → Apps, or run the uninstaller shortcut. Removes the app and the bundled sidecar.

macOS: drag Hyperia.app to the Trash.

Linux: sudo apt remove hyperia, or delete the AppImage.

Your state under ~/.hyperia/ is left in place. To wipe everything — config, keys, tokens, voice model, notes:

rm -rf ~/.hyperia                                # macOS / Linux
Remove-Item -Recurse -Force $env:USERPROFILE\.hyperia   # Windows