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
• No account required
• Never expires

Registered Tier

• Up to 500 files indexed
• All core features included
• Requires free account (sign up at stellarion.dev)
• Never expires

Professional Tier

• Up to 2,000 files indexed
• All features + priority support
• Subscription-based
• Valid while subscription is active

Unlimited Tier

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

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
Stellarion v2.0.0

No valid license found.
Your System ID: ABCD-1234

To activate:
1. Visit https://stellarion.dev/activate
2. Sign in with your account
3. Enter your System ID: ABCD-1234
4. Copy the license key to ~/.stellarion/license.key

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 Activation Page

Go to stellarion.dev/activate in your browser.

2.2 Sign In

Sign in with your Google or GitHub account. A free account automatically grants you the Registered tier (500 files).

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 / 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 --version
Stellarion v2.0.0
License: Registered (500 files)
Status: Active

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 activation 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