Orbital

Deploying Orbital

Configuring your license

How Orbital loads, fetches and verifies your license, and where to put the license file

Orbital requires a license to run. This page covers how to obtain a license, where Orbital expects to find it, and how to override the defaults.

Getting a license

When you first sign in, Orbital automatically contacts the license server (https://account.orbitalhq.app), downloads a free license, and configures it for you.

In most environments, no manual setup is required.

If your machine cannot access the internet, or you’d prefer to manage your license manually, you can sign in to account.orbitalhq.app and manage your license directly.

From the portal you can:

  • Download a license.json file directly
  • View your active features and usage quotas
  • Manage instances registered against your license

How Orbital loads a license

On startup, Orbital searches for a license.json file in the following locations, in order. The first valid license wins:

  1. The path provided via --vyne.license.path (if set)
  2. ${vyne.app.data.path}/license.json — by default ./orbital_data/license.json
  3. ~/.orbital/license.json
  4. /opt/var/orbital/license/license.json

If you’ve signed in via the Orbital UI and no license is found on disk, Orbital will fetch one from the license server against your organisation and save it to the default write path (option 2 above).

This is the recommended way to get started — just sign in and Orbital takes care of the rest.

You can also download license.json from account.orbitalhq.app and drop it into any of the locations above.

Configuring the license path

In your docker-compose.yml, Set --vyne.license.path to load the license from a custom location:

services:   orbital:      image: orbitalhq/orbital:latest      environment:         OPTIONS: >-            --vyne.license.path=/opt/orbital/secrets/license.json

The downloaded license is also saved to this path, so make sure the directory is writable by Orbital.

Verifying your license

The Orbital UI shows your current license status, including the licensee, plan, expiry, and usage against any metered quotas.

You can also query the license status directly:

GET /api/license/status              # Returns the current license and usageGET /api/license/status?refresh=true # Forces Orbital to re-download from the license server

Both endpoints require authentication, and the user must have the ModifyLicense privilege.

When no valid license is found

If Orbital can’t find a valid license — for example, on a brand-new install before you’ve signed in — it will issue a short-lived fallback license, allowing the server to start. The fallback is written to ${vyne.app.data.path}/temp-license.json.

A fallback license lets you trial the application for 30 minutes. After this time, you’ll need to provide a free license to continue using Orbital. Sign in via the UI, or place a real license.json at one of the search paths above, and restart Orbital to activate.

Expired or invalid licenses are skipped during the search and Orbital will continue to the next location. The reason is logged at warn level.

Air-gapped and offline deployments

By default, Orbital will periodically report operation invocation counts back to the license server. This is used for usage attribution and quota enforcement.

If your deployment is air-gapped or otherwise can’t reach account.orbitalhq.app, Orbital supports running in air-gapped mode, which disables the requirement to report quotas, and removes the need to contact account.orbitalhq.app.

If you’d like to use this features, please reach out to our sales team