Zero-Config Setup with AI

GetWebstack is designed to be driven by an AI coding agent. Instead of asking you to fill in a wizard or hand-author gws.json, the CLI ships a set of skills that any modern AI agent can use to read your repo, generate a configuration, deploy it, and iterate until it works.

This page explains the moving parts so you (and your AI) know what's going on.

TL;DR: Run gws init to register the project shell, then tell your AI agent /gws-setup. It will figure out the rest.

The model

There are exactly two sources of truth in a GetWebstack project:

gws.json — your project's deployable configuration. Lives in the API. The local file in your repo is a working copy.
The cluster — what's actually running, derived from gws.json by gws up.

Everything else (Dockerfiles, deployment manifests, Helm values) is regenerated from gws.json whenever needed. There are no hand-edited deployment artifacts to keep in sync.

The AI's job is to produce a gws.json that, when imported and applied, results in a healthy cluster. Your job is to review the diff and approve.

Prerequisites

You need a supported AI coding agent installed and on your PATH:

Agent	Skill location	Notes
Claude Code	`~/.claude/skills/`	First-class support
GitHub Copilot CLI	`~/.claude/skills/`	Reads the same skills directory
OpenAI Codex CLI	`~/.agents/skills/`	First-class support
Cursor	`~/.agents/skills/`	First-class support
Amp	`~/.agents/skills/`	First-class support

The install.sh script symlinks the GWS skills into both directories, so any of these tools picks them up automatically. Re-run gws skills install (or just gws update) if a directory is missing.

No AI agent? Skip ahead to Manual escape hatch. Every other GWS command works without one.

What ships with the install

curl -sSL https://getwebstack.com/install.sh | bash

In addition to the gws binary at ~/.gws/bin/gws, the installer drops these skills into your AI agent's skills directory:

Skill	What it does
`/gws-setup`	One-shot project bootstrap — analyzes the repo, generates `gws.json`, writes Dockerfiles + deployment manifests + Helm values, deploys, validates, iterates on failure (capped at 5 attempts)
`/gws-up`	Wraps `gws up` with sanity checks and post-deploy verification
`/gws-status`	Wraps `gws status` and surfaces actionable failures
`/gws-down`	Wraps `gws down` (does not delete the cluster)
`/gws-debug`	8-step debug runbook: doctor → pod signals → logs → exec → file-sync → URL probe → fix → escalate

Re-run install.sh (or gws update) to refresh the symlinks at any time.

The flow

1. Initialize the project shell

From your project root:

gws init

Phase 2 of GetWebstack moved all setup logic out of gws init. The command now does just four things:

Prompts for a project name.
Best-effort registers the project shell with the API (works offline — the API can be wired up later by gws login + gws config import).
Writes .gws/.gitignore (and adds .gws/ to your repo .gitignore).
Appends a GWS context block to AGENTS.md and/or CLAUDE.md if those files exist — so any AI agent that opens the repo immediately knows which commands exist and what they do.

It does not generate gws.json, scan dependencies, or create a cluster. Those are the AI's job.

When gws init finishes:

✓ gws init complete.
Next: tell your AI agent `/gws-setup` to generate gws.json and deploy.
No AI? Hand-author gws.json and run `gws config import gws.json`.

2. Tell your AI agent to run `/gws-setup`

In your AI agent of choice (Claude Code, Codex, Cursor, etc.):

/gws-setup

The skill drives the entire loop:

gws schema --json              # learn the live JSON schema for gws.json
gws detect --json              # detect frameworks, ports, services
gws generate-template <fw> dockerfile
gws generate-template <fw> deployment
gws generate-helm-values <chart>
gws config validate gws.json   # local schema check
gws config import gws.json     # push to API
gws up                         # deploy
gws doctor --json              # diagnose
# → if anything fails, fix and loop (max 5 attempts)

You don't run any of those commands yourself — the AI invokes them. You read the diff, you read the final gws.json, you decide whether to approve.

3. Iterate

Edit something, re-run /gws-up, watch gws status. If a deploy breaks, run /gws-debug and the AI walks the runbook.

Configuration commands you'll see

