Overview

gws.json is the single declarative file that describes a GetWebstack project: its services, their build inputs, ports, hostnames, secrets, watch rules, and profiles. Every CLI command — gws up, gws fork, gws rebuild, gws status — reads from it.

Edit gws.json with AI, not by hand

The recommended way to create or change gws.json is to ask an AI agent (Claude Code, GitHub Copilot CLI, OpenAI Codex CLI, Cursor, Amp, …) to run /gws-setup. The skill reads the live JSON schema, makes the edit, validates it, and runs gws config import for you — so you never have to memorize field names or wrestle with overlay rules.

/gws-setup add an `api` service on port 3000 with a watch rule that
rebuilds the image when Dockerfile or package.json change

Hand-editing still works (and is documented throughout this section), but treat it as the fallback path — mostly useful for tiny tweaks or when you want to learn the schema. For anything non-trivial, let the agent do it.

Top-level structure

A gws.json file is a single JSON object with a small set of top-level fields:

{
  "name": "my-project",          // project identifier (matches the API record)
  "version": "1.0.0",            // gws schema version

  "services": [                   // the heart of the file — one entry per deployable unit
    { "name": "api",  "path": "./api",      "port": 3000 },
    { "name": "web",  "path": "./frontend", "port": 80, "subdomain": "app" }
  ],

  "registry": {                   // where built images are stored
    "mode": "in-cluster"          // "local" | "in-cluster" | "remote"
  },

  "provision": {                  // optional: per-environment cluster targets
    "environments": {
      "local":  { "type": "k3d",      "default": true },
      "remote": { "type": "remote" }
    }
  },

  "profiles": {                   // optional: named overlays that adjust services per scenario
    "ci":  { "services": [{ "name": "*", "fileSync": false }] },
    "e2e": { "services": [{ "name": "*", "fileSync": false, "watch": null }] }
  }
}

Field	Required?	Purpose
name	yes	Project identifier. Matches the project record on the GetWebstack API.
version	yes	gws.json schema version (used for migrations — not your app's version).
services	yes	Array of services to build and deploy. See Services.
registry	no	Where built images live (local, in-cluster, or remote).
provision.environments	no	Cluster targets you can switch between with gws up --env <name>.
profiles	no	Named overlays that override service fields per scenario. See Profiles.

The authoritative schema lives in source: GwsJsonModel. You can fetch the live JSON Schema at any time with gws schema --json.

Lifecycle

1. Created locally by gws init. The CLI inspects your repo, asks any necessary questions, and writes gws.json at the project root (or, for multi-repo projects, in the shared parent directory).
2. Validated against the live JSON schema returned by gws schema --json. Anything the schema rejects never reaches the API.
3. Stored in the API when gws init finishes, or any time you run gws config import. The API copy is the canonical version that gws up, the dashboard, and CI all read from.
4. Round-tripped with gws config: export to pull the API copy down, diff to spot drift, import to push local edits back.

Query the API copy

Pull the canonical gws.json for the current project from the API:

gws config export

Writes the full effective config to stdout. Pipe it where you need it:

gws config export > gws.json          # snapshot to disk
gws config export | less              # inspect interactively
gws config export | jq '.services'    # poke at one section

To check whether your local copy matches the API:

gws config diff

diff exits non-zero on any difference, which makes it convenient for CI guards.

Import a new gws.json

After editing gws.json — ideally via /gws-setup, or by hand for small tweaks — push it to the API:

gws config import

The CLI validates against the live schema first and refuses to push anything invalid. The next gws up (yours or a teammate's) picks up the new config.

You can also validate without touching the API:

gws config validate

This is offline and requires no auth — useful in pre-commit hooks.

What's in this section

• Services — every supported field on a service entry, with worked examples.
• Profiles — named overlays that override service fields per scenario (ci, e2e, staging).
• Watch Configuration — file-watch rules inside gws.json that trigger automatic rebuilds and re-applies during development.

See also

• gws init — creates gws.json and registers it with the API
• gws config — the full import/export/diff/validate reference
• gws schema — emits the live JSON schema gws.json is validated against