Projects and repositories
A project is a repository and the shape of the workspace that opens it. The shape is the image, the preset and the network policies. The project also names the ref a workspace opens at.
The guest of a workspace made from a project clones the repository into
/workspace/<repository name> and runs the repository’s own .spin.yaml tasks there.
Making and sharing a project
Section titled “Making and sharing a project”Projects belong to the installation. Whoever makes one is its admin. An installation can keep
making projects to its administrators, with project_creation in the
configuration file.
spin project create --name <name> --repository <https-url> --ref <branch> --preset <preset>spin project listEverybody signed in sees a project until its admins share it with only some people and teams. A share is saved whole: what you do not name is no longer shared. Admins always see the project.
spin project share <slug> --team <team> --admin <user-id>spin project share <slug> --everyone --admin <user-id>Whoever sees a project opens workspaces from it, in a team of theirs. See spin project.
Opening from a URL
Section titled “Opening from a URL”You can open a repository, a branch, a commit or a pull request from its URL:
on the dashboard’s /launch page, or from the terminal with spin open.
spin open https://github.com/<owner>/<repository>spin open https://github.com/<owner>/<repository>/tree/<branch>spin open https://github.com/<owner>/<repository>/commit/<sha>spin open https://github.com/<owner>/<repository>/pull/<n>The project is found by its repository among the projects you see. When more than one has it,
--project says which. A repository no project has is one to make a project of first.
A plain repository URL opens at the project’s ref. A workspace can also be
opened at a commit or at a pull request, which is checked out as pr-<n>.
The workspace is made in --team, or in your personal team, and sized by the project’s preset
unless --preset names another. spin open ends in spin ssh, which logs in with a key you
added (spin ssh-key add), unless you pass --no-connect.
To open a project by its slug instead of a URL:
spin workspace create --project <slug> --ref <branch-or-tag>Prebuilds
Section titled “Prebuilds”A project can name refs to prebuild. Each one is built as it moves, and the result is a snapshot. A workspace that opens the project at that ref is cloned from its prebuild, so it starts from what the build already made. The builds run as the person who named the refs.
spin project create --name <name> --repository <https-url> --ref <branch> --prebuild-ref <branch>spin project prebuilds <slug>spin project prebuild <slug> <ref>spin project prebuilds lists each build of a ref at a commit and what became of it.
spin project prebuild builds a ref now, at the commit the forge says it is at. A commit whose
build failed is built again. Only the project’s admins can run it.
An installation can retire a ready prebuild that no workspace has opened for a while. The project’s next open then starts from the image. See Snapshots.
Your GitHub account
Section titled “Your GitHub account”A private repository on GitHub is cloned with the workspace owner’s own account. You connect your GitHub account once, and it clones and pushes your workspaces’ private repositories. The control plane keeps the token. The host your workspace runs on sets it on the requests a network policy brokers to GitHub, so no workspace’s disk holds it.
Connect in the dashboard, under Settings → Git, or from the CLI, with a code you enter on GitHub’s page:
spin git connectspin git listEither way, GitHub asks you to authorize the installation’s app. The token never reaches your
machine. spin git connect needs “Enable Device Flow” checked on the installation’s GitHub App.
To choose a repository for a project, list the repositories your account reaches, or only those whose name has a query in it:
spin git reposspin git repos <query>spin git disconnect github forgets the account and has GitHub revoke the token. See
spin git.
Installations run Spinbox v20261027.01; the reference is generated from spin v20261114.01 (51f7e0dea). This page as Markdown, for a model or a terminal.

