> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reasonos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboarding your organization

> Claim your workspace, bring your team and your code, connect AI, and open your first branch — with the keys you need at each step.

This guide is for the person setting up ReasonOS for a team on a hosted deployment such as `gc.reasonos.com`. It walks through the first day in order and tells you, at each step, what you need to have in hand. Nothing here requires installing anything on your laptop; everything happens in the browser.

If you only want to share documents, skip to [Free document sharing](#free-document-sharing) at the end.

## Before you start

Have these ready. Each is used by one step below, and none is needed before you reach that step.

| You need | Used for | Who provides it |
| - | - | - |
| Your ReasonOS organization | Signing in for the first time. ReasonOS creates it with you during onboarding. | ReasonOS |
| Admin access to your git host (GitHub or GitLab) | Adding the organization's **import key** so branch servers can clone and push your repositories. | You |
| A personal AI plan (Claude, ChatGPT or Google) **or** a provider API key (Anthropic, OpenAI or Google) | Running the coding agent and the assistant in the editor. You need at least one of the two. | Each member, or the project admin |
| Your company email domain verified with ReasonOS | Optional. Lets teammates with that domain join without an invitation. | ReasonOS, at your request |
| A URL where your application runs | Optional. Only for the QA feature's first run. | You |

<Note>
  You never paste a private key, a password or an API key anywhere except the settings page built for it. The organization's git key is generated by ReasonOS and its private half never leaves the platform. AI credentials are stored by the control plane and are not visible to branch servers or to other members.
</Note>

<Steps>
  <Step title="Claim your workspace">
    Sign in with the link ReasonOS gave you. On the first sign-in from a new organization, ReasonOS asks you to claim a workspace:

    * **Subdomain** — the address your team will use, checked live as you type. `acme` becomes `acme.gc.reasonos.com`.
    * **Workspace name** — the display name, for example "Acme Inc.".

    Choose **Create workspace**. You become the workspace **owner**, and the browser lands on the projects page of your new workspace.

    Ownership moves only by an explicit transfer, never by editing a role, so claim the workspace from the account that should hold it.
  </Step>

  <Step title="Check your security settings">
    Open **Settings › Security** (in the Organization group).

    * **Multi-factor authentication is on by default** for password and emailed-code sign-ins. Members enrol on their first sign-in. Sign-ins through your company's single sign-on are exempt, because your identity provider owns the second factor. Turn MFA off here only if your identity provider already enforces it.
    * **Session length** has a ceiling you can lower for your organization.

    If your company uses single sign-on, ask ReasonOS to connect your identity provider to your organization. Members then sign in with the company button instead of a password.
  </Step>

  <Step title="Bring your team">
    There are two ways in for a teammate.

    **Invitations.** Open **Settings › Access › People** and invite by email. Every invitation creates a **member**. Once the person has accepted, open their row and change the role to **admin** if they need one. The email link opens a sign-in page; a teammate who already has a ReasonOS account just signs in. Invitations work even when open sign-up is off.

    **Joining by verified domain.** If your company domain is verified with ReasonOS, anyone who signs in with a verified email at that domain joins automatically as a member. Consumer domains such as gmail.com never qualify. Ask ReasonOS to verify your domain if you want this.

    Roles are **owner**, **admin** and **member**. A member can read and push to every project in the organization by default. To hold someone to read-only, or to give a team more, grant a role under that project’s **Settings › Access**. Define finer-grained roles under **Settings › Access › Roles** and group people under **Teams** when you want project permissions to follow a team rather than a list of names.
  </Step>

  <Step title="Connect your code">
    ReasonOS clones your repository onto a branch server every time someone opens a branch, and pushes commits back. For a repository that lives on GitHub or GitLab, it does that with the **organization's import key**.

    1. **Generate the import key.** Open **Settings › Integrations › Git & SSH** and choose **New import key**. Give it a name your git host will recognise later, such as `reasonos-import`. ReasonOS generates the pair and shows you the public half. Only the newest key is active, so generate one and keep it.

    2. **Add the public key to your git host.** Copy the public key and paste it in:

       * **One repository** — add it as a **deploy key** on that repository. On GitHub, tick **Allow write access**. Without it, ReasonOS can clone but cannot push branches back.
       * **Many repositories** — GitHub allows a deploy key on only one repository. Add the same public key to the **SSH keys** of a service account that has write access to every repository you plan to import.

       You do this once per organization.

    3. **Import the repository.** From the projects page choose **New project**, then **Other git remote**, and paste the clone URL in its SSH form, for example `git@github.com:acme/payments.git`. A private repository needs the import key from step 1; the form tells you if none exists yet and links to Git & SSH.

    **Hosted on ReasonOS instead.** If the code has no home yet, **New project › New RBS workspace** makes a ReasonOS-hosted repository. Cloning it to your own machine uses a personal SSH key from **Your profile › Profile & preferences** — see [Git](/platform/git#cloning-and-pushing).

    <Note>
      Connecting a GitHub account directly (a GitHub App) is not available yet. The import key is the supported path for GitHub and GitLab repositories today.
    </Note>
  </Step>

  <Step title="Connect AI">
    The editor's assistant, the coding agent, and the Claude Code, Codex and Gemini command lines on branch servers all need a credential. There are two kinds, and they serve different things.

    **Your own plan (per member).** Open **Your profile › Profile & preferences › AI subscriptions**. There is one card each for Claude, ChatGPT and Google. Sign in with the vendor, or paste the token its command line gives you (`claude setup-token` for Claude, the contents of `~/.codex/auth.json` for Codex, `~/.gemini/oauth_creds.json` for Gemini). From then on the coding agents on every branch server you open run on your plan, and only for you. Nobody else can use it, and your work never bills to a teammate's plan.

    **A provider key (per project).** Open the project's settings and choose **AI providers**. Paste an Anthropic (`sk-ant-…`), OpenAI (`sk-…`) or Google (`AIza…`) key. A project key powers the editor's built-in assistant and shared workflows such as AI orchestration. It does **not** power the Claude Code, Codex or Gemini command lines; those always use a member's own plan. Usage against a project key counts toward the organization's monthly model budget.

    Named extra keys for shared workflows live with the project’s provider keys under **Project settings › AI providers**. Organization-wide provider keys live under **Settings › AI providers**.

    | You want | Set up |
    | - | - |
    | Claude Code, Codex or Gemini in a branch terminal | The member's own plan under AI subscriptions |
    | The editor assistant for one person | Either the member's plan or a project key |
    | Shared workflows that run without a person present (AI orchestration) | A project key or an organization key |

    **With nothing configured** the chat still opens, but the first message fails with an error that names **Your profile › Profile & preferences › AI subscriptions**. Resending the message does not help; configure a credential instead. Details: [Configure AI access](/agents/using-the-agent#providers-and-api-keys).
  </Step>

  <Step title="Set your limits">
    Open **Settings › Compute › Compute & quotas**.

    * **Concurrent branch servers.** Your organization has a ceiling set by ReasonOS. You can lower it here.
    * **Monthly model budget.** The token budget shared by everything that runs on project and organization keys.

    Project settings › **Branch servers** is where you stop a server. A normal stop preserves that branch’s workspace and ReasonOS context so reopening it can resume where it left off. Only a project administrator can choose **Stop and destroy workspace**, which asks for an explicit typed confirmation and permanently removes that branch’s uncommitted workspace and context.

    Commit and push work you need to share or keep in the remote repository; durable branch workspaces are not a replacement for source control. **Project defaults** is currently marked Coming soon, so configure project-specific behavior in each project’s settings today.
  </Step>

  <Step title="Open your first branch">
    From the projects page open your imported project, then open a branch. ReasonOS starts a branch server, clones the code, and the editor connects when it is ready.

    The quickest way in is **Take the tour** on the project page, beside Open workspace. It opens the default branch's workspace and starts the **Platform tour**: the assistant walks you through the editor, terminals, builds, tests, previews and QA one stop at a time, checking each step against the workspace you are actually in. It takes about ten minutes and changes nothing.

    The same tour, and any guides a repository ships in `.reasonos/guides/`, are always under **Teach me** in an empty assistant chat. The first time you open a workspace in a browser, that list opens for you without sending anything to an AI model. A link can also start a named guide directly by adding `?guide=<guide-id>` to a workspace address, for example `?guide=platform-tour`.

    Every teammate who opens the same branch joins the same server and sees the same files, terminals and assistant conversations. See [Collaboration](/editor/collaboration).
  </Step>

  <Step title="Optional: CI, QA and Work">
    * **CI.** Add a `ci.rbs` file at the root of your repository and declare a `ci_workflow`. Pushes, merges, new branches and manual runs trigger it, and results appear on the project's **Runs** tab. Guide: [CI](/platform/ci).
    * **QA.** The first time you open the project's QA tab, it asks where your application runs (a base URL and an environment name, by default `staging`) and offers to run a smoke test or write your first test. Guide: [QA](/platform/qa).
    * **Work.** Issues, cycles and proposals live on the project’s Work tab in the shared project record, so they stay visible across branches. Branch tasks remain a branch-local execution aid. Guide: [Work](/platform/work).
  </Step>
</Steps>

## Keys and credentials at a glance

| Credential | Created where | Pasted where | Scope |
| - | - | - | - |
| Organization import key | Settings › Integrations › Git & SSH (ReasonOS generates it) | Your git host: a repository deploy key with write access, or a service account's SSH keys | Every branch server and CI run in the organization |
| Personal SSH key | Your own machine | Your profile › Profile & preferences › Personal SSH keys | Cloning ReasonOS-hosted repositories to your laptop |
| Personal GPG key | Your own machine | Your profile › Profile & preferences › GPG keys | Tying signed commits back to you |
| AI subscription (Claude, ChatGPT, Google) | The vendor | Your profile › Profile & preferences › AI subscriptions | Your sessions only, on every branch server |
| Project provider key (Anthropic, OpenAI, Google) | The provider's console | Project settings › AI providers | The project's assistant and shared workflows |
| Organization provider key | The provider's console | Settings › AI providers | Shared workflows across projects |

## Free document sharing

Where the deployment offers it, anyone can start a **Free document sharing** workspace without talking to sales: choose **Get started** on the ReasonOS site, sign up with an email, verify it, enrol in multi-factor authentication, and claim a subdomain and workspace name. The workspace opens on the document library.

A document sharing workspace holds up to 100 documents and 10 GiB, and its settings show only the pages that apply to documents: members, security, people and roles. When your team is ready for code, branch servers and agents, open **Settings › Plan** and choose **Request the full product**. A ReasonOS operator reviews the request and, on approval, the workspace becomes a full one with everything in this guide available.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.