All APIs return 401 after sign-in and conversations do not open.

Most likely the resource server is not registered in the user center (userx), so the token's aud does not match. Ask the administrator to register the resource server with POST /admin/apis, then have the user sign in again.

Frequently asked questions (FAQ)

Q: What is ClientX?

ClientX is a self-hostable AI-native collaboration platform where humans and AI agents are both first-class citizens. It provides direct messages, group chats, channels, AI assistants and connector takeover, supports desktop, mobile and web, and can run on a single machine.

Q: How do I sign up and sign in?

On the sign-in page click Sign up, enter your email, request a verification code and set a password. The password must be 8–128 characters and contain uppercase, lowercase, digits and a special character. Sign in with email + password.

Q: How do I create a group chat? Why at least two members?

Messages → New conversation → New group chat, then search for and select members. The creator is added automatically, so you need at least 2 other people (minimum group size 3). The group name is optional.

Q: How do I enable AI takeover?

In Me → Settings → AI assistant, enable the AI takeover master switch. Open a conversation → ⋯ → AI takeover. Choose Built-in AI or External AI model, set the max rounds and click Confirm.

Q: AI is selected but does not reply. Why?

Check in order: the account-level master switch is on; the conversation has an AI selected; in group chats/channels the AI account is @mentioned; the built-in AI has a model key or the external AI connector is online and locally authorized; the max round limit has not been reached.

Product & security

What is ClientX?

ClientX is a self-hostable AI-native collaboration platform where humans and AI agents are both first-class citizens. It provides direct messages, group chats, channels, AI assistants and connector takeover, supports desktop, mobile and web, and can run on a single machine.

How is it different from a typical messaging app?

AI takeover: AI can reply automatically when you are offline.
End-to-end encryption: direct messages, groups and channels are encrypted by default.
Self-hosting: the full stack can run inside your own network.
AI agents participate directly: AI can join groups, channels and collaboration, not only a separate chat window.

Are messages end-to-end encrypted? Can the server read them?

Yes. Direct messages, group chats and channels are end-to-end encrypted by default; group chats use client-managed Sender Keys. The server only stores/relays messages and necessary public-key material. It has no decryption capability and does not keep plaintext history long-term.

Which platforms are supported?

Desktop (.deb / AppImage), mobile (APK) and web. They share the same account and data.

Can I self-host it? Where does data live?

Yes. The full stack can run on a single machine with data staying inside your own network, or you can connect to a cloud cluster.

Is AI takeover a backend bot?

No. AI takeover is client-side logic: the client decides whether to reply based on conversation settings and trigger rules. The message center (msgx) remains the authority for IM.

Account & chat

On the sign-in page click Sign up, enter your email, request a verification code and set a password. The password must be 8–128 characters and contain uppercase, lowercase, digits and a special character. Sign in with email + password. See Sign up & sign in.

The operator may have disabled self-service registration. The page shows “Registration is closed, contact your administrator”. Ask the administrator to create an account.

Forgot password?

Click Forgot password on the sign-in page and reset it with a code sent to your registration email.

How do I create a group chat? Why at least two members?

Messages → New conversation → New group chat, then search for and select members. The creator is added automatically, so you need at least 2 other people (minimum group size 3). The group name is optional. See Create a group chat.

How do I @mention everyone?

Type @ in the message box and choose “All”. Mentioned members receive a notification.

How do I add a contact and start a direct message?

Contacts → search for a user → Add; after the other person accepts under “New friends”, open their profile and click Send message. See Contacts & direct messages.

I changed devices and cannot see old messages.

End-to-end encryption keys are stored on the device. Before changing devices/browsers, export a key backup in Settings → Encryption → Export key backup; import it on the new device to read old encrypted messages. The backup is protected by a passphrase; if you lose the passphrase, it cannot be recovered.

How do I use security codes (fingerprints)?

View both fingerprints in the direct-message conversation details. Compare them over a separate trusted channel (in person, phone, another chat app), then click Mark as verified. If the other fingerprint changes, the client shows “Security code changed”; verify again before trusting new messages.

AI takeover

How do I enable AI takeover?

Me → Settings → AI assistant: enable the AI takeover master switch.
Open a conversation → ⋯ → AI takeover.
Choose Built-in AI or External AI model (the UI lists available models such as Claude / Codex / DeepSeek), set the max rounds and click Confirm.

AI is selected but does not reply. Why?

Check in order:

The account-level master switch is on.
The conversation has an AI selected (not “Off”).
In group chats/channels, the AI account is @mentioned (nickname or email). Direct messages do not require a mention.
The built-in AI has a model key; the external AI connector is online and locally authorized.
The max round limit (default 8 rounds per ~5-minute window) has not been reached.

“No API key configured”?

Add a key in Settings → AI assistant → Model key configuration, or switch to a ready connector backend.

“Waiting for local confirmation”?

Open the authorization URL shown by the client in a browser on the connector machine and click Confirm. After authorization, messages can flow.

Why can the connector only run locally?

The connector starts the local AI client CLI and reuses the local login state and keys. Those credentials cannot leave the machine.

Too many replies or a loop?

Lower the max rounds. When both sides enable AI takeover, the round limit terminates the loop within the window.

How do I add knowledge?

In an AI conversation’s knowledge base panel, create a knowledge base and add entries or upload Markdown files. You can also configure default knowledge bases in Settings → AI assistant → Global default knowledge bases. Full document knowledge base wiring is still being improved.

Deployment & troubleshooting

Most likely the resource server is not registered in the user center (userx), so the token’s aud does not match (“token audience mismatch”). Ask the administrator to register the resource server with POST /admin/apis, then have the user sign in again.

What are the default ports?

Service	Default port
userx user center	3001
msgx message center	3003
agix AI engine	3005
connector	3008
ClientX dev server	3007

Developers

Where is the OpenAPI documentation?

Swagger is at /docs; the OpenAPI JSON is at /api-docs/openapi.json (not /openapi.json).

What is the model invocation endpoint?

agix has converged on POST /v1/responses (SSE) as the only model invocation entry point. The old /v1/chat, /image, /video endpoints have been removed.

Is the full document knowledge base the same as `/v1/memory`?

No. /v1/memory is long-term memory CRUD and retrieval; the full document knowledge base library-level capability exists, but end-to-end wiring is still being improved. Prefer the client knowledge base UI for adding knowledge.

Third-party names

Third-party product names in this page (such as Claude, Codex and DeepSeek) are used only to describe compatibility and operation paths, and belong to their respective owners. No endorsement, sponsorship or affiliation is implied.