Configuration and Multi-Device Access

The default .env gets you running in minutes. This lesson covers the optional configuration — ports, CORS, multi-device access, version pinning, and Cloud Sync.

Environment variables reference

Already set in compose (no action needed)

Variable	Default	Purpose
INSTANCE_ID	self_hosted	Single-user gating — do not change
DEPLOYMENT_LOCALITY	local	Hides the cloud-limitation banner in Obsidian settings
OBSIDIAN_HOST_OVERRIDE	host.docker.internal	Rewrites 127.0.0.1 to the Docker host gateway
OBSIDIAN_NETWORK_ALLOWLIST	—	Additional comma-separated hostnames/IPs for Obsidian connections
ENABLE_MCP_SERVER	true	MCP server and Second Brain
ENABLE_AGENT_GATEWAY	true	Agent Gateway (OpenClaw / Hermes)

Optional (set in .env if needed)

Variable	Default	Purpose
GLASSY_TAG	— (required)	Image tag from GHCR. Must name a released version (e.g. v2.58.0); never latest (the hosted build).
APP_PORT	3000	Host port. Change if 3000 is in use.
APP_URL	http://localhost:3000	Base URL. Set this for Tailscale/domain access.
CORS_ORIGINS	http://localhost:3000	Must include every origin you use.
OLLAMA_BASE_URL	http://host.docker.internal:11434	Ollama on the host
OLLAMA_MODEL	llama3.2	Default Ollama model
BACKUP_ENCRYPTION_KEY	—	Encrypt on-demand backups (AES-256-GCM)
CLUSTER_WORKERS	min(2, CPUs−1)	Worker processes. Set to 1 on a small box.

Changing the port

If port 3000 is in use:

APP_PORT=3001
APP_URL=http://localhost:3001
CORS_ORIGINS=http://localhost:3001

Then docker compose up -d. The container always listens on 8080 internally; APP_PORT only changes the host-side mapping.

Multi-device access

To use Glassy from another device (phone, laptop, tablet), set APP_URL and CORS_ORIGINS to your network URL and choose an access method:

Option 1: Tailscale (recommended)

Tailscale is a WireGuard mesh VPN — no port forwarding, no public exposure.

APP_URL=http://<machine>.tail-net.ts.net:3000
CORS_ORIGINS=http://<machine>.tail-net.ts.net:3000

Install Tailscale on both your server and your phone/laptop. They’ll see each other as if on the same LAN.

Option 2: Cloudflare Tunnel

A Cloudflare Tunnel gives you a public HTTPS URL through Cloudflare’s edge — no open ports on your server.

APP_URL=https://glassy.example.com

Set up the tunnel with cloudflared and point your domain at it.

Option 3: Caddy HTTPS overlay

If you own a domain, the bundled Caddy overlay gives you auto-renewing Let’s Encrypt TLS:

docker compose -f docker-compose.yml -f docker-compose.https.yml up -d

Version pinning

For reproducibility, pin a released version:

GLASSY_TAG=v2.58.0

Then docker compose up -d. To upgrade later, change GLASSY_TAG to the newest released version (see the releases page) and re-run docker compose pull && docker compose up -d. Never set GLASSY_TAG=latest — the floating :latest tag is the hosted build and omits self-host features.

Obsidian network allowlist

If Obsidian runs on a different machine than Glassy (not localhost), add its address to the allowlist:

OBSIDIAN_NETWORK_ALLOWLIST=192.168.1.10,glassy.tail-net.ts.net

You’ll also need to configure the Obsidian Local REST API plugin to bind to 0.0.0.0 instead of 127.0.0.1.

Cloud Sync (cross-instance data sync)

Cloud Sync keeps your notes, documents, bookmarks, voice recordings, conversations, and pinned tags synchronized between your self-hosted appliance and your Glassy cloud account. It runs over a server-to-server delta channel authenticated by a per-peer sync token — separate from your self-host pairing token.

Enabling Cloud Sync

1. Generate a sync token on the receiving side. Open the receiving instance — your cloud account, or a private VPS in a Pair — then go to Settings → Cloud Sync and click Generate. Copy the raw token; it is shown once.
2. Save it on the sending appliance. Open the appliance’s Settings → Cloud Sync, paste the token into Pair token, enter the receiver URL in Syncs to, and choose Save Cloud Sync settings. Both values resolve per cycle, with no restart.
3. Scripted/bootstrap fallback only: set GLASSY_SYNC_TOKEN=<token> in .env and restart. A token saved in Settings wins from its next cycle.
4. Verify in the self-hosted web app at Settings → Cloud Sync — you should see the peer connection, credentialSource, per-type cursor status, and a Sync now button.

Scheduler tuning

Variable	Default	Purpose
GLASSY_SYNC_INTERVAL_MS	300000 (5 min)	Full cycle interval — pulls peer changes + pushes local. Set to 0 to disable automation (manual Sync now still works).
GLASSY_SYNC_CHECK_MS	10000 (10 s)	Fast-check interval — detects near-instant pushes from the peer.

Per-type, direction, and conflict controls

In Settings → Cloud Sync you can enable/disable sync per content type, set direction (two-way, push-only, pull-only), and choose a conflict policy (most-recent = last-writer-wins, or cloud-wins).

Multi-appliance

Each appliance connects to the cloud independently with its own token. Multiple appliances can sync to the same cloud account — each peer is tracked separately in the sync health dashboard.

What’s next?

Learn about backups and data management — automated daily backups, encryption, and restore.