Docs / service setup

Make a repository runnable with the smallest contract.

A connected repository needs a valid spinnery.yml on its default branch before Spinnery can start it as a workspace service. Docker Compose still owns the runtime; the manifest only fills in what Spinnery cannot safely infer.

Set up services with spin up Use the prompt yourself Download the Agent Skill

repository readinessdefault branch

checkinginspecting repository

setup_requiredspinnery.yml missing

validatespin validate

readyvalid manifest merged

When it is needed

Connected does not mean runnable yet.

Repositories without a manifest remain visible so setup is not a dead end. Spinnery blocks workspace creation until the default branch contains a valid contract instead of discovering an ambiguous port or missing input halfway through startup.

checkingConnected

Spinnery is still inspecting the repository.

The repository can appear during onboarding while Spinnery checks its default branch. Wait for inspection before assuming setup is missing.

manifest_missingSetup required

The repository has no spinnery.yml yet.

It stays visible for setup, but workspace creation is blocked until a valid manifest reaches the default branch—normally through a PR created in your own coding-agent workflow.

valid manifestReady

The default branch has a valid contract.

The repository can be used as a workspace service. Each required input still needs a same-name output from another selected service or an explicit project binding.

Fast path / spin up

Choose the services. Spinnery handles the setup handoff.

spin up keeps every project service selectable and shows whether each one is ready, still checking, missing setup, or invalid. A service that is still checking pauses creation until you rerun after inspection finishes. If your selection includes a service that needs setup or has an invalid contract, Spinnery asks how you want to prepare it.

spin upservice readiness

✓APIready

✓Websetup required

✓Workerinvalid

How do you want to set up the selected services?

Use Codex (temporarily unavailable)

› Use Claude Code

Set up manually

Local prerequisites

Install and authenticate the GitHub CLI (gh) so it can clone, push a branch, and open a PR. Install and authenticate the Claude Code CLI (claude) for assisted setup. Codex remains available for normal workspace work and the manual skill-guided flow, but its automated setup choice is disabled until it can enforce the required config-only tool boundary.

Use Codex

Temporarily unavailable for assisted setup: current Codex releases cannot enforce the config-only tool boundary this automation requires. You can still use the Spinnery skill from your own Codex session.

Use Claude Code

Runs your authenticated local Claude Code CLI with the same locked-down, focused setup brief. When no tracked Compose file exists, it may also create the dedicated compose.spinnery.yml runtime file.

Set up manually

Prints the repositories and this guide so you can prepare and open each PR yourself.

Each repository gets its own isolated checkout, so setup never edits your current working tree.
Repository jobs run with bounded concurrency. The agent can inspect the checkout and write only the declared Spinnery manifests plus compose.spinnery.yml when no tracked Compose file exists; it cannot use Git, GitHub, the web, or your general shell environment.
Spinnery independently rejects unrelated edits, checks each manifest and its Compose service references without executing repository code or loading external Compose files, creates the focused commit, pushes the setup branch, opens and verifies one non-draft PR, and prints GitHub’s canonical PR URL. It never merges.
Run the full Docker-backed spin validate command in CI or during review before merging; the assisted path deliberately uses a narrower no-execution check for an untrusted checkout.

Missing Compose is handled explicitly

When the repository already tracks a Compose file, assisted setup treats it as read-only. When none exists, the agent can create only compose.spinnery.yml alongside the requested manifests, using checked-in Dockerfile, runtime, package-manager, command, and port evidence. Spinnery rejects any other changed path.

Review remains the gate

Workspace creation stops here until every setup PR is merged into its repository's default branch. Review and merge the PRs, then rerun spin up. Spinnery will recheck the selected services and continue once they are ready.

Start small

Do not repeat Docker Compose.

If the repository already has docker-compose.yml and needs no browser URL, the two-line manifest is enough. Add a preview only when Spinnery must publish a Compose service through a dev URL.

If no Compose file exists, add a focused compose.spinnery.yml based only on checked-in runtime evidence, then point compose.file at it. Keep this runtime file reviewable and free of secret values.

smallest valid fileCompose owns everything

version: 1
compose: {}

browser serviceone published preview

version: 1

compose:
  file: docker-compose.yml
  previews:
    - service: web
      port: 5173
      hmr: true

default_preview: web

Keep evidence in its native file.

Compose owns build contexts, commands, service dependencies, health checks, volumes, and container environment. Dockerfiles own image construction. Package manifests own scripts and dependency managers. Add only Spinnery-specific previews, contracts, setup, tests, or CLI entrypoints to spinnery.yml.

Author version: 1. The CLI temporarily accepts an existing version: 2 manifest only for compatibility and normalizes it to version 1; do not introduce version 2 in new or edited files.

Cross-service wiring

Match names for the zero-config path.

A provider exposes an output. A consumer declares an input and maps it to the environment variable its code already reads. When both use the same name, Spinnery wires selected workspace services automatically. Use an explicit project binding only to override or disambiguate the provider; neither repository names the other repository or embeds a workspace URL.

API repositorypublishes api_url

version: 1

compose:
  previews:
    - service: api
      port: 8080

