Docs

Install and run Glassys

Glassys runs on the machine the agent should operate, as a service of your own user. These are the steps, the knobs and the recipes for reaching it from your phone.

Requirements

Node.js 22.13+ and pnpm 11.14+ (the repository is a pnpm workspace; do not use npm). On Node 25+, install Corepack first with npm install -g corepack.
A git workspace on the machine that will run the agent.
macOS (launchd) or Linux (systemd --user).
Your agent’s SDK sign-in on that host. For Cursor, sign in with the Cursor SDK in the wizard; an API key is optional.

Install

One line, from any directory. It clones the repository if needed, runs pnpm install, builds, and installs a user service: launchd on macOS, systemd --user on Linux. Closing the terminal does not stop Glassys.

bash

$ curl -fsSL https://raw.githubusercontent.com/KN990x/Glassys/main/scripts/install.sh | bash

The same thing, by hand:

bash

$ git clone https://github.com/KN990x/Glassys.git glassys && cd glassys && pnpm install && pnpm run service:install

First run

1Open http://127.0.0.1:8787 on the host (or the port in GLASSYS_PORT).
2Set the operator password. Whoever sets it owns the instance.
3Pick the adapter and the absolute path of the workspace.
4Sign in to the agent’s SDK. On a host without a display (SSH, systemd), the wizard shows a login URL to open wherever you are.

Setting up from another device, or through a reverse proxy, asks for the one-time setup code the installer prints. It is also in the gateway log, and in $GLASSYS_DATA_DIR/setup-code until setup is done. A browser on the host itself needs no code.

Manage the service

Run these from the clone you installed from. An upgrade is git pull --ff-only, install, build and restart, and it checks that /health reports the new commit. It stops if the pull fails instead of rebuilding the old clone.

bash

$ cd glassys && pnpm run service:status
$ cd glassys && pnpm run service:upgrade
$ cd glassys && pnpm run service:uninstall

Linux: the unit is ~/.config/systemd/user/glassys.service. On a headless host, enable linger so logging out does not stop it, and read its logs from the journal:

bash

$ sudo loginctl enable-linger $USER
$ journalctl --user -u glassys

macOS: a LaunchAgent at ~/Library/LaunchAgents/dev.kn990x.glassys.plist with KeepAlive.

For a one-off debug session in the foreground (closing the terminal stops it):

bash

$ pnpm run build && pnpm start

Uninstall stops the service and removes the unit. It does not delete the clone or data/.

Reach it from your phone

The gateway binds to 127.0.0.1. For a public URL, terminate TLS in front of it and forward HTTP and the WebSocket (/ws) to 127.0.0.1:8787. Glassys is the app behind the proxy, not the proxy.

Caddy

Caddy 2 upgrades WebSockets on the same reverse_proxy. Replace the host name with yours.

Caddyfile

your.example.com {
	encode gzip
	reverse_proxy 127.0.0.1:8787
}

Cloudflare Tunnel and Access

Point a tunnel at http://127.0.0.1:8787 with WebSockets on. Access is optional and comes on top: set security.edgeAuth: cloudflare-access with your team domain and audience. Glassys still asks for its own operator password. With Access off, Glassys never calls Cloudflare.

With a proxy on the same host, every request reaches Glassys from 127.0.0.1. Set network.trustProxy: true (or GLASSYS_TRUST_PROXY=1) so login limits apply per visitor. Keep idle timeouts high: agent runs last minutes, and Glassys pings the socket every 25 s.

Web Push needs HTTPS (or localhost), and iOS only delivers push to an installed app: open the site in Safari and add it to the Home Screen.

docs/deploy/caddy.md docs/deploy/cloudflare.md

Configuration

Everything that is not a secret lives in $GLASSYS_DATA_DIR/config.yaml, created with defaults on first run (see config.example.yaml). Settings in the app writes locale, theme, agent, display and session; bind, port, allowed origins, trustProxy and edge auth are yaml or environment only.

Secrets — the optional per-adapter API keys, the operator password hash and the JWT secret — live in environment variables or $GLASSYS_DATA_DIR/secrets.json. The app can show configured / rotate, never the full key again.

Environment variables

Variable	What it does
`GLASSYS_DATA_DIR`	Where config, secrets, transcripts and schedules live (default: data/ in the clone).
`GLASSYS_BIND`	Address to listen on (default 127.0.0.1).
`GLASSYS_PORT`	Port to listen on (default 8787).
`GLASSYS_TRUST_PROXY`	Set to 1 behind a reverse proxy on the same host.
`GLASSYS_WEB_DIR`	Serve the app from another build.
`GLASSYS_NODE`	The node binary the installed service runs.
`GLASSYS_OPERATOR_PASSWORD_HASH`	Pin the operator password hash; it can then only be changed here.
`GLASSYS_JWT_SECRET`	Pin the session signing secret.

Optional adapter keys: CURSOR_API_KEY, ANTHROPIC_API_KEY, CODEX_API_KEY / OPENAI_API_KEY, OPENCODE_API_KEY, GEMINI_API_KEY / GOOGLE_API_KEY. The installer never copies them into the unit.

config.example.yaml

Agents

Glassys talks to each agent through its local SDK or through ACP, never through print-mode, which hides the thinking. The vendor’s CLI can stay installed: its login does not sign Glassys in.

Agent	How Glassys reaches it
Cursor	@cursor/sdk on the host — not cursor-cli or cursor-agent. Sign in with the Cursor SDK, or set CURSOR_API_KEY.
Claude Code	Claude Agent SDK.
OpenCode	OpenCode SDK and a local server; needs the opencode binary on PATH.
Codex	Codex SDK, with the Codex binary it ships.
Gemini	Through the ACP adapter (gemini --acp) until the Gemini CLI SDK is on npm.
Any ACP agent	The generic ACP host runs agents from the ACP registry.

Do not run two auto-run agents on the same working directory at once — for example the CLI in a terminal and Glassys on the same files.

Security

Glassys with auto-run and a host workspace is operator access to that machine.
Operator auth is always on, even behind Cloudflare Access.
Sandbox and auto-run are visible in Settings. With auto-run off, Cursor uses Auto-review, which denies risky calls, and ACP denies file writes and terminals.
Keep the workspace outside Glassys’s data directory. Claude and ACP refuse tool calls into it; Cursor, Codex, OpenCode and Gemini run their tools in their own process, so for them only a sandbox or a separate workspace keeps the agent out.
Do not bind 0.0.0.0 unless the proxy is the only public face.

Read SECURITY.md