Get started with SupaCloud

By the end of this tutorial you will have an account on a SupaCloud instance, an Organization and a Workspace, model access so agents can think, Git access so they can clone and push, and one project bound to a repository — exactly what Your first agent run assumes you already have. It takes about fifteen minutes.

What you need

• The URL of a SupaCloud instance — a hosted one, or one you self-hosted.
• An email address you can read mail at. Sign-in is magic-link-first, so the first thing SupaCloud does is send you a link.
• One AI provider API key, or a provider account you can authorize (Anthropic, OpenAI, Google, GitHub Copilot, OpenRouter, …).
• A git repository you can read and write.

Front-load the two things that surprise new users

A self-service sign-up is not approved automatically. Only an address listed in the instance’s SUPACLOUD_INITIAL_ADMIN_EMAILS configuration is approved as its account is created; every other new account lands on Account pending approval until an instance admin approves it under Owner → Users. On your own self-hosted instance, sign up with the address you put in that variable and you skip the wait entirely.

The Get started checklist is owner-only. It reads the Workspace’s autonomy state, which only an owner may read, so a member who joined an existing Workspace by invitation never sees it — and does not need it, because whoever owns that Workspace has already done sections 3 to 6 below. If that is you, skip straight to Your first agent run.

1. Sign in or create an account

The sign-in page leads with a magic link, not a password: you identify yourself with an email address and SupaCloud mails you a one-time sign-in link. A password is a quiet opt-in below it, not the main road.

1. Open your instance URL. You land on /login.

2. Type your email address and press Continue with email. One of two things happens: if your address’s domain is mapped to an Organization’s single sign-on you are redirected to that identity provider; otherwise SupaCloud emails you a sign-in link that expires in 30 minutes and shows you the password card, so you can still choose Sign in with a password instead.

3. No account yet? Press Need an account? Sign up, then give your name, your email and — optionally — a password of at least 12 characters. The password really is optional: the magic link alone is a complete sign-in method. (If your instance has registration closed, this button is absent and an admin invites you instead.)

4. After signing up you land on Verify your email. Open the confirmation link SupaCloud sent — it expires in 24 hours — to activate the account. Nothing arrived? Use Resend confirmation link, or Change email address if you mistyped it.

5. If you have already armed an authenticator app on this account, the password step hands you on to a six-digit code prompt. Your second factor belongs to your SupaCloud account, so it applies no matter which sign-in method you used.

What varies per instance — do not hunt for a button that is not there

Three sign-in affordances are opt-in and off by default, so whether you see them depends on how your instance is configured:

• Social login — Continue with Google / Continue with GitHub appear under the email field only when the operator configured that provider. See Sign in with Google or GitHub.
• Captcha — a small verification step your browser solves silently, shown while registering, requesting a magic link or resetting a password (and on sign-in after several failed attempts). It needs an HTTPS origin.
• Enterprise SSO — a Continue with OIDC button carrying an ENTERPRISE badge.

An operator turns the first two on as described in Enable social login and the captcha.

2. Meet your Organization and your Workspace

Two words do the tenant work in SupaCloud, and you create neither of them by hand. Your first sign-in provisions both in one transaction: a personal Organization (named Personal) and one Workspace (named Workspace), with you as the owner of each.

The Organization is the top tenant — it owns billing and seats, single sign-on and invitations. You belong to exactly one, which is why there is no Organization switcher anywhere in the UI: the server derives your active Organization from your active Workspace. The Workspace is the container everything else lives in — projects, tasks, runs, workflows, schedules, secrets and connectors are all Workspace-scoped, and membership is per user.

Rename the Workspace to something meaningful under Settings → Workspace whenever you like; nothing in this tutorial depends on its name. For the full model — and the one term, one meaning rule behind it — read Workspaces and Organizations.

3. Open the Get started checklist

On a brand-new Workspace the dashboard greets its owner with a Get started modal over a dimmed backdrop. It is the same path this tutorial walks, and it is worth following in the app rather than from memory, because it probes your actual state: four required steps, a n/4 counter, and two optional power-ups set apart below.

Three behaviours are worth knowing before you start clicking:

• Each step’s Set up button deep-links to the exact surface that step needs. When you come back to the tab, the checklist re-probes and ticks the step Done by itself — you never refresh, and an OAuth flow that finished in another tab is picked up on return.
• The order is deliberate and it is credentials-first. Model access, then Git access, then the project, then the run. Each step is a hard prerequisite of the next, so skipping ahead just makes the failure arrive later.
• Skip hides the modal for this browser session only. The persistent reminder is the Onboarding mode banner in Settings → Workspace, which is also where you can finish setup later.

