Overview
Xiaohe Agent has three layers, and most setup confusion comes from missing one of them.
| Layer | What it is | Where it lives |
|---|---|---|
| Agent | The engine — the xiaohe runtime, with its skills and your workspace | A computer you control |
| Session | An HTTP service the engine speaks through. A window talks to a Session, never to the engine directly | The same computer, another machine of yours, or a host someone runs for you |
| Window | The chat interface — Desktop Client, Web UI, or iPhone | Whatever device you are holding |
Installing the Agent and starting a Session is one step. The window is a separate install, and it can sit on a different device.
Where a Session can live
A window and its Session need not be on the same machine.
| Shape | The Session runs on | The window connects to |
|---|---|---|
| Local | This computer | http://127.0.0.1:8110 |
| Private network | Another computer of yours | That machine's private-network address, for example http://100.64.x.x:8110 |
| Hosted | A machine your operator runs | The address and key the operator gives you |
All three shapes need the same two things: an address and a Session key.
Four credentials, do not mix them
| Used in | What it grants | Looks like |
|---|---|---|
| Settings → Assistant | Model replies | The provider's own key format |
| Settings → Server | Chat access to one Session. A local install writes it for you, and devices on the same account sync it | xh_ses_… |
| Settings → License & Key → License | Desktop Pro features, from the account center | xh_lic_… |
| Settings → License & Key → Cloud key | Cloud services — MCP, DERP, and the LLM gateway | xh_cld_… |
A Session key does not unlock Pro, and a license does not start a chat. Most “it does not work” reports are one of these two in the wrong field.
Signing in under Settings → Account makes this computer and your phone one account: the Session key travels with the login, and your other machines appear in the device list.
How the docs are organized
- Quickstart — the shortest path from nothing to a working chat: install, account and credentials, configure the app. No terminal required.
- Advanced — the terminal way: the
xiaohecommand, terminal chat, running a Session for windows, model providers, and where the API references live. - Workspace and skills — what
xiaohe workspace initcreates,PERSONAL.md, where skills come from, and how to repair or align the workspace. - Continuous session (Jarvis mode) — the long-lived conversation: how it works, memory, background tasks, and troubleshooting.