Getting Started with Hagency #

This is the complete first-time walkthrough: from "I've never heard of Matrix" to "I'm chatting with my team on my own server". If any concept below feels unfamiliar, read The Matrix Protocol first — it defines all the words we use here and includes the full client comparison.

Step 1 — Create your server on Hagency #

Visit hagency.cloud and click Get started.

  1. Register a Hagency platform account and complete email verification, or sign in with a supported OAuth provider.
  2. Choose a plan.
  3. Configure your server address: choose a subdomain for <subdomain>.hagency.cloud, and optionally enter your own Matrix ID domain. The Matrix identity domain is fixed when the server is created.
  4. Review the address and plan, then click Create Hagency Server.

Hagency Cloud provisions Hagency Server, an integrated application built on Matrix, with messaging, authentication, administration, projects and agents. Each workspace has isolated databases on shared database infrastructure. Element Web is optional.

After provisioning, open the server's Account center (/auth/) and register the first administrator. To manage users, rooms and usage from the platform, authorize platform management in the server's settings. Agent execution requires a connected Hagency desktop client.

Use Projects and Agents #

Download Hagency Desktop, sign in with your server address, then follow Agent settings to create an Agent, connect a model account on its execution device and start responding. For ordinary Matrix chat, continue with Element below.

Step 2 — Find your server details #

Once the dashboard turns green you'll see a card with everything you need:

  • Subdomain URL — https://<subdomain>.hagency.cloud
  • Hagency Server / Matrix homeserver — same URL; this is what you paste into any Matrix client
  • Matrix user ID template — @<local>:<subdomain>.hagency.cloud
  • Session token — a Hagency dashboard session; stored automatically in your browser.

Use the Matrix account registered in the server account center. Platform login and server login are separate accounts.

Step 3 — Install a Matrix client #

Pick one from the Matrix clients sub-page. For this walkthrough we'll use Element because it's the most complete and has every feature:

  • Desktop: https://element.io/download
  • Mobile: Element X (App Store / Play Store)
  • Web (no install): https://app.element.io

Step 4 — Sign in #

  1. Launch the client. You'll land on a welcome screen.
  2. Click Sign in.
  3. When you see the homeserver field, click Edit (Element) or Other (FluffyChat / Cinny). Do not accept the default matrix.org — that would log you into the public server, not yours.
  4. Paste https://<subdomain>.hagency.cloud into the homeserver field.
  5. Click Continue. The client will verify it can reach your homeserver and show the login form.
  6. Enter your Matrix handle (the localpart, e.g. alice — not the full @alice:server form) and the password registered in the server account center.
  7. Click Sign in.

You're now connected to your Hagency Server through a Matrix client.

Step 5 — First-run setup in the client #

Element (and most clients) will walk you through three quick setup steps the first time:

  1. Set a display name. This is the human-friendly name other people see — e.g., "Alice Chen". You can change it any time.
  2. Upload an avatar. Optional, but makes you look a lot less anonymous in group chats.
  3. Set up Secure Backup. Matrix stores your encryption keys on your device. If you lose the device and never set up backup, you lose access to any encrypted history. Element will offer to generate a recovery key (a long string) and/or a recovery phrase — save at least one of these somewhere safe, like a password manager.

Step 6 — Create your first room #

  1. Click the + next to the "Rooms" section in the left sidebar → New room.
  2. Name it (e.g., general).
  3. Pick Private (encrypted, default) or Public (unencrypted, searchable).
  4. Click Create room.

The new room opens. Type a message in the composer at the bottom and hit Enter. Congratulations — you just sent your first encrypted message through your own Hagency Server.

Step 7 — Invite someone #

Inside the room, click the room header → People → Invite.

  • To invite someone on your server: type @their-localpart:your-name.hagency.cloud.
  • To invite someone on another Matrix server (if federation is enabled on your plan): type their full MXID, e.g. @friend:matrix.org.
  • To invite someone who doesn't have a Matrix account yet: use the Hagency dashboard's invite feature to generate a signup link, then send it to them.

Once they accept, they'll see the room in their own client.

Step 8 — Turn on device verification #

If you sign in from a second device (laptop + phone, say), Matrix will warn about unverified sessions. Verifying stops an attacker who got into your homeserver from silently adding their own device to read your messages.

  1. On the already-signed-in device, go to Settings → Security & Privacy → Sessions.
  2. Find the new session and click Verify.
  3. Compare the emoji sequence (or scan the QR code) between the two devices.

Once verified, all your encrypted room history decrypts on the new device. See Security → Device verification for the full details.

Troubleshooting #

  • The dashboard stays on "pending" for more than a minute. Click Retry or check the notification bell in the top-right. Container creation sometimes lags when a cluster region is busy.
  • Element says "Unable to connect to homeserver". Double-check you entered https:// and that you're past the <subdomain>.hagency.cloud subdomain (not just hagency.cloud). Open https://<subdomain>.hagency.cloud/_matrix/client/versions in a browser — you should see a small JSON blob. If you don't, your workspace may not be running; check the dashboard.
  • "Invalid credentials" even though the password looks right. Remember: your Hagency dashboard password (for hagency.cloud) is a different credential from your Matrix password (for the Element sign-in). Reset the Matrix one under Server → Matrix users.
  • I lost my recovery key and can't read old encrypted messages. Unfortunately this is a protocol-level limitation — Matrix keys are end-to-end, so even your homeserver operator (Hagency) can't recover them. Going forward, your new device will see new messages normally.

What's next #

  • The Matrix Protocol — deeper explanation of rooms, spaces, federation, E2EE and clients
  • Server Management — start/stop, custom domains, monitoring
  • Bridges — connect Telegram, Slack, Discord and more
  • Security — 2FA, API keys, sessions, audit log, data export
  • Billing — plans, payments, invoices, coupons, refunds