The two optional power-ups — MCP credentials and a custom skill — give agents extra tools and reusable instructions. Neither blocks a first run; leave them for later.

4. Connect a model harness

This is the checklist’s first step because it is the one an agent cannot work around. A harness credential is what lets the agent think; without it a launch has no model to run on and fails before it has done anything useful.

1. Press Set up on Connect a harness. You land on Settings → API Keys.

2. Choose how to give SupaCloud model access:

   • Paste an API key — pick the provider, optionally label the key, paste the value.
   • Connect an account — pick the provider and press Connect to run an OAuth flow instead of copy-pasting a key. GitHub Copilot uses a device code: SupaCloud shows a short user code and a github.com URL, you authorize there, and SupaCloud finishes the connection by polling in the background.

3. Pick a scope: Personal for a key only you use, Workspace to share it with everyone in the Workspace, Organization for an Organization-wide key (owners and admins only).

4. Save, then return to the dashboard tab. The step flips to Done as soon as one API key or one connected account exists.

There is no wiring step

You do not assign a credential to an agent. The matching login is resolved automatically at launch — Claude is the recommended starting point. And a model whose provider has no credential is shown greyed out in every model picker, so the UI tells you what is reachable rather than failing at run time. Scopes, precedence and locking are covered in Manage secrets in the UI.

5. Add Git access

The checklist’s second step is the other half of the dependency chain. An agent works in a disposable container: it clones your repository into it, commits, and pushes a branch back. Without a Git credential the clone fails at the very first command.

1. Press Set up on Add Git credentials. You land on Settings → Git.

2. Choose the auth type — SSH Key or Access Token — and paste the key or token value.

3. Optionally restrict the credential to one provider (GitHub, GitLab, Forgejo, Bitbucket). Leave it unrestricted and it is offered for every provider.

4. Pick a scope (Personal, Workspace or Organization) and save.

Read access is not enough

Grant the token or key write access to the repository, not just read. An agent that can clone but cannot push will do the whole job and then have nowhere to deliver it — a failure that looks like a broken agent and is really a credential scope. If your instance has both an Organization-wide key and your own, the most specific scope wins; see Manage secrets in the UI.

6. Create your first project

A project is what an agent is pointed at: a name plus a repository, in the active Workspace.

1. Press Set up on Create a project. You land on the New Project form.

2. Fill in:

   • Name — how the project appears in every list, and the word you type in the web terminal’s run command.
   • Git Repo URL — required. An SSH URL works, for example ssh://git@git.example.com:2222/org/repo.git.
   • Git Provider — Forgejo, Bitbucket, GitHub or GitLab.
   • Git Credential — the picker lists only credentials that match the provider you just chose. This is precisely why section 5 came first: with no matching credential the picker offers only No credential and a link back to Settings.

3. Press Create Project. You land on the new project’s page.

A project can start git-only

An issue tracker is not required to create a project. You can wire the forge’s own issues, or Linear or Notion, from the project’s configuration later, and then launch work straight from an issue — see Launch a task from an issue.

7. Finish setup — and what that unlocks

The checklist’s fourth step is the next tutorial, so do it there. Once all four show Done, a Finish setup button appears in the modal footer. Pressing it is not cosmetic: it turns the Workspace’s onboarding mode off, and onboarding mode is a real safety posture.

While it is on, the Workspace’s autonomy level is capped at 25 and autonomous backlog dispatch is paused, no matter what the slider shows. Graduating lifts the cap to the full range and lets the delivery engine start dispatching work on its own. Only the Workspace owner can press it, graduation is one-way, and if you would rather stay capped for now you can leave it and graduate later from the Onboarding mode banner in Settings → Workspace.

If you are not sure you want autonomous dispatch yet, read Set the autonomy level before you press it — the cap exists so a brand-new Workspace cannot dispatch work unattended before you have seen a single run.

What you have now

• An approved account you can sign in to, by magic link or password.
• A personal Organization and one Workspace, both owned by you.
• A model harness credential, so agents can think.
• A Git credential with write access, so agents can clone and push.
• One project bound to a repository.

Next: your first agent run

That is every prerequisite Your first agent run assumes. Go there next: it launches an agent against the project you just created, follows it live, and reads back what the run cost.

If something on this page did not behave as described — no confirmation email, a stuck Account pending approval screen, a project that refuses to save — see Troubleshooting.