Quickstart: Managed mezhub

This guide walks a brand-new user from cloud.mezite.com through to a running managed hub, an admin login, and a node-join token in your clipboard — ready to install mezd on your first node. It should take about five minutes once the hub finishes provisioning.

By the end you will have a managed mezhub running in your chosen region, an admin session token on your local machine, and a static node-join token valid for two hours.

Prefer to run Mezite yourself? See the self-hosted quickstart instead — it walks through a single-node deployment with SQLite or PostgreSQL.

Prerequisites

  • A web browser and an email address you can receive mail on
  • mezctl installed locally (see Installation)
  • A few minutes for the hub to provision after you create it

Step 1: Sign Up on cloud.mezite.com

Open https://cloud.mezite.com and create an account. You will need an email address and a password. Signup auto-creates a default workspace for you — there is no separate "create workspace" step.

Pick a password manager-friendly password. The cloud account password is separate from the initial admin password the hub will issue in Step 3, and from the static node tokens you will generate later.

Step 2: Set Your Workspace Slug

Right after signup, the onboarding screen prompts you for a workspace slug. The slug becomes part of every managed hub's hostname (for example, slug acme gives you a hub at acme.hub.mezite.com), so pick something short and memorable.

The slug is locked the moment you submit your first hub-create form in Step 3 — it cannot be changed once any instance row exists, even while that hub is still provisioning. Choose carefully.

Step 3: Create a Managed Hub

Open the MezHubs tab in the sidebar and click create. You will be prompted for:

  • Region — pick the region nearest you; eu-west-1 is a safe default in Europe.
  • Plan — the entry plan is shared-cpu-1x-512mb, which is enough to evaluate Mezite and run a handful of nodes. Larger plans are selectable in the UI for production workloads.

Submit the form and wait for the hub status to change to Running. Provisioning typically takes a couple of minutes — the UI will poll and update the status for you.

When the hub flips to Running, the UI will show your hub's hostname (for example acme.hub.mezite.com) and the initial admin password. Copy the password now — it is displayed once and not retrievable later. If you lose it, you can reset it from the workspace settings, but it is far less painful to copy it the first time.

Step 4: Install mezctl Locally

mezctl is the admin CLI you use to manage your hub. Follow the Installation guide to grab the latest release for your platform, then confirm it is on your PATH:

Verify mezctl install bash 
mezctl version

Step 5: Log In with mezctl

Use the hostname from Step 3 as your auth server, the username admin, and the initial admin password from Step 3. mezctl login prints a session token to stdout — capture it in an environment variable so the next commands can reuse it.

Log in to the managed hub bash 
export MEZITE_AUTH_SERVER=<your-hub-host>:443
export MEZITE_ADMIN_PASSWORD='<initial-admin-password>'

export MEZITE_TOKEN=$(mezctl \
  --auth-server="$MEZITE_AUTH_SERVER" \
  login \
  --username=admin \
  --password="$MEZITE_ADMIN_PASSWORD")

echo "Logged in. Session token captured."

Step 6: Confirm the Hub Responds

Run a read-only command against the hub to confirm your session token works. Listing users is the quickest smoke test — your admin user should appear:

List users bash 
mezctl \
  --auth-server="$MEZITE_AUTH_SERVER" \
  --token="$MEZITE_TOKEN" \
  users list

# Output (your admin user should appear):
# USERNAME  ROLES  STATUS
# admin     admin  active

Step 7: Create a Node-Join Token

A static join token lets mezd register a node with your hub. Create one with a short TTL — two hours is plenty to install mezd on your first machine.

Create a node-join token bash 
mezctl \
  --auth-server="$MEZITE_AUTH_SERVER" \
  --token="$MEZITE_TOKEN" \
  tokens create \
  --type=static \
  --ttl=2h \
  --roles=node

# Output (one line):
# Token created: d4f8a2e17b3c4d9ea5f61234567890ab (roles: node, expires: 2026-05-17T12:00:00Z)

Copy the token value after Token created: — that is the string you will paste into mezd in the next quickstart.

What Just Happened?

  1. cloud.mezite.com created an account, a default workspace, and locked your workspace slug to your first hub's subdomain.
  2. The managed control plane provisioned a fresh mezhub in your chosen region, generated User and Host CA keypairs, ran database migrations, and minted an initial admin password.
  3. mezctl login authenticated against the hub's gRPC auth service over HTTPS and received a session token bound to your admin identity.
  4. mezctl tokens create wrote a static, role-scoped provisioning token to the hub's database — anyone who presents that token within the TTL window can join a node to your cluster.

Next Steps

Keep the node-join token handy and head to the next quickstart to install mezd and bring your first node online.

  • Quickstart: mezd — install the node agent and join your new hub using the token you just generated.
  • mezctl Reference — full command surface for admin tasks: users, roles, tokens, certificate authorities, and more.
  • RBAC Guide — replace the default admin role with fine-grained, label-scoped access for your team.
  • SSO Guide — wire up OIDC, SAML, LDAP, or GitHub OAuth so users sign in with your identity provider instead of the local admin account.