Kubb Studio
Kubb Studio is a browser workspace for generating and reviewing TypeScript code from an OpenAPI spec. It runs your Kubb plugins to produce types, clients, schemas, and hooks, shows file changes, and can publish installable snapshots from CI.
Choose where generation runs:
| Option | Use it for |
|---|---|
| Shared sandbox | Try Studio with a spec you provide in the browser, without installing anything. |
kubb studio | Work on a local project with its existing spec, config, and plugin versions. |
| Docker agent | Keep an agent connected on your infrastructure for a team. |
With a CLI or Docker agent, generation runs in your environment. Studio receives plugin settings, progress, and generated file paths. A local spec is not uploaded. Reading generated file contents or changing local files requires the agent's permission. The shared sandbox runs outside your environment, so use it with a spec you are comfortable providing there.
From spec to production.
Connect a local project
Run the command from a project with Kubb installed and a kubb.config.ts:
kubb studioThe first run opens Studio to approve the machine. After approval, keep the command running and select the connected agent in Studio. Generate from the browser to see progress and the file tree. Grant --allow-read to view file contents and diffs.
The CLI asks which permissions to grant for this project and remembers your answers. With no permissions granted, generation uses memory and Studio sees file paths and progress. It does not write generated files or edit your config. For example, to review generated files and write them to disk:
kubb studio --allow-read --allow-writeUse --allow-config-edit to save plugin option changes to kubb.config.ts. Use --allow-exec to run the configured formatter, linter, and output.postGenerate commands. See the kubb studio reference for all flags and actions.
Run an agent without a terminal session
For a local project, detach the same connection:
kubb studio start --allow-readkubb studio statuskubb studio stopThe first start resolves pairing and permissions in the terminal. Later starts reuse them. The worker stays connected when the terminal closes and retries temporary connection failures. Restart it explicitly after a crash or reboot. If status says authentication required, run kubb studio login, then start it again. logout stops the worker and forgets its token.
For a persistent team connection, run the Docker agent. In CI or without a TTY, use an existing KUBB_AGENT_TOKEN and pass the required permission flags; headless runs do not ask permission questions.
Snapshot from CI
kubb studio snapshot generates an installable package on a CI runner, publishes the tarball to Studio, and exits. It uses an organization CI API key in KUBB_TOKEN, not an agent token:
kubb studio snapshotThe command detects GitHub Actions, GitLab CI, Bitbucket Pipelines, and CircleCI. For another CI provider, pass a stable --id. Use --json when a later step needs the tarball URL:
kubb studio snapshot --json | jq -r '.url'A snapshot reports which generated files it added, changed, and removed:
| JSON field | Compared with |
|---|---|
changes | The previous snapshot on the same pull request or branch |
branchChanges | The latest snapshot of a GitHub pull request's base branch or a GitLab merge request's target branch. Run the command on that branch too |
On another CI provider, give the base branch's runs a stable --id too, and pass it as --base-id on a pull request:
kubb studio snapshot --id jenkins:api:main # on mainkubb studio snapshot --id jenkins:api:pr-12 --base-id jenkins:api:main # on a pull requestFollow the GitHub Actions or GitLab CI guide for a complete workflow. Installing the tarball requires a separate registry API key.
See also
kubb studiocommand: actions, flags, and environment variables- Configuration: the config a connected project uses