Instance administration & licensing

What instance administration is

Most of Elliptic is scoped to a single organization. Owners and admins manage their own workspace and never touch anyone else's. Instance administration sits one level above that. It is the control plane for the whole deployment, the Elliptic instance itself, across every organization it hosts. This is where you set the instance name, decide who can create workspaces, turn the deployment fully offline, manage user accounts no matter which orgs they belong to, and activate a license.

This page is for whoever runs the instance. On the hosted instance at elliptic.sh that is the Elliptic team. On a self-hosted deployment it is you. Either way the surfaces and rules are identical, and they all live behind a single role.

The instance admin role

An instance admin is a cross-org administrator. Unlike an org owner or admin, whose authority stops at the boundary of their organization, an instance admin acts on the deployment as a whole. The flag lives on your user account (is_instance_admin), not on any org membership, so it follows you regardless of which workspaces you are a member of, and you do not need to belong to an org to exercise it.

Every instance endpoint is gated by require_instance_admin. If your account does not carry the instance-admin flag, the request is rejected with an Instance-administrator-access-required error, and the admin page in the web app quietly redirects you back into the app. There is no partial access. You either hold the role or you do not.

You reach the instance admin surface in the web app at the /admin route. It opens onto three tabs, General, Users, and License, which map to the three areas covered below.

Self-protection guards

Because instance admins are powerful, two actions are blocked even for them, to stop you from locking yourself out or stranding the instance:

• You cannot suspend your own account. Attempting to suspend yourself returns a You-cannot-suspend-your-own-account error. You can suspend any other user.
• You cannot revoke your own instance-admin access. Attempting to revoke your own admin rights returns a You-cannot-revoke-your-own-instance-admin-access error. Another instance admin can revoke yours, but you cannot remove the last hold you have on the instance by accident.

Both guards are checked by identity, the actor compared against the target user. They do not stop you from acting on anyone else, so you can still suspend or demote a second admin if you have to.

Instance settings

Instance settings are a single shared record for the whole deployment, edited from the General tab. The first time an instance admin opens settings the record is created with sensible defaults, so there is nothing to seed by hand. Five fields are configurable:

Changes save as you make them. Toggles apply on switch, and text fields like the instance name and the email from-address commit when you move focus away. A blank instance name is ignored so you cannot accidentally clear it, and clearing the email field stores an empty value so the from-address is simply unset.

Workspace creation, enforced where it matters

Turning off allow-workspace-creation is a real gate, not a cosmetic one. When a user tries to create an organization, Elliptic checks the instance setting first. If creation is disabled and the user is not an instance admin, the request is refused with a Workspace-creation-is-disabled-on-this-instance error before any org is written. Instance admins are always exempt, so you can still spin up workspaces even when everyone else is locked out. This is the right control for a single-tenant deployment, or for an instance where you want to provision every org centrally.

Managing users across orgs

The Users tab lists every account on the instance, not just members of one org. For each user you see their name and email, the number of workspaces they belong to (org_count), whether they are an instance admin, and whether they are currently suspended. Accounts are ordered by when they were created, so the earliest users sit at the top. The list returns up to two hundred users.

From this one place you can suspend and reinstate accounts and grant or revoke instance-admin rights. These are the four user actions available to an instance admin.

Suspending and reinstating accounts

Suspending a user is the instance-wide off switch. It does not delete anything. It stamps the account with a suspension timestamp, and from that moment authentication rejects it everywhere. A suspended user trying to sign in, whether with a normal session token or a personal access token, is turned away with a This-account-has-been-suspended error. The block is enforced at the authentication layer, so it applies to every org and every surface at once, including the API and the company-brain MCP, with no per-org cleanup needed.

Reinstating is the exact reverse. It clears the suspension timestamp and the account can sign in again immediately, with all of its org memberships and data intact, exactly as before.

1. 1
   Open the Users tab

   Go to the /admin route and select Users. Each row shows the account with badges for instance admin and suspended state.
2. 2
   Suspend the account

   Select Suspend on the user's row. The account is marked suspended right away and is rejected the next time it tries to authenticate. You cannot suspend your own account.
3. 3
   Reinstate when ready

   To restore access, select Reinstate on the same row. The suspension is cleared and the user can sign in again with everything intact.

Granting and revoking instance-admin rights

Make admin sets the instance-admin flag on a user, giving them the full cross-org control plane described on this page. Revoke admin clears it. The change takes effect on the account immediately, and from then on that user passes or fails the require_instance_admin gate accordingly.

