> ## Documentation Index > Fetch the complete documentation index at: https://amd-gaia.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Terminal Hub > Browse, install, and run GAIA agents without leaving the terminal — with a readiness check that fixes what it can and tells you what it can't. The Terminal Hub is GAIA's terminal-native front door. It lists the agents you can run, installs them, and — before it hands you a chat prompt — checks that everything the agent needs is actually working. Where it can fix a problem itself, one key does it. Where it can't, it says so and gives you the exact command. ```bash theme={null} cd tui && make build # -> tui/bin/gaia ./tui/bin/gaia ``` The hub is a Go binary and is **not yet distributed** — no release carries a `gaia--` asset, `pip install amd-gaia` does not provide it, and the Python CLI has no `tui` subcommand (`gaia tui` exits 2 today). Building from source is the only way to get it. Once it ships as a hub component, this page will name the download instead. The Terminal Hub and the [Agent UI](/docs/guides/agent-ui) are two front ends over the same agents and the same background service. Use the hub when you live in a terminal or are on a headless box; use the Agent UI when you want file drops, rendered cards, and a browser. `gaia tui` is the Go terminal binary. Building from source it is `tui/bin/gaia` (`cd tui && make build`) — it accepts a leading `tui` word and drops it, so `./tui/bin/gaia` and `./tui/bin/gaia tui` open the same screen. See the [CLI reference](/docs/reference/cli#terminal-hub-gaia-tui) for its non-interactive subcommands. ## The hub screen The hub opens on the agent list, grouped into three categories: ``` G A I A Local AI Agent Hub — by AMD Installed: 1 Installed (1) Available (0) Coming Soon (12) ──────────────────────────────────────────────────────────────────────────── ▸ ● mail Email Triage v0.5.0 GAIA email triage agent — read, triage, organize, and reply to Gmail/Outlook locally productivity enter run · i install · d remove · / search · tab category · v vote · r refresh · ? help · q quit ``` * **Installed** — on this machine, ready to run. * **Available** — published on the Agent Hub, not installed yet. On a fresh machine Email Triage starts here. * **Coming Soon** — announced but not published. These can't be installed; you can vote for them. | Key | What it does | | ------------------- | ----------------------------------------- | | `Enter` | Run the selected agent | | `i` | Install it (or update it) | | `d` | Uninstall it (asks first) | | `r` | Refresh the agent list from the Agent Hub | | `/` | Search agents | | `Tab` / `Shift+Tab` | Next / previous category | | `v` | Vote for a coming-soon agent | | `?` | Toggle the help overlay | | `q`, `Ctrl+C` | Quit | `Backspace` is deliberately unbound. Everyone presses it meaning "go back", and on this screen that would be one keystroke away from a destructive action. Voting sends only the agent ID to amd-gaia.ai — no personal data. ## Installing an agent Select it and press `i`. That is the whole flow — there is no shell command you need to remember. (For scripts and CI there are non-interactive equivalents; see the [CLI reference](/docs/reference/cli#terminal-hub-gaia-tui).) An agent outside the `verified` security tier runs third-party code on your machine, so GAIA asks first rather than installing quietly. The prompt names what you're agreeing to — the agent id, version, publisher, security tier, download size, and the access it declares — plus the background service's own reason for refusing the install until you say yes. **Cancel is focused by default.** `y` trusts and installs, `n` or `Esc` cancels, `←`/`→` moves between the buttons, `Enter` picks the focused one. If an install fails, the result box stays up with the reason. `i` or `r` retries it; `Esc`, `q`, `n`, or `Enter` dismisses. Dismissing never cancels an install that is still running — the background service owns that work, and a half-removed install directory is worse than waiting. ## The readiness check Press `Enter` on an installed agent and GAIA checks its preconditions before starting it. This runs on **every** launch, not just the first, because any of these can break between sessions. ``` Getting Email Triage ready 1 of 5 ready ────────────────────────────────────────────────────────────────────────────── [ok] Background service running (pid 47979) · host API v1.1 > [!] Email Triage agent installed, not started The Email Triage agent is registered but its state is "stopped". Start it — the background service supervises it from then on. run: gaia daemon start-agent email look: ~/.gaia/agents/email/logs/ f start the agent [ ] Local AI — checked once "Email Triage agent" is fixed [ ] AI model — checked once "Email Triage agent" is fixed [ ] Mailbox — checked once "Email Triage agent" is fixed ────────────────────────────────────────────────────────────────────────────── f start the agent · r re-check · d details · esc back ``` Two things on this screen are worth knowing about, because they change how you read it. **Rows below a failure aren't results — they're deferred.** `checked once "X" is fixed` means exactly that: the check did not run, so the screen never shows you a verdict it couldn't have reached. A `[ ]` row is not a pass and not a failure. **Where a fix can be automated, it's one key.** The failing row offers `f` and the footer repeats it. `f` on the row above starts the agent; the count went `1 of 5` → `2 of 5` and the check moved on to the next row on its own. ### Markers | Marker | Meaning | | ------ | --------------------------------------------------------------- | | `[ok]` | Checked and working | | `[!]` | Checked and failed | | `[?]` | Tried, but couldn't establish an answer either way — not a pass | | `[ ]` | Not checked yet (waiting on the row above) | | `[..]` | Checking now | The marker and the words carry the state on their own, so the screen reads the same on a monochrome terminal or piped to a file. ### Keys | Key | What it does | | ------------------------ | ------------------------------------------------------------------ | | `f` | Apply the focused row's fix — shown only when that row has one | | `r` | Re-check everything | | `d` | Toggle the raw answer the check got — paste this into a bug report | | `↑` / `↓` (or `k` / `j`) | Move between rows | | `Enter` | Start anyway — offered only when nothing is outright broken | | `Esc` | Back to the hub | | `Ctrl+C` | Quit GAIA | `Enter` is not offered while a row is failing. Press it anyway and the screen names the blocker rather than starting something that would fail on its first action. It *is* offered when a row is merely unverified (`[?]`) — nothing there says anything is broken. ### When the fix can't be automated Some fixes can't be done from a terminal UI. GAIA does not open a browser behind your back or half-implement a flow that already works elsewhere. It hands you the command and waits: ``` Reconnect Gmail for Email Triage ────────────────────────────────────────────────────────────────────────────── The account is linked and granted, but reading it just failed, so the very first thing Email Triage does would fail too. It said: no forwarded 'google' credential is available to the email sidecar. This cannot be done from here — it opens a browser sign-in. Run this in another terminal, then come back and press r. gaia connectors connect google --grant-agent installed:email --scopes openid email profile https://www.googleapis.com/auth/gmail.modify https://www.googleapis.com/auth/gmail.send look: https://amd-gaia.ai/docs/guides/email r re-check · esc back to the checks ``` Run the command in another terminal, come back, and press `r`. The re-check is the loop: fix something, `r`, read the new count. `Esc` goes back to the checks without re-running them. Other rows behave the same way when they can't self-heal — the `Local AI` row, for instance, offers no `f` (the model server keeps the terminal it starts in), so the footer drops to `r re-check · d details · esc back` and the row prints the command to run. ### Filing a bug about a check Press `d` on the failing row. That shows the raw answer the probe got — the HTTP status, the body, the timing — which is what a maintainer needs and what prose summaries lose. ## The chat screen Once the checks clear, GAIA starts the agent and drops you into the conversation. The chrome is the same for every agent — the agent's name appears in the title bar, the `Connected to:` line, and the status line: ``` GAIA │ ──────────────────────────────────────────────────────────────────────────────── Welcome to GAIA Connected to: Type a message and press Enter to start chatting. Type /help for available commands. ──────────────────────────────────────────────────────────────────────────────── ┃ Ask anything... (Enter to send, Ctrl+C to quit) ● connected Esc back · Ctrl+C quit ``` | Key | What it does | | --------------- | -------------------------------------- | | `Enter` | Send message | | `Esc` | Cancel streaming, or return to the hub | | `PgUp` / `PgDn` | Scroll the conversation | | `Ctrl+C` | Quit | | Command | What it does | | -------- | ------------------------- | | `/help` | Show the shortcut overlay | | `/hub` | Return to the Agent Hub | | `/clear` | Clear the conversation | ## Next steps * [Email Triage](/docs/guides/email) — the first agent on the hub, end to end. * [CLI reference](/docs/reference/cli#terminal-hub-gaia-tui) — the non-interactive subcommands (`list`, `status`, `run --query`) and their exit codes. * [Driving the TUI programmatically](/docs/guides/mcp/tui) — the control API, for tests and assistants. Not needed for normal use.