Skip to main content

Installation

Get GetWebstack installed in under 5 minutes.

Name collision: gws vs @googleworkspace/cli

gws here is the GetWebstack CLI (this product). A separate, unrelated npm package, @googleworkspace/cli (Google Workspace/Gmail/Drive/Calendar automation), also installs a gws binary and also ships agent skills — do not confuse the two. If you already have a gws on PATH, check gws help --json: this product's catalog includes commands like up, qa, fork, and render. If you instead see Google Workspace commands (drive, gmail, sheets, ...), STOP — do not uninstall or modify anything on your machine. Report the name conflict as an error and reach out on the GetWebstack Slack for help resolving it.

Prerequisites​

You need:

That's it — k3d and mkcert are not prerequisites. gws up and gws cluster up auto-install both the first time they're needed: pinned versions, SHA-256-verified, downloaded sudo-free into ~/.gws/bin (never /usr/local/bin, never a sudo prompt), and this works the same in a headless CI/agent run as it does in an interactive terminal. macOS no longer needs Homebrew for either tool. Opt out with GWS_NO_AUTO_INSTALL=1, or --no-install-deps on gws up / gws cluster up for a single run, to fall back to the old TTY-prompt-or-print-the-command behavior (see Installing k3d / mkcert manually below).

Docker and Git are never auto-installed — they're system-level, sudo/package-manager territory, and gws deliberately leaves them alone.

No AI agent? Every other GWS command works without one. You'll hand-author gws.json and use gws config import instead of /gws-setup. See Zero-Config Setup with AI → Manual escape hatch.

Install​

# Install CLI + AI skills (/gws-setup, /gws-up, /gws-status, /gws-down, /gws-debug)
curl -sSL https://getwebstack.com/install.sh | bash
# Verify installation
gws --version

The install script also symlinks the GWS skills into ~/.claude/skills/ and ~/.agents/skills/ so any supported AI agent picks them up automatically. Re-run gws skills install (or gws update) at any time to refresh.

After install, in this order​

  1. gws login — this is interactive: it opens a browser for OAuth (Google/GitHub/email). If an AI agent is driving this install, hand this step off to the user and wait for them to confirm it completed — don't attempt to script or complete the browser flow yourself.
  2. Run /gws-setup (a coding-agent skill: analyzes the repo, generates gws.json + Dockerfiles, registers with the API, deploys, validates). If /gws-setup isn't in your session's skill list yet — skills register at session start, so an install partway through a session won't be visible until the agent restarts — read the installed skill file directly and follow it instead: ~/.claude/skills/gws-setup/SKILL.md (Claude Code, Copilot CLI) or ~/.agents/skills/gws-setup/SKILL.md (Codex, Amp, Cursor). It's a single self-contained file, so this fallback works immediately, without waiting for a restart.

That's it! You're ready to start.

Next step: read Zero-Config Setup with AI for the headline workflow, or jump straight into the Quick Start.

Troubleshooting​

Docker not running​

docker info will hang or error if the daemon isn't up. Start Docker Desktop, or on Linux run sudo systemctl start docker.

Port already in use​

sudo lsof -ti:8080 | xargs kill -9

k3d or mkcert failed to auto-install​

gws up / gws cluster up print the tool name, pinned version, and install path on success, or a warning plus the manual command on failure (e.g. no network access, or an unsupported platform/arch combination with no prebuilt binary). Re-run gws up once the underlying issue (usually network access to GitHub Releases) is fixed — the auto-install is idempotent. To skip auto-install entirely, see Installing k3d / mkcert manually below.

Installing k3d / mkcert manually (optional)​

You shouldn't need this — gws up / gws cluster up auto-install both tools by default (see Prerequisites). Use this appendix only if you set GWS_NO_AUTO_INSTALL=1 / --no-install-deps, you're on a platform/architecture gws doesn't ship a pinned binary for, or you just prefer a package-manager-managed install:

With GWS_NO_AUTO_INSTALL=1 set, gws up detects a missing/outdated tool and prints the exact command it would otherwise have run automatically — so you never have to guess the version to install.