Keep the circle small. Instance admins can see and act on every account and every workspace, configure the deployment, and manage licensing. Grant the role only to people who actually run the instance. Remember the self-protection guard: you can promote anyone and demote anyone else, but you can never revoke your own admin access, so an instance always keeps at least the admin who is acting.

Air-gapped mode

Air-gapped mode turns the instance into a zero-egress deployment. When it is on, Elliptic makes no outbound network calls of its own, which is what you want for a fully offline or network-isolated install where data is never allowed to leave the perimeter. You enable it with a single toggle in the General tab, and the setting is read live by every feature that would otherwise reach out.

Concretely, air-gapped mode disables the following:

• Web search. The AI web-search feature, which normally fetches results and has your org's model synthesize a grounded answer, is refused with a Web-search-is-disabled-in-air-gapped-mode error before any outbound request is made.
• Outbound link unfurls. When you paste a URL, Elliptic would normally fetch the page to pull a title, description, and preview image. In air-gapped mode it skips that fetch entirely and returns only the metadata it can derive from the URL itself, so no request leaves the instance. Embeds that render as an iframe are unaffected because they never required a server-side fetch.
• Telemetry. With zero egress there is no anonymous-usage reporting. Keeping telemetry off is the consistent posture for an air-gapped install.

Air-gapped mode does not break AI. Your organization still runs every AI feature on its own model key, the BYOK rule that holds everywhere in Elliptic. To stay fully offline you point that key at a local model through a custom base URL, so summaries, answers, agents, and runs all execute inside your network. Web search is the one AI capability that genuinely needs the open internet, which is why it is the feature that gets switched off.

Offline licensing

Elliptic licenses are offline by design. There is no phone-home, no license server to reach, and no callback at activation. A license is a signed key that an instance admin pastes in once, and the instance verifies it locally. That is what makes licensing work inside an air-gapped deployment that can never reach a vendor endpoint.

A license records four things: the plan, the number of seats, the licensee (who the license is issued to), and an optional expiry. The instance keeps one active license at a time, and you manage it from the License tab.

How a license key works

A license key is a signed token. The plan, seats, licensee, and expiry are encoded into it and the whole thing is signed, so the key carries its own claims and cannot be altered without breaking the signature. Activation verifies that signature offline against the instance secret. If the key has been tampered with in any way, or is otherwise invalid, verification fails and activation is refused with an Invalid-or-tampered-license-key error. Nothing is recorded. A valid, untampered key activates with no network access whatsoever.

Activating a license

On the License tab the instance shows a status badge, either the active plan and seat count, or Unlicensed. To activate, paste your offline license key into the field and select Activate.

1. 1
   Open the License tab

   Go to the /admin route and select License. If no license is active yet the badge reads Unlicensed.
2. 2
   Paste the key

   Paste the signed offline license key into the Activate a license key field. Keys are long signed tokens, so paste the whole thing exactly as issued.
3. 3
   Activate

   Select Activate. The instance verifies the signature offline. On success it records the plan, seats, licensee, and expiry, marks the new license active, and deactivates any license that was active before. A tampered or invalid key is rejected and nothing changes.

Activating a new key always supersedes the old one. The instance flips any previously active license to inactive before recording the new one, so there is exactly one active license at any moment and re-licensing is just a fresh activation.

Viewing and delinking the active license

The License tab shows the current license whenever one is active: the licensee, the plan, the seat count, and the expiry date if the key carries one. If nothing is active it shows Unlicensed instead.

Delinking deactivates the current license. Select Delink license and the active license is flipped to inactive and the instance returns to the Unlicensed state. Delinking does not destroy the key. You can re-activate the same key later, or activate a different one. It is the clean way to move a license between instances or to wind one down.

Issuing signed keys

Instance admins can also mint new license keys. Issuing takes a plan, a seat count, an optional licensee, and an optional number of days until expiry, and returns a freshly signed token. If you pass a day count the key carries a matching expiry, and at activation that expiry is read back from the token and stored on the license. If you omit the day count the key does not expire.

Because keys are verified offline against the instance secret, a key issued by one instance activates on any instance that shares that secret, which is exactly how you provision an air-gapped install: mint the key where it is convenient, then carry it to the isolated deployment and activate it there with no connectivity between the two.

Putting it together

Instance administration is the small set of levers that govern the deployment as a whole. Grant the instance-admin role to the people who run the instance, and trust the self-protection guards to keep at least one of them in control. Use instance settings to name the deployment, to decide who may create workspaces, and to set the email from-address. Suspend and reinstate accounts to control sign-in everywhere at once, knowing the block is enforced at authentication. And for fully offline operation, pair air-gapped mode with a local model behind a custom base URL and an offline license key, so a Elliptic instance can run end to end without ever leaving your network.