Teams, projects, and roles

This page covers using hyperspool.dev with a team: signing in, organizations and projects, and roles. To run everything locally against spool dev, see getting started and the tour.

The shape

Two nouns hold everything:

• An org is your team’s tenant. It owns projects, members, agents, and its own encrypted secrets. Billing and isolation are per org: one org can never see another’s runs, secrets, or members.
• A project is a workspace inside an org, usually one per service or repo. Runs, secrets, schedules, the event bus, webhooks and connected repos all live at the project level. A run id spells out both: myorg:api:run-3xKq….

You belong to one or more orgs, with a role in each (below), plus optional grants on individual projects.

Signing in

Sign-in at hyperspool.dev is by invitation for now: someone adds your email to an org, or you were invited to the service. An address nobody has invited is sent back to the sign-in page with a note saying so. If you are signed in but belong to no org, the console offers to create one (next section).

A new login starts with the invite mail. Its link, valid for 7 days, confirms the address and lets you choose a password, a passkey or GitHub or Google sign-in. Until you have followed it, signing in with GitHub or Google is not linked to the invited address. If the link ran out or the mail never came, an admin adding you again sends a new one.

The first time you open the console, and again whenever the terms change, it asks you to accept the terms of service and the privacy notice. Until you have accepted once, the API refuses your tokens too, with a message that says so. If you only use the CLI, spool terms accept shows the links and accepts them from the terminal.

For the CLI, create a personal access token under Settings > Tokens, then:

spool login https://api.hyperspool.dev

It prompts for the token (or reads it from stdin, for scripts), resolves your org and project from your memberships (--scope acme/web picks one), and saves a context for it in config.toml. It needs at least one org to pick, so create yours in the console first if you have none. From then on every command targets that context; override per command with --org / --project, or switch with spool org use and spool project use. spool context get shows the current target.

Creating an org

Any signed-in user can create an org of their own: + New organization in the console’s org switcher, or from the CLI:

spool org create acme --name "Acme"
spool project use acme/default

You become its owner. It starts on the Free plan with one project, default, and you can add more from there. Slugs use lowercase letters, digits and hyphens, can’t be changed later, and a few are reserved (admin, api, settings and the like).

The Free plan has one seat, so inviting people needs a paid plan.

The plan also sets how many runs the org has going at once, how long finished runs are kept, and how much managed compute its steps use; what your plan includes has the numbers. A run started at the cap waits its turn instead of failing, as Before a run starts describes. Settings > Usage and Settings > Billing show where an org stands.

You can own one org on the Free plan. Orgs on a paid plan don’t count toward that, and neither do orgs you only belong to. Upgrade your Free org to create another.

Projects

List the projects you can see, and create one (org admin or owner). The console has the same under Settings > Projects:

spool project list
spool project create api --name "API service"
spool project create web --name "Web app"

Submit work to a specific project with --project. The run id it prints is fully qualified, so you can paste it into any run command:

run=$(spool submit ./pipeline.yaml --project api)
spool run get "$run"
spool logs "$run" -f

Delete a project (and its scoped state) with spool project delete <slug> (org admin or owner); it refuses while runs are executing.

Members and roles

Every membership carries one of four roles. They’re ranked, so a higher role includes everything below it:

Role	Can
viewer	read: list and watch runs, read logs, list secret names
member	the above, plus run workflows (submit, cancel, signal), save and publish graphs, create a schedule or fire one now, and add a handler
admin	the above, plus manage members, projects (create and delete), secrets (set and delete; no role reads a value back), schedules (edit, pause, resume, delete), handlers (replace, remove), webhooks, and caps
owner	the above, plus change ownership; an org owner also mints agent tokens for the org and its projects

A graph’s own triggers follow the graph rather than the handler and webhook rules. Publishing, which a member can do, registers the handler and webhooks its trigger steps declare; publishing a version with no trigger steps removes them.

A handler added by hand is left alone, even one that runs the same graph. Publishing a graph with trigger steps under the name of such a handler replaces it, and that takes an admin.

Roles apply at two levels, and your effective role on a project is the higher of the two:

• An org-wide role (spool org member) applies to every project in the org.
• A project grant (spool project member) admits someone to just that one project, with no org-wide access. Use it to give a contractor member on web without letting them see api. A grant stops at admin; owner is an org-level role only.

Add people by email, here or under Settings > Members. Both commands create the user if the email is new, create their login and send the invite mail, and print which of those happened. There is no separate invite step:

# Org-wide: a teammate who works across all projects
spool org member set dana@example.com --role member

# Project-scoped: a contractor who works on one project and can only read another
spool project member set sam@example.com --role member --project web
spool project member set sam@example.com --role viewer --project api

spool org member list and spool project member list list current members (admin-gated). The org’s last owner can’t be demoted or removed, so an org can’t be left ownerless.

When a permission check fails, the error says why: you don't have access to \myorg/api`, or this needs the `member` role on `myorg/web`; you have `viewer``. Ask an org or project admin to grant you with the commands above.

What’s project-scoped

These all belong to a project and follow the same role rules:

• Secrets - encrypted config, injected into steps.
• Credentials and connected accounts - auth that steps and nodes name.
• Schedules - recurring runs.
• Events and handlers - the project bus.
• Webhooks and connected repos - one webhook per forge, serving every repo you connect from it.

Your org’s steps run on managed environments, each started for one org or project and never shared with another org. Agents you run yourself are scoped by their token to your org or to one project; see Running your own agent.

Exporting and deleting

An org admin can download everything the org holds as one JSON file, from Settings > Data or with:

spool org export acme                  # writes acme-export.json

It has the members, projects, every version of every workflow, schedules, handlers, webhooks, the names of secrets and credentials, and every run with its history and output. Secret values aren’t in it. Logs and artifacts aren’t either, since they can be far larger than the rest: each run names the paths its log and artifacts are served at, which work for as long as the org exists.

An owner deletes the org under Settings > Data by typing its slug, or:

spool org delete acme                  # asks first; pass --yes in a script

Everyone loses access at once, and the rest happens in the background: queued and running runs are cancelled, then schedules, handlers, webhooks, secrets, credentials, connected accounts, run history, logs and artifacts are removed, and the org’s agent tokens stop working. Running the command again says whether it has finished. The slug stays taken for 30 days.

A paid subscription is cancelled with the org: it does not renew, there is no refund for the rest of the period, and the period’s metered usage is billed on its last invoice when the period ends.

Settings > Account downloads what the service holds about you (your account, memberships, the terms you accepted and a list of your tokens) and deletes your account. Deleting is refused while you are the only owner of an org: give it another owner under Settings > Members, or delete it, first.

Deleting your account removes your sign-in, memberships, tokens, the accounts you connected, your chat links, your copilot conversations and what you wrote in an invite request. Runs you started stay with their org, and the run list shows them as started by a deleted user. Invited again, the same address starts a new account.