License and usage

Meshly Build is licensed software — every running instance needs a valid license key tied to your account on the MDS Customer Portal (portal.meshlystack.com). The license unlocks the platform; usage data flowing back to the portal drives your billing.

This page explains the license activation flow, what data is reported, and how to keep an eye on it.

When the license is activated

Licenses are NOT activated at install. They're activated when the first admin user is set up — the same screen that asks for the admin username, password, and email also has a License key field. Pasting the key here:

1. Creates the admin user (always succeeds)
2. Sends the key to the portal for validation (only fails the license step, not the user creation)
3. If valid, persists the issued API key + signed token locally
4. If invalid, the instance enters degraded mode — the UI shows a banner telling the admin to fix the license in Settings, but doesn't lock anyone out

For self-hosted installs without a license key (e.g. demo/trial environments), leave the field blank at first-user setup. The instance runs in degraded mode with the banner; everything still works, but the portal sees no usage and your billing math eventually catches up.

Activating later

If you skipped the license at first-user setup, or you need to change keys (revoked, plan upgrade, etc.):

Settings → System → License

You'll see:

• Status — Active / Degraded / Not configured
• Product — always "Meshly Build"
• License key — masked (first 8 + last 4 visible)
• Domain — the domain this license is registered against, e.g. acme.meshly.build
• Active users this month — live count that drives billing (see below)
• License expires — when the cached signed token expires
• Validated — when the license was last successfully validated against the portal
• Last heartbeat — when the last automatic heartbeat ran (every 5 min)

Below that is a Change license key form. Paste a new key, click Validate. The portal re-checks; on success the new key replaces the old one and the panel updates.

If the portal rejects the new key (invalid, expired, plan mismatch), the inline error shows the portal's reason and the existing license stays active. No way to break a working license by typing a bad new one.

What gets billed

Meshly Build is billed per active user per month (default €100/user/month, with per-license overrides possible).

An active user is defined as a user who, during the calendar month, did at least ONE of the following:

• Created a task
• Completed a task
• Posted a comment / message in a conversation
• Ran an agent (sent an agent message)
• Edited a task (updated fields, labels, etc.)

NOT counted (these explicitly don't make a user "active"):

• Logged in
• Viewed a page
• Opened a notification

The "Active users this month" number on the License Settings page shows your current month's count. It's the same number the portal uses to invoice you.

Heartbeat and telemetry

Your instance reports back to the portal automatically:

• License heartbeat — every 5 minutes. Confirms the license is still alive and refreshes the cached signed token. Includes minimal metadata (version, instance fingerprint).
• Usage telemetry — every 5 minutes. Reports the current calendar month's active-user count, task-completion count, AI token counts, AI cost (rounded cents), and request count. The portal upserts on (customer, domain, period) — same period reported multiple times just updates the value. The portal takes max(activeUsers) across the month for billing, so any later-in-month reports that are higher take precedence.

These are background tasks. You don't need to do anything; they run as long as the instance is up.

Offline grace

If the portal is unreachable for a stretch (network blip, portal maintenance, your install is in a private network with limited egress):

• The cached signed token stays valid for 24 hours from issue. During this window, your instance keeps working as if everything's fine.
• After the token expires, there's a 7-day grace period. Banner appears in the UI; non-essential features still work; the admin should look into why heartbeats are failing.
• After grace runs out, the instance enters degraded mode — same banner as "not configured".

To recover: connect the network (or fix whatever's blocking egress to portal.meshlystack.com), wait for the next heartbeat. The portal returns a fresh signed token and degraded mode clears.

Multi-tenant installs

If your Meshly Build install is multi-tenant (one shared server hosting apex.meshly.build, bcorp.meshly.build, etc.), each tenant has its OWN license. Each tenant's admin sets their own license key at first-user setup. Heartbeats and telemetry are per-tenant — the portal sees each tenant as a separate customer with separate billing.

Most users won't be on a multi-tenant install. If you're a single-organisation Meshly Build customer with a dedicated install, this section is informational only.

Where the data goes

Everything reported flows to https://portal.meshlystack.com/api/.... Specifically:

• POST /api/license/validate — at first-user setup or when you change the key
• POST /api/license/heartbeat — every 5 minutes
• POST /api/telemetry/meshly-build/usage — every 5 minutes

No customer code, task descriptions, or source files are sent. The telemetry payload contains only aggregate counters — {activeUsers, activeAgents, tasksCompleted, aiTokenInput, aiTokenOutput, aiCostUsdCents, requests} plus the domain and period.

If you want to see exactly what was sent, the customers portal admin page shows your reported rollups per month.

Rotating the license key

If your license needs to change (plan upgrade, suspected key leak):

1. Get a new key from your portal account
2. Open Settings → System → License
3. Paste the new key in Change license key, click Validate
4. The portal re-issues a fresh apiKey + signed token; the old apiKey is invalidated portal-side

Your instance keeps working — there's no "downtime" between revoking and re-validating because the validate call atomically replaces the state.

If you got the new key but somehow your install can't reach the portal to validate, contact support — there's a manual path involving the portal admin issuing a fresh apiKey out-of-band, which gets injected into your tenant DB by your install's admin.

Troubleshooting

Status shows "Degraded" but I just set the license.

• Wait 5 minutes for the next heartbeat to refresh. The status updates on heartbeat success.
• Check the Last heartbeat status field — if it shows "transient: …", the portal was briefly unreachable; another tick will fix it.
• If it shows "denied: …", the portal rejected the call — open the license panel and try Change License with the same key (forces a re-validate).

Active users this month seems wrong.

• The count is COUNT(DISTINCT user_id) over the five qualifying actions. If you're seeing a number lower than the team size, it means most of the team hasn't actually DONE one of those actions this month (logging in doesn't count).
• Wait until enough qualifying activity accumulates; the count updates in near-real-time.

Banner says "No license configured" but I see a license key on the Settings page.

• The key is persisted but the apiKey field got wiped (rare bug, fixed in 3.0.26). Open Change License, paste the same key, validate — that re-issues the apiKey and clears the banner.

What's next

• Agents and API keys — what gets counted as agent activity for usage
• Working with tasks — task activity is one of the five "active user" signals