Licensing

This guide explains how to activate Stellarion, manage your license, and understand the different tiers available.

License Tiers

Stellarion offers four license tiers to match your needs:

Free Tier

• Up to 100 files indexed
• All core features included
• Never expires

Professional Tier

• Up to 500 files indexed
• All core features included
• Free for 60 days. Subscription required after 60 days

Enterprise Tier

• Unlimited files indexed
• All features + dedicated support
• Enterprise subscription
• Custom SLA available

License Enabling

Step 1: Get Your System ID

Each machine has a unique System ID used to bind your license. When you first run Stellarion without a license, it displays your System ID:

$ stellarion license --system-id

╭──────────────────────────────────────────────────────────╮
│           STELLARION SYSTEM ID                           │
╰──────────────────────────────────────────────────────────╯

  System ID: XXXX-XXXX

  Diagnostics:
  ├── Hardware-based: Yes
  ├── MAC Available: Yes
  ├── Platform: darwin
  └── Hostname: xxx-macmachine.in

  Use this ID at: https://stellarion.ai/licenses

Note: Your System ID is unique to your machine. If you reinstall your OS or significantly change your hardware, you may get a new System ID.

Step 2: Activate Your License

2.1 Visit the License Page

Go to stellarion.ai/licenses in your browser.

2.2 Sign In

Sign in with your Google or GitHub account.

2.3 Enter Your System ID

Enter the System ID displayed by Stellarion. The format is XXXX-XXXX (e.g., ABCD-1234).

2.4 Copy Your License Key

After entering your System ID, you'll receive a license key. Copy it and save it to the license file:

macOS:

stellarion license --activate 

╭──────────────────────────────────────────────────────────╮
│        STELLARION LICENSE ACTIVATION                     │
╰──────────────────────────────────────────────────────────╯

  Your System ID: XXXX-XXXX

  Waiting for license key...
  (Press Ctrl+C to cancel)

  Enter license key:

Linux:

# Create the directory if it doesn't exist
mkdir -p ~/.stellarion

# Save the license key
echo "ST-REG-eyJ2ZXJz..." > ~/.stellarion/license.key

Windows (Command Prompt):

mkdir %USERPROFILE%\.stellarion
echo ST-REG-eyJ2ZXJz... > %USERPROFILE%\.stellarion\license.key

Windows (PowerShell):

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.stellarion"
"ST-REG-eyJ2ZXJz..." | Out-File -FilePath "$env:USERPROFILE\.stellarion\license.key" -Encoding UTF8

2.5 Verify Activation

Run Stellarion again to verify your license is active:

➜  ~ stellarion license --info    
╭──────────────────────────────────────────────────────────╮
│         STELLARION LICENSE INFORMATION                   │
╰──────────────────────────────────────────────────────────╯

  System ID: BG8W-93EB

  ✅ Status: ACTIVE
     Tier: Professional
     Max Files Indexed: 500
     License key active. Limited to 500 files indexing.

  License Details:
  ├── Key: ST-PRO-****-XXXX
  ├── Issued: 12/11/2025
  ├── Email: xxxx@gmail.com
  └── Verification: local
       Last Verified: 12/11/2025, 4:23:41 PM

  ┌────────────────────────────────────────────────────────┐
  │ UPGRADE OPTIONS                                        │
  ├────────────────────────────────────────────────────────┤
  │  Unlimited        Unlimited files                      │
  ├────────────────────────────────────────────────────────┤
  │  https://stellarion.ai/licenses                        │
  └────────────────────────────────────────────────────────┘

License Key Format

Stellarion uses v2 license keys with the following format:

ST-{TIER}-{PAYLOAD}-{CHECKSUM}

Examples:

ST-FREE-eyJ2ZXJzaW9uIjoyLC....-A1B2
ST-REG-eyJ2ZXJzaW9uIjoyLCJ....-C3D4
ST-PRO-eyJ2ZXJzaW9uIjoyLCJ....-E5F6
ST-UNL-eyJ2ZXJzaW9uIjoyLCJ....-G7H8

Components:

Security Features:

• Machine-bound: License is tied to your System ID
• Cryptographic checksum: Validates license integrity
• Tamper-resistant: Encoded payload prevents modification
• Offline validation: Works without internet connection

License File Location

The .stellarion directory is created automatically when you first run Stellarion.

Upgrading Your License

To upgrade from one tier to another:

1. Upgrade your subscription on the dashboard
2. Visit the license page at stellarion.dev/activate
3. Enter the same System ID - a new license key will be generated with your upgraded tier
4. Replace your license file with the new key

The system automatically detects your new tier and generates the appropriate license key.

Using on Multiple Machines

Each machine requires its own license activation:

To activate on a new machine:

1. Get the System ID from the new machine
2. Visit stellarion.dev/activate
3. Enter the new machine's System ID
4. Each machine will receive its own unique license key

Troubleshooting

"Invalid license key"

Possible causes:

• License key was copied incorrectly (check for extra spaces or missing characters)
• License was generated for a different System ID
• License key is in old v1 format (starts with CM- instead of ST-)

Solution: Regenerate your license at stellarion.dev/activate

"System ID mismatch"

Cause: The license was generated for a different machine.

Solution: Generate a new license with your current System ID at stellarion.dev/activate

"License expired"

Cause: For Professional and Unlimited tiers, licenses are tied to your subscription.

Solution: Renew your subscription on the dashboard, then regenerate your license.

"File limit exceeded"

Cause: Your project has more files than your tier allows.

Solutions:

1. Upgrade to a higher tier
2. Use .stellarionignore to exclude directories (similar to .gitignore)
3. Limit indexing with the maxFiles parameter:

   mcp__stellarion__index_project({
     path: ".",
     maxFiles: 500
   })
   

"No valid license found"

Cause: License file is missing or in the wrong location.

Solution:

1. Check that the license file exists at the correct path
2. Verify the file contains only the license key (no extra whitespace or newlines)
3. Re-download your license from stellarion.dev/activate

Environment Variables

You can also set your license via environment variable:

export STELLARION_LICENSE_KEY="ST-REG-eyJ2ZXJz..."

This takes precedence over the license file and is useful for:

• CI/CD environments
• Docker containers
• Temporary testing

License Validation

Stellarion validates your license:

1. At startup: Checks license file or environment variable
2. During indexing: Verifies file count against tier limit
3. Offline: All validation happens locally, no internet required

Validation Checks:

• ✅ License format is valid (ST-TIER-PAYLOAD-CHECKSUM)
• ✅ Checksum matches payload
• ✅ System ID matches current machine
• ✅ License tier is recognized
• ✅ License hasn't expired (for PRO/UNL tiers)

Need Help?

If you're having issues with licensing or activation:

• Email: support@stellarion.dev
• Dashboard: stellarion.dev/dashboard - View your account and subscription status
• Book a call: stellarion.dev - Schedule time with our team

Quick Reference

Activate a New Machine

# 1. Run stellarion to get System ID
stellarion

# 2. Visit stellarion.dev/activate and enter System ID

# 3. Save license key
echo "ST-REG-..." > ~/.stellarion/license.key

# 4. Verify
stellarion --version

Check Current License

stellarion --version
# Output: License: Registered (500 files), Status: Active

Upgrade License

# After upgrading subscription, regenerate license at stellarion.dev/activate
# Then replace the license file
echo "ST-PRO-..." > ~/.stellarion/license.key