Skip to content

Instance Access Modes

Glassy has two orthogonal axes that decide what your instance looks like and how people get in:

  • INSTANCE_ID — who is this instance for? (public, clear, or self_hosted)
  • INSTANCE_ACCESS_MODE_DEFAULT — who can see it without logging in? (public or private)

Most operators set both at deploy time and never touch them again.

The INSTANCE_ID axis

INSTANCE_ID is set at deploy time and cannot be changed at runtime. It is the canonical signal for "what kind of Glassy is this?" across the entire app.

INSTANCE_ID Audience Commerce Registration
public (default) Open SaaS users Pro plans, AI top-ups, GlassyCalc sidecar Open (or admin-controlled)
clear The Clear membership community Clear plans + GlassyCalc sidecar only Admin-issued invitations
self_hosted One person, their own machine Disabled — all features unlocked for the owner Permanently disabled

What each identity controls

  • public — the standard Glassy experience at app.glassy.fyi. Pro upsells appear; Clear plans are hidden; registration is admin-controlled via ALLOW_REGISTRATION.
  • clear — Clear-tier gating kicks in via isClearInstance(). Pro upsells, the Public Window upsell, Pro-only checkout flows, FAQ pricing rows, and the landing-page Pro teaser all hide or redirect. Clear plans and the GlassyCalc sidecar remain purchasable. The pro_* plans are server-rejected at the checkout endpoint with 400 Pro plans are not available on this instance even if a stale client tries.
  • self_hosted — server-side service gating removes /api/commerce/*, /api/stripe/*, /api/push/*, Sentry initialisation, transactional email, and AI-credit deduction. BYOK-only AI on the appliance: GEMINI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY are not loaded from env; BYOK via Settings → API Keys and local Ollama work; the no-provider path returns 402 { code: 'NO_AI_PROVIDER' }. Registration is permanently locked. Owner is auto-unlocked with clear_lifetime on first boot.

The access-mode axis

INSTANCE_ACCESS_MODE_DEFAULT controls whether anonymous visitors can see anything without logging in.

Mode Effect Default for
public Anonymous visitors see marketing surfaces (landing pages, public windows, shared notes) Cloud instances (public, clear)
private Every route requires authentication; anonymous visitors are redirected to login with deep-link stashing Self-hosted single-user appliance

The mode is enforced on the marketing routes first — anonymous visitors to /#/about, /#/security, /#/guide, /#/neurodiversity, /#/obsidian, /#/writers, /#/students, /#/extension, /#/download on a private instance are routed to login before any flash, not after.

Combining INSTANCE_ID and access mode

Any combination works. The matrix below shows the realistic deployments:

INSTANCE_ID Access Registration Use case
public public Open Standard SaaS
public public Closed Invitation-only SaaS pilot
public private Open Members-only site with a public registration form
public private Closed Fully closed SaaS — admin invites only
clear public Open Public Clear community with self-serve signup
clear public Closed Public Clear instance with admin-issued invitations
clear private Open Members-only Clear community
clear private Closed Fully closed Clear membership site
self_hosted public Disabled Single-user appliance (rare; private mode is recommended)
self_hosted private Disabled Recommended self-host setup

For a self-hosted single-user appliance, the recommended combination is INSTANCE_ID=self_hosted + INSTANCE_ACCESS_MODE_DEFAULT=private. This gives you the locked-down appliance experience with deep-link stashing.

Configuration

At deploy time

Variable Default Where it lives
INSTANCE_ID public docker-compose.yml environment, baked in by compose overlay
INSTANCE_ACCESS_MODE_DEFAULT public .env file, read at server start

INSTANCE_ID is intentionally not .env-overridable on the self_hosted appliance — it's the privacy safeguard that disables commerce and registration. The other two are runtime-mutable via the admin panel.

At runtime

For public and clear instances, the admin can toggle INSTANCE_ACCESS_MODE_DEFAULT from Admin → Instance Access without redeploying. The change applies within 60 seconds (after the in-process cache TTL expires).

INSTANCE_ID cannot be toggled at runtime — change requires a redeploy with the new env var.

User management

From the admin panel (admin accounts only):

  • View all registered users
  • Toggle registration open/closed via ALLOW_REGISTRATION
  • Manage user tiers and quotas
  • Revoke sessions
  • See the instance identity and access mode at the top of the panel — read-only

On self_hosted, the admin panel is reachable at /#/admin and the only user is the seeded owner.

Migration between modes

There is no automatic migration between INSTANCE_ID values. Switching identity is a deploy-time decision:

  • public → clear — redeploy with the Clear compose overlay. Existing user accounts keep their Pro tiers; commerce endpoints swap to Clear-only plans.
  • public → self_hosted — redeploy the self-host appliance. Export your data first; the new instance has a fresh database and you'll need to import.
  • clear → public — redeploy without the Clear env var. Existing Clear members lose Clear-tier gating unless they switch to a Pro plan.

For mode-only changes (public ↔ private), no data migration is needed — toggle from the admin panel.

Learn more