Quickstart

The shortest path from nothing to a working chat: install, prepare credentials, configure the app, chat. Everything on this page happens in installers and app settings — no terminal required.

1. Download and install

There are two things to install, and they are independent.

	What you get	Needed for
Client	The desktop window	Chatting in the desktop app
Agent	The engine, plus the local Session service	Every chat, whichever window you prefer

Chatting on one computer needs both: the Client alone has no engine, and the Agent alone has no desktop window. The easiest path is to install the Client first — on first launch it offers to install the engine on the same computer. Accept, and most of this page is done for you.

Client (the window)

Open the Download page and pick your platform.
macOS — open the .dmg and drag Xiaohe to Applications. The first launch may need right-click → Open.
Linux — sudo dpkg -i Xiaohe_*_amd64.deb.
Windows — run Xiaohe_*_x64-setup.exe. If SmartScreen appears, choose More info → Run anyway.

No account is required to install.

Agent (the engine)

Supported on macOS Apple Silicon, Linux x86_64, and Windows x86_64.

Windows — download xiaohe-installer.exe and double-click it. The wizard walks through language → runtime → Node.js → Claude (CLI and SDK, about 250 MB) → DeepSeek API key → desktop Client → review → Install. Confirm the UAC prompt if one appears.
macOS and Linux — run this in a terminal:
```
curl -fsSL https://download.xiaohe.team/xiaohe-agent/install.sh | bash
```
The script installs the engine and offers the desktop Client. Answer yes to “Issue a local Session…” so the chat key is written for you.

The Windows wizard also asks for a DeepSeek key and can install the Client for you. On macOS and Linux, set the model afterwards in the app — see step 3.

2. Account and credentials

Everything the app may ask for, in one place. None of it is needed before install; pick up each credential when a settings tab asks for it.

Credential	Where it comes from	Needed when
Model provider key (DeepSeek, Kimi, …)	The provider's own platform, e.g. the DeepSeek platform	Always — chat cannot answer without a model. The Model gateway is an alternative that skips provider accounts
Session key `xh_ses_…`	Issued by the Session service itself — a local install writes it into the app automatically	Every window, every shape. Devices signed into the same account receive it through the account
License `xh_lic_…`	The account center — register with your email, top up, and claim a license	Desktop Pro features. A new install includes about seven days of trial
Cloud key `xh_cld_…`	The account center, alongside the license	Cloud services — MCP, DERP, and the LLM gateway
Private network	Joined in-app, no separate app to install	Only for reaching a Session on another machine of yours

Register at the account center with your email; topping up there feeds the model gateway balance and the Pro purchase. Signing in under Settings → Account links this computer and your phone to that account, so the Session key syncs and your machines find each other.

Open the desktop app and work through the settings tabs. The order below is the order that unblocks a chat.

Sign in. Under Settings → Account, sign in with the account from step 2. This links the app to your account — the Session key syncs to your other devices, and your machines can find each other.
License and cloud key. Under Settings → License & Key, paste the license xh_lic_… and the cloud key xh_cld_… if you have them. Chat works without both — they only gate Pro features and cloud services.
Give it a model. Under Settings → Assistant, pick a provider and paste its key. Without a model the chat window opens but never answers.
Start the local service. Under Settings → Server, press Start local service. This installs and starts the Session service on this computer and writes the Session key for you — nothing to paste. To reach a Session on another machine instead, use Add remote server with that machine's address and key.
Chat. New session, send a message.

4. The settings tabs

The desktop settings are a handful of tabs. Two are required for a working chat; the rest are optional.

Tab	What it does	Required?
Assistant	Model providers and keys	Yes — without a model, no replies
Server	Session servers: start the local service, add remote servers, test keys, see status	Yes — without a server, no chat
Account	Account sign-in; links your computers and phone so Session keys sync and machines find each other	No — chat works without it; needed for multi-device
License & Key	Pro license and cloud key (MCP, DERP, LLM)	No — a trial covers the first days; required later for Pro and cloud services
Tailnet	The in-app private network; join it to reach Sessions on your other machines	No — only for multi-machine setups
Updates	App updater and channel	No — automatic by default

The remaining tabs — Dependencies, Profile, General (language, theme, font), Voice, Usage & Cost, Feedback — are personal preferences and diagnostics, none required for chat.

Other windows

The same chat works in two more windows, once a Session exists somewhere:

Web UI — open http://127.0.0.1:8110/ in a browser on the machine that runs the Session, and paste the xh_ses_… key when asked. The browser keeps its own settings, so each browser pastes once.
iPhone — the phone runs no Session; it always connects to one you already have. Under Settings → Account sign in with the account, then under Settings → Server → Add remote server enter the address and key. If the computer is only reachable over the private network, join it under Settings → Tailnet first.

Troubleshooting

Symptom	What to try
Offline	Under Settings → Server, press Start local service
401, or a rejected key	Restart the local service, then reopen the app. Still stuck? Sign the device into the same account so the key syncs, or re-issue one
An activation gate	Paste the license under Settings → License & Key, or use the Web UI, which has no desktop gate
A model error	Check Settings → Assistant on the machine that runs the Session

Keeping things updated

The Client updates itself under Settings → Updates. Updating the engine is a terminal command — see Advanced.

Where to go next

Goal	Next step
Terminal chat, server commands, model providers	Advanced
Integrate with your own tools	Session API
One key for DeepSeek, Kimi, and Claude	Model gateway

1. Download and install​

Client (the window)​

Agent (the engine)​

2. Account and credentials​

3. Sign in, fill in, start the server​

4. The settings tabs​

Other windows​

Troubleshooting​

Keeping things updated​

Where to go next​