gstack Administrator & Developer Guide

gstack (Garry's Stack) is an all-in-one AI engineering toolkit built on Bun, providing headless browser automation, AI-powered design generation, PDF rendering, and 30+ Claude Code slash-command skills. This guide covers architecture, configuration, deployment, security, and developer internals for administrators and contributors working with gstack v1.10.1.0.

1. Architecture Overview

1.1 System Design

gstack is organized as a monorepo with four primary subsystems that share a common Bun runtime:

┌─────────────────────────────────────────────────────────────┐
│                        gstack CLI                           │
│  browse/src/cli.ts → HTTP → browse/src/server.ts (Bun)     │
│                              ├── BrowserManager (Playwright)│
│                              ├── Security Classifier        │
│                              ├── Activity Stream (SSE)      │
│                              ├── Token Registry (multi-agent)│
│                              └── Sidebar Agent (Claude)      │
├─────────────────────────────────────────────────────────────┤
│  design/src/cli.ts → OpenAI GPT-4o Image API               │
│  make-pdf/src/cli.ts → browse CLI → Chromium PDF           │
├─────────────────────────────────────────────────────────────┤
│  Skills System                                               │
│  ├── SKILL.md.tmpl (templates with resolver placeholders)    │
│  ├── scripts/resolvers/ (dynamic content generators)         │
│  ├── scripts/gen-skill-docs.ts (multi-host doc generation)   │
│  └── hosts/ (per-host config: path rewrites, frontmatter)    │
├─────────────────────────────────────────────────────────────┤
│  Supabase Backend                                            │
│  ├── telemetry-ingest (edge function)                        │
│  ├── community-pulse (edge function, cached)                 │
│  ├── update-check (edge function)                            │
│  └── Migrations (001-004): telemetry, RLS, upsert, attack   │
├─────────────────────────────────────────────────────────────┤
│  Chrome Extension                                            │
│  ├── background.js (health polling, command proxy, refs)     │
│  ├── sidepanel.js (activity stream, chat)                    │
│  ├── content.js (indicator injection, inspector)             │
│  └── inspector.js (element picking)                          │
└─────────────────────────────────────────────────────────────┘

browse is the centerpiece: a persistent HTTP server wrapping Playwright-driven Chromium. The CLI (browse/src/cli.ts) is a thin client that sends commands over HTTP to the long-running server (browse/src/server.ts). This architecture means the browser persists across individual command invocations, preserving page state, cookies, and sessions.

design is a standalone tool that calls the OpenAI GPT-4o Responses API for image generation, with iterative refinement, vision-based quality gates, and gallery management.

make-pdf orchestrates Markdown-to-PDF conversion by rendering HTML through the browse server's Chromium instance, using print-optimized CSS.

Skills are template-driven slash commands. Each skill is a .md.tmpl file with resolver placeholders (e.g., {{BROWSE_COMMAND_REFERENCE}}) that get expanded at generation time by TypeScript resolvers. The gen-skill-docs.ts script produces host-specific versions for each supported AI coding environment.

1.2 Process Model

The browse server uses Bun's HTTP server with a single-threaded event loop. Key architectural decisions:

• Persistent server: The browse server starts once and stays alive, with an idle timeout (BROWSE_IDLE_TIMEOUT). CLI commands talk to it over localhost HTTP.
• Token-based auth: The server generates a random token on startup, writes it to a state file, and all /command requests require Bearer <token>.
• Tab sessions: Each browser tab is managed by a TabSession instance (browse/src/tab-session.ts) that tracks refs, frames, and loaded HTML independently.
• Watchdog: The CLI can set BROWSE_PARENT_PID so the server auto-exits when the parent process dies (set to 0 to disable).

1.3 Technology Stack

1.4 Module Reference

browse/src/ — Core Browser Engine

design/src/ — AI Design Tool

make-pdf/src/ — PDF Rendering Pipeline

lib/ — Shared Libraries

scripts/ — Build & Generation

2. System Requirements

2.1 Runtime Requirements

2.2 External Service Dependencies

Note

The browse server itself requires no external API keys. It runs entirely locally with Playwright-managed Chromium. API keys are only needed for the design tool (OpenAI) and optional features like tunneling (ngrok) or sidebar chat (Anthropic).

2.3 Supported AI Coding Hosts

gstack generates host-specific skill files for these environments:

3. Configuration Reference

gstack is configured entirely through environment variables. There are no YAML or TOML configuration files.

3.1 Browse Server Configuration

Tip

For CI/CD pipelines, BROWSE_PARENT_PID=0 prevents the watchdog from killing the server if the parent shell exits. Combine with BROWSE_PORT for deterministic port assignment in parallel test environments.

3.2 Security Configuration

Warning

Setting GSTACK_SECURITY_OFF=1 disables prompt injection detection entirely. This removes the ML ensemble that protects against malicious web content being injected into AI agent conversations. Only disable for debugging or in fully trusted environments.

3.3 Tunnel Configuration

3.4 Design Tool Configuration

3.5 PDF Tool Configuration

3.6 Platform / Environment Detection

3.7 Sidebar Agent Configuration

3.8 Testing & Eval Configuration

Note

The eval system supports tiered execution: gate evals run on every PR, while periodic evals run on a schedule. Set EVALS_ALL=1 to force all tiers in a single run.

4. Deployment & Scaling

4.1 Installation

# Clone the repository
git clone https://github.com/garrytan/gstack.git
cd gstack

# Install dependencies (Bun handles everything)
bun install

# Build the browse server bundle (required for Windows)
bun run build

4.2 Browse Server Lifecycle

The browse server follows a specific lifecycle:

1. Auto-start: When the CLI sends a command and no server is running, it auto-starts one (unless BROWSE_NO_AUTOSTART is set).
2. Port discovery: The server tries a range of ports, or uses BROWSE_PORT if set. If the port is taken, it fails with a clear error.
3. State file: On startup, the server writes its PID, port, and auth token to the state file (default: .gstack/browse-state.json).
4. Idle timeout: After BROWSE_IDLE_TIMEOUT seconds of no requests, the server shuts down.
5. Watchdog: If BROWSE_PARENT_PID is set and that process dies, the server exits.

# Start server explicitly with headed Chromium
BROWSE_HEADED=1 BROWSE_PORT=9222 bun run browse/src/server.ts

# Start with tunneling enabled
BROWSE_TUNNEL=1 NGROK_AUTHTOKEN=your_token bun run browse/src/server.ts

4.3 CI/CD Integration

For CI environments:

# Recommended CI environment variables
export CI=1                    # Adds --no-sandbox for containerized Chromium
export BROWSE_PARENT_PID=0     # Disable watchdog
export BROWSE_PORT=9222        # Fixed port for predictability
export GSTACK_SECURITY_OFF=1   # Optional: skip ML classifier in trusted CI

Important

Chromium requires --no-sandbox inside Docker containers and most CI runners. gstack automatically adds this flag when CI=1 or CONTAINER=1 is set. Without it, the browser will fail to launch with a sandbox-related error.

4.4 Container Deployment

The browse server can run in Docker. Key considerations:

• Mount a volume for .gstack/ to persist state across restarts
• Expose the browse server port
• Set CONTAINER=1 for automatic --no-sandbox
• Chromium needs shared memory — use --shm-size=2g or mount /dev/shm

FROM oven/bun:latest

WORKDIR /app
COPY . .
RUN bun install

ENV CONTAINER=1
ENV BROWSE_PORT=9222

EXPOSE 9222

CMD ["bun", "run", "browse/src/server.ts"]

docker run -d \
  --shm-size=2g \
  -p 9222:9222 \
  -e CONTAINER=1 \
  -e BROWSE_PORT=9222 \
  -v gstack-state:/app/.gstack \
  gstack-browse

4.5 Multi-Agent Deployment

gstack supports multiple AI agents sharing a single browse server through the token registry:

1. The primary agent starts the server and gets the admin token from the state file.
2. Additional agents connect via the /pair endpoint to get scoped tokens.
3. Token scopes (read, write, admin, meta, control) restrict what each agent can do.

This enables architectures where a supervisor agent delegates browsing tasks to worker agents, each with least-privilege access.

4.6 Remote Access via ngrok

For accessing the browse server from remote machines:

export BROWSE_TUNNEL=1
export NGROK_AUTHTOKEN=your_ngrok_token
export NGROK_DOMAIN=custom.ngrok.io  # Optional: custom domain

# Server will log the tunnel URL on startup
bun run browse/src/server.ts

Caution

The ngrok tunnel exposes your browse server to the internet. While token-based authentication protects the /command endpoint, ensure your ngrok account has appropriate access controls. Denied tunnel access attempts are logged by tunnel-denial-log.ts.

5. Operations

5.1 HTTP API Endpoints

The browse server exposes these HTTP endpoints:

5.2 Server State File

The browse server persists its state to .gstack/browse-state.json (or the path in BROWSE_STATE_FILE). This file contains:

• Server PID
• Server port
• Authentication token
• Server start timestamp

The CLI reads this file to discover and authenticate with a running server. If the state file is stale (PID no longer alive), the CLI starts a new server.

5.3 Audit Log

Every command execution is logged to .gstack/browse-audit.jsonl as append-only JSONL. Each entry includes:

• Timestamp
• Command name and arguments
• Agent token (anonymized)
• Result status
• Execution duration

This provides a forensic trail for debugging multi-agent interactions and security incidents.

5.4 Telemetry

gstack sends anonymous telemetry to Supabase edge functions:

• telemetry-ingest: Batch insertion of usage events (max 100 events, max 50KB per request)
• community-pulse: Aggregated community statistics (cached for 1 hour)
• update-check: Version ping that logs installation info

Supabase configuration (public, non-secret) lives in supabase/config.sh.

Note

Telemetry is anonymous. Session tracking is gated by telemetry configuration (see issue #1150 for the gating fix).

5.5 Upgrade System

gstack includes a versioned migration system in gstack-upgrade/migrations/:

Migrations run automatically during gstack updates and are idempotent.

5.6 Monitoring

Health check:

curl http://localhost:9222/health

Process monitoring:

# Check if server is alive using state file
cat .gstack/browse-state.json | jq '.pid' | xargs kill -0

Audit log tail:

tail -f .gstack/browse-audit.jsonl | jq .

6. Performance

6.1 Browser Resource Management

The BrowserManager manages Chromium's resource consumption:

• Tab limit: Each tab is a TabSession with its own page context. More tabs means more memory.
• Circular buffers: Console and network captures use CircularBuffer (fixed-size ring buffers) to prevent unbounded memory growth.
• Size-capped network capture: SizeCappedBuffer in network-capture.ts caps total captured network data.
• Idle timeout: The server auto-shuts down after inactivity, freeing all Chromium resources.

6.2 Chromium Launch Optimization

The server applies platform-specific Chromium flags:

• --no-sandbox in CI/container environments
• Anti-detection patches in headed mode (navigator.webdriver, plugins, languages, CDP artifacts, Permissions API)
• Custom Chromium binary via GSTACK_CHROMIUM_PATH for pre-warmed or optimized builds

6.3 PDF Rendering Performance

The make-pdf pipeline chains Markdown parsing (marked) through HTML rendering to Chromium's PDF output. For large documents:

• The ProgressReporter class in orchestrator.ts provides real-time feedback during multi-file orchestration
• Print-optimized CSS (print-css.ts) ensures clean page breaks and typography
• smartypants.ts applies typography improvements (curly quotes, em-dashes) in a single pass

6.4 Security Classifier Overhead

The ML security ensemble adds latency to command processing. If this is a bottleneck in trusted environments:

• Set GSTACK_SECURITY_OFF=1 to disable entirely
• Configure GSTACK_SECURITY_ENSEMBLE to activate only specific layers
• Adjust GSTACK_HAIKU_TIMEOUT_MS to cap the Haiku classifier timeout

Tip

In development, the security classifier can add noticeable latency to the first request while ML models load. Subsequent requests use cached models. Pre-warm the server by sending a no-op command after startup.

7. Security

7.1 Authentication Model

The browse server uses a token-based authentication system:

1. Server token: Generated randomly on each server startup and written to the state file. Required as Bearer <token> header on all /command requests.
2. Multi-agent tokens: The TokenRegistry (browse/src/token-registry.ts) manages scoped tokens for paired agents.

Token scopes:

7.2 ML Security Classifier

The security classifier (browse/src/security-classifier.ts) uses an ensemble of five detection layers to identify prompt injection attacks in web content:

The classifier produces verdicts: SAFE, WARN, or BLOCK. Attack telemetry (domain, payload hash, confidence, layer, verdict) is stored in Supabase via migration 004.

Important

Issue #1156 notes that WARN verdicts currently take no defensive action beyond logging. Until this is addressed, WARN-level detections are informational only. Monitor audit logs for WARN verdicts in production deployments.

7.3 Content Security

The content security module (browse/src/content-security.ts) filters untrusted web content before it reaches AI agents:

• All web-sourced content is wrapped between BEGIN UNTRUSTED CONTENT and END UNTRUSTED CONTENT markers
• The BROWSE_CONTENT_FILTER environment variable controls filtering aggressiveness
• This prevents web content from being interpreted as instructions by downstream AI agents

7.4 URL Validation

browse/src/url-validation.ts implements:

• Cloud metadata blocking: Blocks access to 169.254.169.254 and similar cloud metadata endpoints (SSRF prevention)
• file:// validation: Restricts file URL access to safe directories
• Allowlist/blocklist: Configurable URL filtering

7.5 Path Security

browse/src/path-security.ts enforces a safe directory allowlist for all file operations. Any path outside the allowed directories triggers the error:

Path must be within: <SAFE_DIRECTORIES>

7.6 Privacy Filtering

The activity stream (browse/src/activity.ts) automatically redacts:

• Passwords
• Authentication tokens
• Sensitive query parameters

This ensures the Chrome extension's side panel and activity stream do not leak credentials.

7.7 Cookie Security

BrowserManager tracks imported cookie domains to maintain an elevated security context for those origins. Cookie import (browse/src/cookie-import-browser.ts) supports extracting cookies from installed browsers.

7.8 Anti-Bot Stealth

In headed mode (BROWSE_HEADED=1), gstack patches Chromium to evade bot detection:

• navigator.webdriver returns false
• Plugin and language arrays are populated with realistic values
• CDP (Chrome DevTools Protocol) artifacts are hidden
• Permissions API behavior is normalized

7.9 Supabase Row-Level Security

The database migrations progressively tighten RLS policies:

• Reads blocked on all tables (telemetry data is write-only from clients)
• Updates restricted to tracking columns only (cannot modify event payload)
• Inserts kept for backward compatibility with older client versions

Verify RLS policies are correctly applied:

./supabase/verify-rls.sh

7.10 Audit Trail

The audit log (browse/src/audit.ts) writes append-only JSONL to .gstack/browse-audit.jsonl. This log is the forensic record for:

• All command executions
• Authentication events
• Security classifier verdicts
• Tunnel access attempts (denied attempts logged separately by tunnel-denial-log.ts)

Warning

The audit log grows without bound. Implement log rotation for long-running deployments. The log file path is determined by the state directory (.gstack/ by default).

8. Developer Internals

8.1 Repository Structure

gstack/
├── browse/
│   ├── src/              # Browser automation engine
│   │   ├── server.ts     # HTTP server entry point
│   │   ├── cli.ts        # CLI client entry point
│   │   └── ...           # 25+ modules (see Module Reference)
│   └── test/             # Browse tests
├── design/
│   └── src/              # AI design tool (15 modules)
├── make-pdf/
│   └── src/              # PDF pipeline (8 modules)
├── skills/               # SKILL.md.tmpl templates
├── scripts/
│   ├── resolvers/        # Template resolvers (18 resolvers)
│   ├── host-adapters/    # Host-specific adapters
│   └── gen-skill-docs.ts # Multi-host doc generator
├── hosts/                # Per-host config (10 hosts)
├── lib/                  # Shared libraries (worktree.ts)
├── model-overlays/       # Model-specific behavior files
│   ├── claude.md
│   ├── gemini.md
│   ├── gpt.md
│   ├── gpt-5.4.md
│   ├── o-series.md
│   └── opus-4-7.md
├── extension/            # Chrome extension (Manifest V3)
├── supabase/
│   ├── functions/        # Edge functions (3)
│   ├── migrations/       # Schema migrations (001-004)
│   ├── config.sh         # Public Supabase config
│   └── verify-rls.sh     # RLS smoke test
├── gstack-upgrade/
│   └── migrations/       # Version migrations (4)
└── test/
    └── helpers/          # Test utilities

8.2 Key Classes

8.3 Skills System Architecture

Skills are the primary interface between gstack and AI coding hosts. The generation pipeline works as follows:

1. Templates: Each skill has a SKILL.md.tmpl file with resolver placeholders like {{BROWSE_COMMAND_REFERENCE}}, {{INVOKE_SKILL}}, {{CONFIDENCE_CALIBRATION}}.

2. Resolvers: TypeScript functions in scripts/resolvers/ that generate dynamic content. The resolver registry (scripts/resolvers/index.ts) maps placeholder names to resolver functions.

3. Host configs: Each host in hosts/ defines path rewrites and frontmatter requirements. For example, Codex requires specific frontmatter transformation (scripts/resolvers/codex-helpers.ts).

4. Generation: scripts/gen-skill-docs.ts iterates over all templates, runs resolvers, applies host-specific transformations, and writes final .md files.

5. Model overlays: Files in model-overlays/ provide model-specific behavior adjustments (Claude, Gemini, GPT, GPT-5.4, O-series, Opus 4-7).

8.4 Command System

Browse commands are split into three categories by side-effect profile:

Read commands (browse/src/read-commands.ts) — no page mutation:

Write commands (browse/src/write-commands.ts) — mutate page state:

Meta commands (browse/src/meta-commands.ts) — server/session operations:

8.5 Snapshot System

The snapshot module (browse/src/snapshot.ts) produces accessibility tree representations and annotated screenshots. These are the primary mechanism by which AI agents "see" web pages:

• Accessibility tree: Extracts the page's a11y tree into a structured text format that AI agents can reason about
• Annotated screenshots: Captures the page with element reference overlays for visual grounding

8.6 Testing Strategy

gstack uses Bun's built-in test runner with a tiered evaluation system:

Test infrastructure:

• test/helpers/agent-sdk-runner.ts: Parallel SDK session runner with Semaphore for concurrency control and RateLimitExhaustedError handling
• test/helpers/benchmark-judge.ts: LLM-based evaluation judge (uses Anthropic API)
• test/helpers/e2e-helpers.ts: End-to-end test helpers with eval mode gating
• test/helpers/eval-store.ts: EvalCollector for aggregating evaluation results
• test/helpers/session-runner.ts: Session management for eval runs (supports EVALS_MODEL override)

# Run unit tests
bun test

# Run gate evals
EVALS=1 EVALS_TIER=gate bun test

# Run all evals with a specific model
EVALS=1 EVALS_ALL=1 EVALS_MODEL=claude-3-5-sonnet bun test

8.7 Git Worktree Manager

lib/worktree.ts provides the WorktreeManager class for creating isolated Git worktrees. This is used by skills that need to run tests or builds in isolation without affecting the main working directory.

8.8 Code Patterns

Error handling: gstack uses safeUnlink, safeKill, and isProcessAlive utilities (browse/src/error-handling.ts) for defensive cleanup. Custom error classes (CookieImportError, BrowseClientError, PdftotextUnavailableError) provide typed error handling.

State management: The browse server treats the filesystem as persistent state. The state file, audit log, and session cookies are all file-based. resolveConfig() in browse/src/config.ts determines the state directory based on project detection.

Buffer management: Two buffer implementations prevent unbounded memory growth:

• CircularBuffer (fixed item count, ring buffer) for console/dialog logs
• SizeCappedBuffer (fixed byte size) for network captures

Platform abstraction: browse/src/platform.ts handles OS detection and temp directory resolution, enabling cross-platform behavior in cookie import, path validation, and process management.

8.9 Contributing

Adding a New Browse Command

1. Determine the command category (read, write, or meta).
2. Add the handler function to the appropriate module (read-commands.ts, write-commands.ts, or meta-commands.ts).
3. Register the command in server.ts's command dispatch.
4. Update the browse resolver (scripts/resolvers/browse.ts) to include it in generated documentation.
5. Add tests.

Adding a New Skill

1. Create a SKILL.md.tmpl file in the skills/ directory.
2. Use resolver placeholders ({{RESOLVER_NAME}}) for dynamic content.
3. If a new resolver is needed, add it to scripts/resolvers/ and register it in scripts/resolvers/index.ts.
4. Run bun run scripts/gen-skill-docs.ts to generate host-specific versions.
5. Test with each target host.

Adding a New Host

1. Create a host config file in hosts/ (e.g., hosts/newhost.ts).
2. Define path rewrites and frontmatter requirements.
3. Register the host in hosts/index.ts.
4. If the host needs special handling, create an adapter in scripts/host-adapters/.
5. Run skill generation and verify output.

Adding a New Resolver

1. Create a resolver module in scripts/resolvers/.
2. Export a function that returns the resolved content string.
3. Register the resolver name in scripts/resolvers/index.ts.
4. Use the placeholder in skill templates: {{YOUR_RESOLVER_NAME}}.

Adding a Supabase Migration

1. Create a new migration file in supabase/migrations/ following the naming pattern 00N-description.sql.
2. Apply the migration to your Supabase project.
3. Update supabase/verify-rls.sh if the migration adds new tables or policies.
4. Test with the telemetry-ingest and community-pulse edge functions.

9. Integration Points

9.1 Chrome Extension

The Chrome extension (extension/) connects to the browse server for real-time interaction:

The extension communicates with the browse server via:

• /health for connection status polling
• /activity/stream (SSE) for real-time event streaming
• /command for executing browse commands from the side panel
• /refs for element reference data

9.2 Supabase Backend

Tables:

Views:

Edge functions:

Tip

The community-pulse endpoint caches results for one hour. During development, you may need to wait for cache expiration or clear the community_pulse_cache table directly to see updated aggregations.

9.3 Model Overlays

Model overlay files in model-overlays/ provide behavioral adjustments for different LLMs:

These overlays are injected into skill templates via the model-overlay resolver (scripts/resolvers/model-overlay.ts) to tune prompt behavior for each model's strengths and characteristics.

9.4 make-pdf Integration

The make-pdf tool depends on the browse server for rendering:

Markdown → marked parser → HTML + print-css → browse load-html → Chromium PDF

make-pdf/src/browseClient.ts provides a typed wrapper around shell-outs to the browse CLI. Set BROWSE_BIN to override binary discovery. The pipeline includes:

1. Setup (setup.ts): One-time dependency check
2. Rendering (render.ts): Markdown to HTML conversion with typography improvements
3. Orchestration (orchestrator.ts): Multi-file coordination with progress reporting
4. Verification (pdftotext.ts): Optional text extraction to verify PDF content

10. Troubleshooting

Error: Server failed to start within Ns

Cause: The browse server did not become ready within the startup timeout, typically because Chromium failed to launch.

Solution:

1. Check that Chromium is installed: bunx playwright install chromium
2. In containers, ensure CI=1 or CONTAINER=1 is set for --no-sandbox
3. Verify sufficient shared memory: df -h /dev/shm (need 256MB+)
4. Check for port conflicts: lsof -i :9222

Prevention: Set BROWSE_PORT to avoid port scanning delays. Use GSTACK_CHROMIUM_PATH for a known-good binary.

Error: Cannot find server.ts. Set BROWSE_SERVER_SCRIPT env or run from the browse source tree.

Cause: The CLI cannot locate the server entry point. This happens when running the browse CLI from outside the gstack directory.

Solution:

1. Run from within the gstack repository
2. Or set the BROWSE_SERVER_SCRIPT environment variable to the absolute path of browse/src/server.ts

Prevention: Install gstack globally or use a shell alias that includes the correct working directory.

Error: server-node.mjs not found. Run 'bun run build' to generate the Windows server bundle.

Cause: On Windows, the browse server requires a pre-built bundle that has not been generated.

Solution:

bun run build

Prevention: Always run bun run build after cloning or updating the repository on Windows.

Error: Authentication failed (HTTP 401)

Cause: The CLI is using a stale token that does not match the running server's token.

Solution:

1. Check the state file: cat .gstack/browse-state.json
2. Verify the server PID is still alive
3. If the server was restarted, the CLI will auto-discover the new token on the next command
4. Delete the state file and let the CLI start a fresh server

Prevention: Let the CLI manage server lifecycle automatically rather than starting the server manually.

Error: [browse] Server crashed twice in a row — aborting

Cause: The server process crashed on two consecutive startup attempts.

Solution:

1. Check system logs for Chromium crash details
2. Verify system resources (RAM, disk space)
3. Try with BROWSE_HEADED=1 to see if the browser window shows an error
4. Check for conflicting Chromium processes: ps aux | grep chromium

Prevention: Monitor system resources. In CI, allocate sufficient --shm-size for Docker.

Error: Browser not launched

Cause: A command was sent before the browser context was initialized.

Solution:

1. Wait for the server to fully start (check /health endpoint)
2. If using BROWSE_HEADLESS_SKIP=1, the browser will not launch — unset this variable

Prevention: Use the CLI's auto-start mechanism rather than manual server management.

Error: Tab N not found

Cause: The specified tab ID does not exist or has been closed.

Solution:

1. List available tabs: browse tabs
2. Use a valid tab ID or omit BROWSE_TAB to use the active tab

Prevention: Do not hardcode tab IDs across sessions. Query available tabs before switching.

Error: No active page. Use browse goto <url> first.

Cause: The current tab has no page loaded (e.g., fresh server with no navigation).

Solution:

browse goto https://example.com

Prevention: Always navigate to a URL before running page commands.

Error: [browse] Port N (from BROWSE_PORT env) is in use

Cause: The port specified in BROWSE_PORT is already occupied by another process.

Solution:

1. Find what is using the port: lsof -i :N (or netstat -tlnp | grep N)
2. Kill the process or choose a different port
3. Unset BROWSE_PORT to use automatic port discovery

Prevention: Use port ranges rather than fixed ports in multi-instance deployments.

Error: [browse] No available port after N attempts in range MIN-MAX

Cause: All ports in the auto-discovery range are occupied.

Solution:

1. Check for zombie browse server processes: ps aux | grep server.ts
2. Clean up stale state files: rm .gstack/browse-state.json
3. Kill orphaned Chromium processes

Prevention: Ensure the watchdog (BROWSE_PARENT_PID) is active so servers auto-exit with their parent.

Error: MHTML archive requires Chromium CDP

Cause: The mhtml command was invoked but CDP (Chrome DevTools Protocol) is not available.

Solution: MHTML archiving requires a Chromium-based browser. Ensure you are not using a non-Chromium browser override via GSTACK_CHROMIUM_PATH.

Prevention: Only use mhtml with the default Playwright Chromium or a compatible Chromium binary.

Error: Path must be within: <SAFE_DIRECTORIES>

Cause: A file operation (upload, file serving) attempted to access a path outside the allowed directories.

Solution:

1. Move the file to a directory within the allowlist
2. Check browse/src/path-security.ts for the current safe directory list

Prevention: Keep working files within the project directory or configured safe directories.

Error: URL validation failures (cloud metadata, blocked domains)

Cause: The URL validation module blocked a request to a restricted URL.

Solution:

1. For cloud metadata blocking (169.254.169.254): this is intentional SSRF prevention — do not bypass
2. For file:// URLs: ensure the file path is within safe directories
3. Check URL against the allowlist/blocklist in browse/src/url-validation.ts

Prevention: Use goto with HTTPS URLs. For local files, use load-html with file content instead of file:// URLs.

Error: Exit code 128 in conductor template creation

Cause: Git operations failed due to unborn HEAD or missing refs (GitHub issues #1174, #1176).

Solution:

1. Ensure the repository has at least one commit
2. Check that the current branch has a valid HEAD reference
3. If using worktrees, verify the main repository is in a clean state

Prevention: Initialize repositories with an initial commit before running conductor skills.

Error: DESIGN_NOT_AVAILABLE in Codex workflows

Cause: Design tool is not available in the Codex environment (GitHub issue #1159).

Solution: The design tool requires OpenAI API access. Verify OPENAI_API_KEY is set and accessible in the Codex environment.

Prevention: Check host compatibility before invoking design workflows. Not all hosts support all gstack features.

Error: Custom OPENAI_BASE_URL not respected

Cause: The design tool does not honor custom OpenAI base URL configuration (GitHub issue #957).

Solution: Currently a known limitation. Use the standard OpenAI API endpoint or monitor issue #957 for a fix.

Prevention: Do not rely on custom base URLs for gstack's design features.

Error: ./setup --help runs install instead of showing help

Cause: The --help flag is not properly intercepted before the install flow (GitHub issue #1133).

Solution: Run gstack --help for general help instead.

Prevention: Refer to this guide for setup options.

Error: ./setup --prefix bug

Cause: The --prefix option in setup has a known issue (GitHub issue #620).

Solution: Use the default installation path or manually configure after setup.

Prevention: Monitor issue #620 for a fix.

Error: Review skill not looking at correct diff

Cause: The review skill examines the wrong diff base (GitHub issue #1152).

Solution: Explicitly specify the base branch when invoking the review skill, or ensure your Git branch tracking is configured correctly.

Prevention: Verify git diff output matches expectations before running the review skill.

Error: Codex generated skills carried Claude defaults

Cause: Host-specific skill generation was not properly transforming Claude defaults to Codex equivalents (GitHub issue #1163).

Solution: Regenerate skills with bun run scripts/gen-skill-docs.ts after updating to a version with this fix.

Prevention: After updating gstack, always regenerate skills for all hosts.

Error: WARN verdict takes no defensive action

Cause: The security classifier's WARN verdict logs the detection but does not block the content (GitHub issue #1156).

Solution: Monitor audit logs for WARN verdicts manually. Consider treating high-confidence WARNs as BLOCKs in your own middleware.

Prevention: Follow issue #1156 for the planned enforcement of WARN verdicts.

Caution

When debugging browse server issues, check the audit log (.gstack/browse-audit.jsonl) first. It contains timestamped records of every command execution, authentication event, and security verdict, making it the fastest path to root cause.

11. Supabase Schema Reference

11.1 Tables

telemetry_events: Stores raw telemetry events. Client-writable (INSERT only), reads blocked by RLS.

installations: Tracks unique gstack installations. Populated by the update-check edge function.

update_checks: Version check history — logs which versions are checking for updates.

community_pulse_cache: Cached aggregation table used by the community-pulse edge function (1-hour TTL).

11.2 Views

11.3 Migration History

Note

RLS policies are strict: clients can INSERT telemetry but cannot READ any data back. Telemetry is effectively write-only from the client perspective. All aggregation happens server-side via edge functions.

12. Quick Reference

Environment Variable Cheat Sheet

# Essential browse server config
export BROWSE_PORT=9222
export BROWSE_HEADED=1
export BROWSE_IDLE_TIMEOUT=3600
export BROWSE_PARENT_PID=0

# Security (development only)
export GSTACK_SECURITY_OFF=1

# Tunneling
export BROWSE_TUNNEL=1
export NGROK_AUTHTOKEN=your_token

# Design tool
export OPENAI_API_KEY=sk-your-key

# CI/containers
export CI=1
export CONTAINER=1

# Custom Chromium
export GSTACK_CHROMIUM_PATH=/usr/bin/chromium-browser

Common Operations

# Start headed browse server
BROWSE_HEADED=1 bun run browse/src/server.ts

# Health check
curl http://localhost:9222/health

# Run all tests
bun test

# Run gate evals
EVALS=1 EVALS_TIER=gate bun test

# Generate skill docs for all hosts
bun run scripts/gen-skill-docs.ts

# Build Windows bundle
bun run build

# Verify Supabase RLS
./supabase/verify-rls.sh

# Tail audit log
tail -f .gstack/browse-audit.jsonl | jq .

HTTP API Quick Reference

# Execute a command
curl -X POST http://localhost:9222/command \
  -H "Authorization: Bearer $(jq -r .token .gstack/browse-state.json)" \
  -H "Content-Type: application/json" \
  -d '{"command": "goto", "args": ["https://example.com"]}'

# Pair a new agent with read-only access
curl -X POST http://localhost:9222/pair \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"scopes": ["read"]}'

# Get element references
curl http://localhost:9222/refs \
  -H "Authorization: Bearer $TOKEN"

# Stream activity (SSE)
curl -N http://localhost:9222/activity/stream \
  -H "Authorization: Bearer $TOKEN"

See the User Guide for hands-on usage tutorials, CLI command reference, and workflow examples.