# Configuring your license

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

Source: https://orbitalhq.com/docs/deploying/configuring-your-license

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](https://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](https://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:

```yaml
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.

**Note**
License configuration must currently be passed as command-line arguments (`--vyne.license.path=...`) or environment variables (`VYNE_LICENSE_PATH=...`). Overriding these settings in `application.yml` is not currently supported.

  See [Passing Orbital application configuration](/docs/deploying/configuring-orbital#passing-orbital-application-configuration) for the conventions.

## 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:

```bash
GET /api/license/status              # Returns the current license and usage
GET /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](hello@orbitalhq.com)