Skip to main content

Dev environment

A practical recipe for getting a full-stack project running locally — and for opening per-branch sandboxes that humans or AI agents can break safely.

Prerequisites​

  • gws CLI installed — see Installation
  • Docker running locally
  • A git-tracked project (mono- or multi-repo)

1. Authenticate​

gws login

Opens a browser, completes OAuth, stores the token in ~/.getwebstackrc.

2. Create the config​

Choose one path:

Path A — let an AI agent generate it (recommended):

cd your-project
gws init           # creates the project shell + registers it with the API

Then in Claude Code, GitHub Copilot CLI, OpenAI Codex CLI, Cursor, or Amp:

/gws-setup

The agent inspects your repo, generates gws.json + Dockerfiles + deployment manifests, validates against the live schema, deploys, and HTTP-probes every service.

Path B — author gws.json by hand:

cd your-project
gws init
# edit gws.json
gws config validate    # offline schema check
gws config import      # push to the API

See the gws.json overview and gws config reference.

3. Bring it up​

gws up

First run takes ~15s to provision the local cluster, then builds and deploys each service. Subsequent gws up is faster — only changed images rebuild.

4. Verify it's healthy​

gws status

You should see every service Running, every URL responding, and file-sync sessions in Watching state. For a deeper machine-readable check:

gws status --json | jq

Open a service URL — https://<service>.<project>.local.getwebstack.dev — in your browser; TLS, DNS, and ingress all work out of the box.

5. Edit code with sub-second sync​

Open any source file in your editor and save. The bidirectional file sync pushes the change into the running pod within ~0.5s. No image rebuild on save unless your service's gws.json watch rules say otherwise — see Watch Configuration.

6. Tail logs and exec into a pod​

gws logs api          # one-shot tail
gws logs -f api       # follow
gws exec api          # interactive shell inside the running pod
gws exec api -- npm test

7. Open a per-branch sandbox​

When you start a feature, create an isolated worktree + namespace so it runs side-by-side with main:

gws fork feature-payments
cd .worktrees/feature-payments
gws up -w feature-payments

You now have:

  • A separate Git worktree (independent branch, independent files)
  • A separate isolated namespace with its own database, secrets, and DNS hostname
  • A unique namespace; the same https://api.<project>.local.getwebstack.dev hostname serves it via the gws-namespace cookie (use the picker at https://<project>.local.getwebstack.dev or set the cookie programmatically with the deployment ID from gws status -w <wt> --json)

This is also the right pattern for handing work off to an AI agent — give it its own fork so it can break things without affecting main or your teammates.

8. Tear down​

gws down                          # stop the default deployment (cluster stays)
gws down -w feature-payments      # stop a worktree's deployment
gws down   -w feature-payments    # stop pods first
gws delete feature-payments       # remove the worktree

gws down is reversible — the project, generated artifacts, and registration all stay. Bring it back with gws up.

Common follow-ups​

  • Multi-repo project? All repos must share a single parent directory. The merged gws.json lives in that parent and references each repo by relative path. /gws-setup will check this for you.
  • Need a secret? gws secret set DATABASE_URL --stdin < ./db-url — see gws secret.
  • Service crashing? Use /gws-debug inside your AI agent, or run gws doctor yourself.
  • Want auto-rebuild on Dockerfile change? Add a watch rule — see Watch Configuration.

See also​