default_preview: api

outputs:
  api_url:
    from: service.url

Web repositoryconsumes api_url

version: 1

compose:
  previews:
    - service: web
      port: 5173
      hmr: true

default_preview: web

inputs:
  api_url:
    required: true

environment:
  VITE_API_URL:
    from: input.api_url

Backend.output.api_urlsame-name match / explicit bindingWeb.input.api_url → VITE_API_URL

Development environment

Require what development actually uses.

Start from checked-in source, Compose, and safe example templates. If the repository already provides a local mode that replaces a production integration, set that mode explicitly and leave the unused production credentials out. Never invent an authentication bypass. A secret is required by default; use required: false only when the service boots and its normal development workflow works without that integration.

development behaviorsafe default + optional integration

version: 1
compose: {}

environment:
  LOCAL_DEVELOPMENT_MODE:
    value: true
  OPTIONAL_PROVIDER_TOKEN:
    secret: provider-token
    required: false

Example templates are evidence, not credentials.

Assisted setup extracts variable names only from tracked .env.development. Example, sample, and template files may additionally contribute mechanically allowlisted placeholder or development defaults. Credential-looking values are always redacted before the coding agent sees them. Raw file contents are never passed through, and production or untracked environment files remain excluded.

Spinnery Settings shows development defaults, managed resources, project connections, required secrets, and optional integrations separately so users can see what is automatic.

Validate locally

Catch setup errors before the PR.

Run spin validate at the repository root. It reads ./spinnery.yml by default, needs no login or workspace, and discovers the enclosing Git checkout when the manifest is nested. Compose paths stay relative to that repository root, which matches the production runtime. Pass a manifest file or repository directory explicitly; outside Git, run from the repository root or add --repository-root <path>. Add --jsonfor machine-readable output. It requires Docker Compose v2, and failures are bounded at 30 seconds and summarized without printing resolved environment values.

spin validatespin validate ./path/to/repositoryspin validate ./spinnery.yml --json

What the command checks

spinnery.yml is valid YAML with the supported mapping shape, strict boolean fields, and no retired or cross-repository runtime keys.
compose.file exists relative to the repository root, and Docker Compose v2 can resolve it with docker compose config --services.
Every declared preview names a service in that resolved Compose model, preview names are unique, ports are in range, and default_preview names a declared preview when present.
Every input.* reference has a matching inputs declaration, and each environment entry has exactly one literal, reference, or secret-name source.

What still needs repository review

Static validation cannot prove application behavior, secret safety, or project-level bindings. If Docker Compose v2 or spin validate is unavailable, report validation as blocked and perform both the automated and review checks manually instead of claiming success.

Each preview port is the application container port, and hmr is enabled only when the dev server actually supports it.
A single preview becomes the default automatically. When a service exposes multiple previews, default_preview names the primary app used by its bare preview URL and service.url.
Every required cross-service input has a same-name output from another selected service or an explicit project binding; a local repository cannot prove workspace-level wiring.
Environment entries contain literals, supported runtime references, or secret references. Do not read untracked .env or credential files; use checked-in examples and never copy secret values.
A referenced variable is not automatically required. Apply documented safe development defaults first; declare only credentials needed for the normal development workflow, and mark genuinely optional integration secrets required: false.
Optional setup and test commands come from repository evidence and run from the checkout; do not invent commands because a framework often uses them.

Use any coding agent

Paste one prompt. Install nothing.

This prompt gives an agent the same evidence-first workflow as the downloadable skill. It asks for a diff, keeps secrets out of the file, and leaves commits and pull requests under your control.

Download configure-spinnery.zip Read SKILL.md Read the offline reference

Codex

Unzip the downloaded skill so its folder is ~/.codex/skills/configure-spinnery/.

mkdir -p ~/.codex/skills && unzip -o configure-spinnery.zip -d ~/.codex/skills

Claude Code

Unzip the same archive so its folder is ~/.claude/skills/configure-spinnery/.

mkdir -p ~/.claude/skills && unzip -o configure-spinnery.zip -d ~/.claude/skills

copy into any coding agentno install

Configure this repository for Spinnery.

Read https://spinnery.dev/docs/service-setup first. Inspect the repository's Docker Compose files, Dockerfiles, package manifests, lockfiles, and env example files; do not guess when the repository already provides the answer.

Create or update only the smallest valid spinnery.yml needed for this repository. Reuse a tracked Compose file without editing it. If none exists, create only compose.spinnery.yml and derive it from checked-in Dockerfile, runtime, package-manager, command, and port evidence. Keep runtime facts in Docker Compose. Configure the repository's documented development mode, including safe checked-in local switches that replace production integrations. Do not require production credentials for an integration disabled in that development mode. Declare cross-service needs as input mappings and map them to environment variables with from: input.<name>; expose values from this service as outputs. Never write secret values.

Run `spin validate` from the repository root. It must verify the Compose file and preview service names as well as the manifest. If Docker Compose v2 or the command is unavailable, report validation as blocked and perform the manual checks from the docs; do not call the repository ready. Show me the validation result and the final diff. Do not commit, push, or open a pull request unless I explicitly ask.