---
title: Quick Start
description: Launch the gateway, TUI, and built-in web surfaces after onboarding.
sidebar_position: 3
---

# Quick Start

## Onboarding

HybridClaw onboarding walks through:

1. accepting `TRUST_MODEL.md`
2. choosing HybridAI auth or a local-only setup
3. opening HybridAI registration/login in the browser when needed
4. pasting the API key back into the CLI or skipping remote auth for a local backend
5. saving the default bot/model plus encrypted runtime secrets

Run it explicitly with:

```bash
hybridclaw onboarding
```

If you plan to run only on Ollama, LM Studio, llama.cpp, or vLLM, onboarding
can skip the remote-provider steps and you can configure the backend later with
`hybridclaw auth login local <backend> [model-id] ...`.

If onboarding finds invalid JSON in `~/.hybridclaw/config.json`, it can offer
to restore the last known-good saved config snapshot or roll back to a tracked
revision before continuing.

## Start The Gateway

```bash
hybridclaw gateway
```

Common variants:

```bash
hybridclaw gateway start --foreground
hybridclaw gateway start --foreground --sandbox=host
```

Use `--sandbox=host` for stdio MCP servers that depend on host binaries such
as `docker`, `node`, or `npx`.

Use `hybridclaw gateway status` to confirm the active sandbox and runtime
metadata. In container mode it also shows the configured image name, resolved
version, and short image id.

## Start The TUI

In a second terminal:

```bash
hybridclaw tui
```

The local TUI shows a startup banner before the first prompt, opens an
interactive approval picker for pending approvals, and prints a resumable
session summary with `hybridclaw tui --resume <sessionId>` on exit.

## Open The Built-In Web Surfaces

With the gateway running locally:

- chat UI: `http://127.0.0.1:9090/chat`
- agent/session dashboard: `http://127.0.0.1:9090/agents`
- admin console: `http://127.0.0.1:9090/admin`
- statistics: `http://127.0.0.1:9090/admin/statistics`
- agent scoreboard: `http://127.0.0.1:9090/admin/agent-scoreboard`
- docs: `http://127.0.0.1:9090/docs`

If `WEB_API_TOKEN` is unset, localhost access opens without a login prompt. If
it is set, `/chat`, `/agents`, and `/admin` all reuse the same token gate.
For access from another machine, keep the gateway on loopback and follow
[Remote Access](../guides/remote-access.md).

Before exposing the gateway beyond localhost, choose the right runtime shape in
[Local vs Cloud Setup](./local-vs-cloud.md). That guide covers when a public
URL is required, how to configure local-only, tunneled, and cloud deployments,
and how to switch between them.

The `/chat` sidebar keeps recent conversations and can search session titles
with contextual snippets, so you can jump back into older browser sessions
without scrolling through the default recent list.
The chat header also shows a live context-usage ring. Use `/context` for the
full context snapshot, and use `/compact` when the ring shows that a long
session is approaching its model window.

Use `/admin/channels` for transport setup, per-channel instructions, and
managed channel secrets, and `/admin/agents` when you need to edit an agent's
allowlisted workspace markdown files, inspect saved revisions, or restore an
earlier version.
Use `/admin/statistics` for activity and cost trends, and
`/admin/agent-scoreboard` to review observed skill scores, reliability, timing,
and CV links.

## Open The Desktop Wrapper From Source

From a source checkout, the macOS desktop wrapper builds the runtime and opens
the same local chat surface in an Electron window:

```bash
npm install
npm run desktop
```

The app reuses an existing local gateway when one is already listening on
`http://127.0.0.1:9090`; otherwise it starts the bundled gateway. The app menu
links to the admin console.

## Ground A Prompt With Files Or Repo Context

- Web chat accepts uploads and pasted clipboard files or images before send.
- TUI queues a copied local file or clipboard image with `/paste` or `Ctrl-V`.
- Inline prompt references supported in chat are `@file:path[:start-end]`,
  `@folder:path`, `@diff`, `@staged`, `@git:<count>`, and
  `@url:https://...`.

Examples:

```text
Summarize @file:README.md and compare it with @url:https://example.com/spec
Explain this change using @diff and @file:src/gateway/gateway-service.ts:900-1040
```

## Channel Integrations

The gateway auto-connects configured channels:

- Slack when `slack.enabled` is true, `SLACK_BOT_TOKEN` is saved, and
  `SLACK_APP_TOKEN` is saved
- Slack Incoming Webhook when `slackWebhook.enabled` is true and the default
  webhook target has a stored SecretRef
- Microsoft Teams when `msteams.enabled` is true and
  `MSTEAMS_APP_PASSWORD` is saved
- Discord when `DISCORD_TOKEN` is set
- Telegram when `telegram.enabled` is true and `TELEGRAM_BOT_TOKEN` is set
- Signal when `signal.enabled` is true and a reachable `signal-cli` compatible
  daemon plus account are configured
- Email when `email.enabled` is true and an email password is configured,
  typically through the stored `EMAIL_PASSWORD` secret
- WhatsApp when linked auth exists under `~/.hybridclaw/credentials/whatsapp`
- iMessage when `imessage.enabled` is true and either local Messages access or
  remote BlueBubbles credentials are configured

For the setup commands and step-by-step flows, start with
[Connect Your First Channel](./first-channel.md) or go straight to
[Channels Overview](../channels/overview.md).
