SpinneryDocsDocs / Getting started
The first-time flow is concrete: sign in through Auth0, select GitHub App repositories, prepare each repo with a reviewable spinnery.yml, create the project services and bindings, install the CLI, run spin login, run spin up, share a signed dev link on dev.spinnery.dev, then let idle sleep stop runtime billing.
GitHub App connected for acme/scheduler
PR opened: add spinnery.yml
Project: Scheduler; services: Web, Backend
Bindings: web -> Web, /api -> Backend
$npm install -g spinnery
$spin login
$spin up
dev link: signed web--signed-links--acme.dev.spinnery.dev
billing: idle sleep stops runtime meter
Before the commands
The first run is easier to reason about when every step maps to a product surface: hosted workspace, shared shell, awake runtime, signed dev link, and awake-only billing.
workspace = repo + branch + servicesSpinnery turns a reviewed repo contract into a hosted branch workspace so the workspace, not the laptop, is the shared unit for checkout, tools, services, and readiness state.
spin upDevelopers, Claude, and Codex share one terminal context with Git, tmux, editors, tests, logs, and workspace metadata before service boot blocks the handoff.
wake on service workWeb, /api, workers, checks, and resources wake only when service work needs them, so the runtime can be asleep while the shell remains useful.
dev.spinnery.devReviewers open the app surface through a signed dev.spinnery.dev browser session for web, same-origin /api, assets, and realtime traffic. Browser review uses the signed app session, not SSH or raw hosts.
awake runtime onlyThe runtime meter starts for awake service capacity and stops after idle sleep; shell access, repo state, and product policy remain available.
CLI happy path
The first-release docs should show the same path users run: sign the CLI into the Organization, open the Project Workspace, attach to the Shell, watch Services and Resources wake the Runtime, then create a signed dev link when the handoff is ready.
$spin login
Organization: Acme / role: Developer
Access Policy: workspace open allowed; signed dev link allowed
$spin up
Project: Scheduler / Workspace: signed-links
Shell: ready with Git, tmux, Claude, Codex
Runtime: waking Services Web and Backend
Resources: postgres ready; cache waking; storage blocked by policy
Next: spin share when readiness is green
spin loginThe CLI opens Auth0, then Spinnery resolves the Organization, product role, GitHub App scope, and Access Policy for workspace actions.
Organization / Project / Workspacespin up selects the Organization, Project, and branch Workspace before attaching to any Shell or waking any Runtime capacity.
Shell readyThe Shell opens first with Git, tmux, Claude, Codex, logs, and the repo checkout. This baseline does not start Runtime billing.
Services / ResourcesServices and declared Resources report ready, waking, or blocked as web, /api, workers, checks, database, cache, mail, or storage work wakes the Runtime.
signed dev linkUse spin share only after readiness is clear. The signed dev link covers web, same-origin /api, assets, and realtime traffic without granting SSH, logs, secrets, root, or runtime admin.
First-release path
Use this as the short first-run checklist: Auth0/GitHub onboarding, GitHub App selected repositories, per-repo spinnery.yml, spin login, spin up, instant shell access, signed dev links on dev.spinnery.dev, runtime sleep and billing, and the isolation rules that keep reviewer access narrow.
Auth0 org + GitHub AppSign in through Auth0, choose the Spinnery organization, and install the GitHub App only on the repositories Spinnery should prepare.
spinnery prepare-prOpen focused setup PRs so repo owners review the workspace contract before branch workspaces depend on it.
service contractCommit Compose previews, inputs, outputs, environment mappings, setup commands, tests, and CLI helpers beside each repo.
spin loginStart the CLI session through Auth0 and confirm the same organization, role, and GitHub installation scope used in onboarding.
spin upSelect the prepared project and branch, then attach to the hosted workspace without raw VM hostnames or cloud credentials.
shell ready / runtime wakingGit, tmux, Claude, Codex, logs, and the branch checkout are ready first while web, /api, workers, resources, and checks wake behind them.
spin shareShare a signed service--workspace--org.dev.spinnery.dev browser session for web, same-origin /api, assets, and realtime traffic.
spinnery sleepSigned traffic, tests, workers, and jobs can wake the selected runtime size; idle sleep stops the runtime meter while the shell remains available.
one-org-per-VMShell and runtime VMs stay inside one customer organization, and signed dev links never grant SSH, logs, secrets, root, runtime admin, or private consoles.
Auth0: acme developer authorized
GitHub App: acme/web and acme/api selected
PRs: spinnery.yml opened per repo
$spin login
$spin up signed-links
shell: ready immediately
runtime: waking web, /api, workers, resources, checks
dev link: signed web--signed-links--acme.dev.spinnery.dev
sleep: spinnery sleep stops runtime billing
security: one-org-per-VM; SSH/logs/secrets blocked
Hosted workspace model
A first user should understand exactly what gets created and what stays separate: Auth0 login, the repo-owned contract in spinnery.yml, an organization-exclusive shell VM, awake-only runtime services, and the signed dev link used for browser review.
$spin login
Auth0: acme authorized as developer
$spin up acme/scheduler --branch signed-links
config: spinnery.yml loaded from repository
shell: ready on org-exclusive VM
runtime: asleep until web, /api, workers, or checks wake Small
dev link: signed web--signed-links--acme.dev.spinnery.dev
billing: shell included; runtime awake-only
spin login -> Auth0spin login opens Auth0, then Spinnery checks organization membership, product role, GitHub App scope, and whether that user can open or share the selected workspace.
spinnery.ymlThe branch workspace uses the committed spinnery.yml for Compose previews, cross-service contracts, environment mappings, setup commands, and tests instead of hidden setup notes.
org-exclusive shellThe shell VM belongs to one customer organization and opens with Git, tmux, Claude, Codex, logs, and the branch checkout before service runtime work has to finish.
awake-only servicesWeb, /api, workers, checks, and declared resources wake the selected runtime size only when service work needs CPU, memory, or ports; idle sleep stops the runtime meter.
signed dev.spinnery.devThe signed dev link gates web, same-origin /api, assets, and realtime traffic for one service, workspace, organization, and expiration while SSH, logs, secrets, root, and runtime admin stay closed.
First workspace preflight
A successful first run depends on more than the CLI command. Before spin up, make sure repo setup, access policy, resource modes, and runtime cost posture have named owners.
spinnery.yml approvalA repo owner reviews the Compose preview, inputs, outputs, environment mappings, setup commands, and tests before the setup PR merges.
The workspace contract should be owned by the team that owns the code.Auth0 + rolesAn organization admin confirms Auth0 login, Spinnery roles, GitHub App installation scope, and who can issue signed dev links.
Identity is not enough; product roles decide workspace actions.resource modesEach database, cache, bucket, mail sink, queue, or disabled integration has an owner, mode, readiness expectation, and cleanup policy.
Resource decisions should not be discovered during reviewer handoff.size + sleep + capThe first workspace names its runtime size, idle sleep behavior, cap posture, and separate customer-cloud costs before the runtime wakes.
Awake-only billing is useful only when the boundary is visible.Owner map
Getting started should not hide ownership inside platform setup. Before the first workspace is shared, name who owns repository scope, repo contract review, product access, CLI handoff, reviewer access, and runtime cost posture.
selected repository installInstalls the Spinnery GitHub App only on the repositories that should receive setup PRs and branch workspaces.
Repository scope is narrow before Spinnery reads code.spinnery.yml PR reviewReviews Compose previews, inputs and outputs, environment and secret mappings, setup and test groups, and cloud CLI entrypoints before the workspace recipe merges.
The hosted workspace runs a reviewed repo contract.Auth0 roles + optional TailscaleConfirms Auth0 organization membership, Spinnery product roles, signed-link issuance rights, root policy, and whether private routes need Tailscale.
Access is product-scoped before shell or reviewer handoff.spin login && spin upSigns into the organization, opens the branch workspace shell, watches runtime/resource readiness, and keeps work inside the shared terminal context.
The shell opens first while runtime readiness catches up.spin shareReceives the signed browser session created by spin share for web, same-origin /api, assets, and realtime traffic instead of raw hosts, SSH, logs, secrets, or runtime admin.
Review access stays app-scoped and revocable.runtime size + idle sleep + capConfirms the first runtime size, cap posture, idle-sleep rule, and separate customer-cloud resource costs before long tests or agent jobs wake services.
Cost follows awake service work, not shell existence.Hosted MVP milestone
The milestone is the hosted path a first customer or reviewer can follow: run spin up, land in a shell immediately, let runtime services wake in the background, share a signed dev.spinnery.dev URL, and explain that runtime billing applies only while the runtime is awake.
CLI entry pointAfter GitHub, repo setup, project services, and CLI login are ready, spin up selects the hosted project and branch workspace instead of asking users to rebuild local setup.
shell firstThe shell attaches first with Git, tmux, Claude, Codex, repo checkout, and logs ready while service processes report readiness separately.
wake as neededWeb, /api, workers, resources, or checks wake in the background when runtime work needs CPU, memory, ports, or declared service dependencies.
spin shareThe reviewer opens the signed dev.spinnery.dev URL created by spin share for the service/workspace/org host, and the signed session gates web, /api, assets, and realtime traffic.
meter boundaryOpening a signed dev URL can wake the runtime; idle sleep stops the runtime meter while the hosted shell, repo state, and workspace metadata remain available.
first milestoneThe hosted path is the first milestone: spin up, instant shell attach, background runtime wake, signed dev.spinnery.dev handoff, and awake-only runtime billing.
contract examplesLocal spinnery.yml examples and setup PRs describe the contract that the hosted workspace will run; they are not the hosted shell, gateway, runtime meter, or billing system by themselves.
do not overclaimKeep expanded fleet controls, automated caps, invoices, compliance programs, and production operations language clearly planned until those controls are live; this page describes the current hosted workspace path.
Workspace access contract
Getting started should leave one clear handoff: spin upopens the workspace shell, the dev URL follows the service/workspace/org shape, spin share creates the reviewer link, and a signed session gates app traffic before the runtime wakes.
$spin up signed-links
shell: ready with Git, tmux, Claude, Codex
runtime: asleep until web, /api, workers, or checks need it
$spin share signed-links --service web --service api --expires-in 2h
handoff: signed dev.spinnery.dev URL -> browser session
dev: https://web--signed-links--acme.dev.spinnery.dev
session: signed service/workspace/org, expires 2h
billing: shell baseline included; runtime meter awake-only
spin upDevelopers and agents enter through the CLI, select the organization, project, repo workspace, and branch, then attach to the shared shell without passing around raw VM hostnames.
One command is the handoff handle for Git, tmux, Claude, Codex, logs, and readiness.<service>--<workspace>--<org>.dev.spinnery.devSpinnery calls this a signed dev.spinnery.dev URL in product handoffs; the dev.spinnery.dev host keeps the service, workspace, and organization visible for review while DNS stays behind one Spinnery wildcard.
Use a signed dev link for the actual browser handoff, not a raw runtime address.spin shareRun spin share with the allowed services and expiration. Signed links cover the app surface for web, same-origin /api, assets, and realtime routes while SSH, logs, secrets, private consoles, and runtime admin remain closed.
The host shape is not the permission; the signed session is.shell included / runtime awake-onlyThe shell baseline stays ready for repo work. Web, API, workers, tests, and resources wake the runtime meter only when service work needs them.
Auto-sleep stops runtime billing without deleting the workspace.Sign in
Auth0 loginStart in the Spinnery web app. Auth0 handles signup and login, then Spinnery applies organization membership and product roles before any workspace can open.
Use the same organization later in the CLI with spin login.Connect GitHub
GitHub App selected reposInstall the Spinnery GitHub App for the GitHub organization and choose only the repositories Spinnery should inspect, prepare, and open branch workspaces for.
Repository selection is the setup boundary; broad personal access tokens are not required.Prepare repos
per-repo spinnery.ymlEach selected repo gets its own spinnery.yml contract for Compose previews, inputs, outputs, environment mappings, setup commands, and tests.
Repo owners review and merge the contract before branch workspaces depend on it.Create project
Project -> services -> bindingsAdd prepared repos as project services, then bind product routes and resources: Web owns the browser surface, Backend owns /api, and declared resources attach to consuming services.
Project bindings turn reviewed repo contracts into a product-shaped workspace.Install CLI
npm install -g spinneryThe CLI is the normal workspace handoff for developers and agents. Install it in the terminal environment that should attach to Spinnery workspaces.
Verify the install with spinnery --version before first login.spin login
spin loginspin login opens the Auth0 product sign-in flow and returns a local CLI session tied to the same Spinnery organization, role, and GitHub App installation scope.
The CLI should show the expected organization before opening a workspace.spin up
spin upRun spin up, choose the prepared project and branch, then land in the hosted shell with Git, tmux, Claude, Codex, logs, and the branch checkout ready.
Shell first; runtime readiness is reported separately.Runtime wakes
background runtimeWeb, /api, workers, resources, and checks wake only when service work needs CPU, memory, ports, or declared dependencies.
Readiness should say ready, waking, or blocked before a reviewer gets the link.Share dev link
spin shareUse spin share to create a signed dev link on dev.spinnery.dev, such as web--signed-links--acme.dev.spinnery.dev, for web, same-origin /api, assets, and realtime traffic.
The signed dev link is the reviewer handoff; it is not SSH, logs, secrets, root, private consoles, or runtime admin.Sleep and billing
spinnery sleep / idle sleepSigned dev traffic, tests, workers, and service commands can wake the selected runtime size; idle sleep or spinnery sleep stops runtime billing while shell and workspace metadata remain available.
Cost follows awake runtime work, not workspace existence.First workspace trust receipt
The first workspace handoff should make access, isolation, and cost plain in product language before anyone opens the app dev URL.
*.dev.spinnery.devThe dev URL follows the product host shape <service>--<workspace>--<org>.dev.spinnery.dev through one Spinnery wildcard, not raw VM hosts or per-branch DNS.
Use the signed dev link for the browser handoff.service + workspace + org + expirationReviewer access starts as one signed browser session for one service, workspace, organization, and expiration before app traffic reaches the runtime.
Web, /api, assets, and realtime paths share the session.one-org-per-VMShell and runtime VMs stay inside one customer organization, so cross-customer code, dev traffic, and logs never co-tenant.
Branch workspaces can share only their owning org boundary.runtime-awake onlyOpening the signed link may wake web, /api, workers, or checks on the runtime meter; idle sleep stops billing while the shell baseline remains ready.
Cost follows awake service work, not the existence of a workspace.Resource readiness
After spin up, run spinnery workspace resourcesto check declared resources by reference, readiness, and consumer service. The handoff should explain what is ready, waking, or blocked without exposing credentials or provider internals.
$spinnery workspace resources signed-links
resource.postgres.url ready for api
resource.cache.url waking for api
resource.storage.bucket blocked for web: disabled by workspace policy
masked: postgres://***@resource.postgres/app
resource.postgres.urlReady means the workspace mode resolved and the consuming service can receive the masked reference during runtime wake.
resource.cache.urlWaking is a reason to wait before handing a reviewer the link, then run the command again after provisioning or service wake completes.
resource.storage.bucketBlocked output should name the resource and consumer service without printing credentials, provider IDs, internal hosts, or private console URLs.
First workspace handoff
A launch-ready first workspace should be easy to paste into a pull request or support thread: the workspace shell, the signed dev URL, what is ready, and which operational surfaces remain private.
<service>--<workspace>--<org>.dev.spinnery.devspin up signed-linksThe handoff names the workspace, Git branch, tmux session, logs, and shell status before service runtime work starts blocking review.
web--signed-links--acme.dev.spinnery.devThe public host follows <service>--<workspace>--<org>.dev.spinnery.dev, with one browser session for web, /api, assets, and realtime routes.
web ready; api wakingThe first workspace handoff should say which services, resources, and checks are ready, still waking, or blocked before a reviewer opens the app.
ssh / logs / secrets blockedSigned dev URLs stay app-scoped. SSH, raw logs, secrets, root policy, private consoles, and runtime admin remain behind authenticated workspace access.
Setup contract
The per-repo PR points to the service's Compose model and declares how Spinnery publishes and connects it. The project binding says where that service belongs in the product workspace, such as routing web to Web and /api to Backend.
version: 1
compose:
previews:
- service: api
port: 8080
default_preview: api
outputs:
api_url:
from: service.urlProject bindings
web + /apiWeb + BackendFirst-run checks
A first workspace should be runnable from product concepts and reviewed repo contracts, without passing around raw VM hostnames, cloud credentials, or shared secrets.