Skip to main content

Quick Start

This guide walks you through initializing a project, a workspace and deploying them locally on Kubernetes 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 GetWebStack:

cd /path/to/your/project
gws init

GetWebStack will:

  1. Auto-detect your services (Node.js, Python, Docker, etc.)
  2. Generate gws.json configuration

You need to confirm or set a new project name and to select the host services (APIs & frontends).

3. Deploy Locally​

Deploy your project to a local Kubernetes cluster:

gws up

GetWebStack will:

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

Expected output:

✓ Validating dependencies...
✓ Creating k3d 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

Dev mode 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: k3d (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 create 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:
  - https://api.my-project-feature-auth.local.getwebstack.dev
  - https://app.my-project-feature-auth.local.getwebstack.dev

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-registrey

Need Help? Join our Discord community.​