Once gws.json exists, these commands are the contract between local disk and the API.

`gws config import`

Push the local gws.json to the API. Validates against the schema first.

gws config import              # default: ./gws.json
gws config import path/to/gws.json
gws config import --project my-slug   # if no git remote is configured

`gws config export`

Pull the API copy and write it locally (or to stdout).

gws config export              # to stdout
gws config export > gws.json   # redirect to file

`gws config diff`

Show what's different between the local file and the API. Exits non-zero when configs diverge — safe to use in CI.

gws config diff
gws config diff path/to/gws.json

`gws config validate`

Local schema check, no API round-trip. Useful as a pre-commit hook.

gws config validate
gws config validate path/to/gws.json

Helper commands the AI uses

You generally don't run these yourself, but they're available — and they're how the AI stays grounded.

Command	What it does
`gws schema [--json]`	Emits the live JSON schema for `gws.json` (zero drift — same schema the API validates against)
`gws detect [--path <dir>] [--json]`	Detects project type, framework, and port for one or more services
`gws generate-template <framework> <dockerfile\|deployment\|service> [--name X --port N]`	Emits a known-good template (single-stage Dockerfile, no `USER` directive, namespace-free deployment)
`gws generate-helm-values <mysql\|postgresql\|redis\|mongodb\|rabbitmq\|kafka> [--format yaml\|json] [--name <svc>]`	Emits Helm values for a common dev dependency, with persistence disabled
`gws doctor [--service <name>] [--artifacts-only] [--json]`	Diagnoses Dockerfile / manifest / source-code issues plus live cluster checks

Use gws <command> --help for the full option set.

Secrets

Don't put secrets in gws.json. Use gws secret:

# Recommended — interactive prompt, never visible in shell history
gws secret set DATABASE_URL --service api

# CI / AI-friendly — read from stdin
echo "$DATABASE_URL" | gws secret set DATABASE_URL --service api --stdin

Secrets are encrypted at rest in the API and injected into pods at deploy time. See gws secret for the full reference.

Manual escape hatch

If you don't have an AI agent, or you'd rather hand-author the config, the loop is:

# 1. Get the live schema for IDE autocomplete
gws schema --json > schema.json

# 2. Write gws.json by hand
$EDITOR gws.json

# 3. Validate locally (no API needed)
gws config validate gws.json

# 4. Push to API
gws config import gws.json

# 5. Deploy
gws up

Every other command (gws up, gws down, gws status, gws logs, gws exec, gws fork, gws expose, gws secret, …) works exactly the same with no AI involvement.

Troubleshooting setup

My AI agent says it can't find `/gws-setup`

gws skills install        # re-creates the symlinks

Then restart your agent so it re-scans its skills directory. The targets are ~/.claude/skills/gws-setup and ~/.agents/skills/gws-setup — both should resolve to a directory under ~/.gws/skills/.

A non-GWS file already exists at `~/.claude/skills/gws-setup`

The installer warns and skips foreign files. Inspect the file, then re-run install.sh --force-skills to overwrite.

`gws init` worked, but my AI didn't read the AGENTS.md context

Check that the marker block was written:

grep -n "gws:start" AGENTS.md CLAUDE.md

If the markers aren't there, the file probably didn't exist when you ran gws init. Create an empty AGENTS.md (or CLAUDE.md) and re-run gws init — only the content between  and  is overwritten.

I'd rather not run an AI agent at all

That's fine. Skip gws init (or run it just to register the project shell), then use the Manual escape hatch flow above.

The model​

Prerequisites​

What ships with the install​

The flow​

1. Initialize the project shell​

2. Tell your AI agent to run /gws-setup​

3. Iterate​

Configuration commands you'll see​

gws config import​

gws config export​

gws config diff​

gws config validate​

Helper commands the AI uses​

Secrets​

Manual escape hatch​

Troubleshooting setup​

My AI agent says it can't find /gws-setup​

A non-GWS file already exists at ~/.claude/skills/gws-setup​

gws init worked, but my AI didn't read the AGENTS.md context​

I'd rather not run an AI agent at all​

See also​