Skip to main content

Quick Start

This guide walks you through initializing a project, a workspace and deploying them locally on a production-like cluster.

gws not installed? Start with Installation Guide.

Developer workflow​

gws cli extracts some information from your project and create the configuration file needed for deployment.

1. Authenticate​

Create a free GetWebstack account:

gws login

This opens your browser for authentication. Sign in with Google, GitHub, or email.

2. Initialize Your Project​

Navigate to your project directory and initialize the GetWebstack project shell:

cd /path/to/your/project
gws init

gws init is intentionally minimal: it prompts for a project name, registers the project with the API, writes .gws/.gitignore, and appends a GWS context block to AGENTS.md / CLAUDE.md if those files exist. It does not generate gws.json — that's the AI agent's job.

Now tell your AI agent (Claude Code, GitHub Copilot CLI, OpenAI Codex, Cursor, Amp, …) to run:

/gws-setup

The /gws-setup skill detects your services, generates gws.json, writes Dockerfiles + deployment manifests + Helm values, deploys, validates, and iterates if anything fails (5-attempt cap).

No AI agent? Skip to the manual escape hatch — you'll hand-author gws.json and run gws config import gws.json before gws up.

Full walkthrough: Zero-Config Setup with AI.

3. Deploy Locally​

Deploy your project to a local cluster:

gws up

GetWebstack will:

  • Create local cluster (if needed)
  • Build Docker images
  • Deploy to the cluster
  • Generate TLS certificates
  • Configure DNS routing
  • Start file sync (bidirectional)
  • Activate auto-rebuild watchers

Expected output:

✓ Validating dependencies...
✓ Creating cluster 'my-project'...
✓ Building Docker image for 'api'...
✓ Building Docker image for 'app'...
✓ Deploying to namespace 'my-project'...
✓ Configuring Gateway API routes...
✓ Starting file sync...

Deployment successful! 🎉

Services available at:
  - API:  https://api.my-project.local.getwebstack.dev
  - App:  https://app.my-project.local.getwebstack.dev

File sync active:
  - File sync: ✓ (0.5s latency)
  - Auto-rebuild: ✓ (Dockerfile changes)

Open the URLs in your browser:

4. Make Changes​

Edit a file in your project. Changes sync automatically to the running container. Refresh your browser to see updates.

5. Check Status​

View deployment status:

gws status

Expected output:

Project: my-project
Cluster: local (running)

Worktrees:
  ✓ default (main branch)
    Namespace: my-project
    Status: running
    Services:
      - api: ✓ running (1/1 pods)
      - app: ✓ running (1/1 pods)
    URLs:
      - https://api.my-project.local.getwebstack.dev
      - https://app.my-project.local.getwebstack.dev

6. View Logs​

View service logs:

# View all logs
gws logs

# View specific service logs
gws logs api

Setup worktree for AI Agents​

1. Create worktree​

gws fork feature-auth

This:

  1. Creates a new git worktree at .worktrees/feature-auth
  2. Creates a new branch env/feature-auth

2. Let the AI agent work​

The AI agent can now make changes in the isolated worktree.

3. Deploy worktree​

gws up -w feature-auth

Worktree available on:

Namespace: my-project-feature-auth
URLs (same hostnames as main — the `gws-namespace` cookie selects this fork):
  - https://api.my-project.local.getwebstack.dev
  - https://app.my-project.local.getwebstack.dev

Use the picker at https://my-project.local.getwebstack.dev to switch
between the default deployment and any fork.

4. Check All Environments​

gws status -w feature-auth

Output:

Worktrees:
  ✓ my-project (main)          - deployed
  ✓ feature-auth (agent)    - deployed

Both environments run in parallel, completely isolated.

Clean Up​

Stop a Worktree​

gws down -w feature-auth

This:

  • Stops deployment
  • Stops file sync
  • Deletes namespace
  • Keeps worktree directory (for review)

Delete a Worktree​

gws delete -w feature-auth

This:

  • Deletes worktree directory
  • Removes git branch (optional)

Stop Everything​

# Stop all worktrees, keep cluster
gws down

# Stop all worktrees and delete cluster & delete the local image registry/cache
gws down --delete-cluster --delete-registry

Need Help? Join our Slack community.​