Skip to main content
This guide is for the person setting up ReasonOS for a team on a hosted deployment such as gc.reasonos.com. It walks the first days in order. Each step says where it happens, who can do it, what you need, what you’ll see when it worked, how to check it, whether you can skip it for now, and what to do if it fails. The required hosted setup uses the browser. Optional CLI-token setup and cloning to your own machine use local tools. Steps marked required are the five that Settings › Setup counts (on deployments that include it; see Where setup stands). The rest can wait until you need them, and the guide says what each one unlocks. If you only want to share documents, skip to 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 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; Settings shows only its public half. In the legacy SSH path, trusted execution servers receive the private key for repository access, so restrict the upstream identity to repositories intended for this team. In managed mode, original vendor AI credentials stay with the credential service; branch servers use scoped session credentials. Collaborators share an execution environment, so this is not isolation from untrusted teammates. See AI accounts and keys. Never put a key in a chat, an issue, a shared branch-server terminal or a commit, even to ask for help.

Roles in one line

Owner holds the workspace; ownership moves only by an explicit transfer. Admins can change organization settings and integrations. Members can read and push to every project by default. Steps below name the role they need.
1

Claim your workspace (required)

Where: the sign-in link ReasonOS gave you. Who: the person who should own the workspace.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’ll see: the projects page of your new workspace, empty, with you as the workspace owner.Check: Settings › Setup shows Workspace and your role as configured.If it fails: a subdomain that is already taken is refused as you type; pick another. Claim the workspace from the account that should hold it, because moving ownership later is an explicit transfer, never a role edit.
2

Check your sign-in security (required)

Where: Settings › Organization › Security. Who: someone with permission to manage organization settings (owners and admins by default).
  • 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. Leave MFA on for password and emailed-code sign-ins; your identity provider’s MFA does not protect those separate sign-in paths.
  • Session length — how long a branch server holds a person’s credential; terminals and agents lose it after this. The page shows your deployment’s maximum.
  • Shared branch servers lets people with different access to a project share one server; leave it off unless the team trusts each other fully. When it is off, a mismatch can refuse joining the existing server; do not work around that by sharing credentials.
  • Secret values from tools is off by default: secret values are entered in Settings, not through access tokens, assistants or agents. Turn it on only if your team sets secrets from scripts or tools on purpose.
Changes to this policy are recorded in the organization audit log.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.Check: Setup shows Two-factor sign-in as configured while MFA is required. With MFA off it shows saved, not verified; this is not proof that another sign-in path enforces MFA. Setup cannot verify your single sign-on policy.If it fails: a member who lost their second factor cannot reset it from this page, and removing their membership does not reset it either. Ask ReasonOS, who operate the sign-in provider, to recover the account.
3

Bring your team

Where: Settings › Access › People. Who: an owner or admin. Skip: yes — you can set up code and AI alone and invite people later.There are two ways in for a teammate.Invitations. 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.Every member can read and push to every project by default because the organization’s base permission is Write. A project role granted under a project’s Settings › Access adds to that floor; granting someone Read on a project does not take their inherited Write away. To hold people below that floor, use an explicit deny in a custom role under Settings › Access › Roles (a deny beats every allow, and owners are never denied). There is no page in Settings for changing the base permission yet; if your organization needs a different base — for example no access, so projects are invitation-only — ask ReasonOS. Group people under Teams when project permissions should follow a team rather than a list of names. The effective permission a person has on a project is shown on that project’s Access page (What can I do?).You’ll see: the person in People, with Invited until they accept.Check: Setup shows Teammates as configured once two members exist; pending invitations alone show as saved, not verified.If it fails: an invitation that never arrives is usually a spam filter; resend from the row. A person at a verified domain who still can’t join is signing in with a different email address than the verified one.
4

Connect your code (required)

Where: Settings › Integrations › Git & SSH (the page is titled Git access), then New project on the projects page. Who: an admin for the key; anyone who can create projects for the import. You need: admin access to the git host.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. On Git access 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 organization key is active. Generating another replaces it for existing imports and can break their access until the git host is updated; do not rotate it as a troubleshooting step.
  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 dedicated service account limited to the repositories your team intends ReasonOS to use. Everyone authorized to work on those projects can use the platform’s repository access; it does not inherit each person’s separate GitHub permissions.
    You do this once per organization.
  3. Import the repository. From the projects page choose New project. The first step asks which products the project will use (Work, Code, QA, Observe, Understand, Feedback — each can be turned on or off later in Project settings); the second is the starter: choose Import a repository (“Bring existing code from GitHub or any git remote”). On deployments without configured first-class GitHub or GitLab connections, the Source step marks them not available yet; choose Other git remote and paste the clone URL. For private repositories using the import key, use the SSH clone URL, for example git@github.com:acme/payments.git. A private repository needs the import key from step 1 — the form says so and links to Git access — while a public repository imports without one. Enable Work if you want issues and the first-change workflow below. Finish the remaining steps (name and visibility, then review) to create the project. Private restricts readers outside your organization; it does not remove members’ inherited base Write permission.
Hosted on ReasonOS instead. If the code has no home yet, the New RBS workspace starter makes a ReasonOS-hosted repository whose main starts with WORKSPACE.rbs and a README; Empty repository gives you a bare one to push into; Product demo adds a guided tour. Cloning a hosted repository to your own machine uses a personal SSH key from Your account › Profile & preferences — see Git.You’ll see: the new project on the projects page, with its default branch and a short sync while ReasonOS fetches the code.Check: Setup shows Code connected as configured once a fetch has completed. It shows blocked with the import error if the fetch failed, and saved, not verified while the import is still running or when only an import key exists so far. A hosted starter with its initial repository also counts as connected without an external import. Whether ReasonOS can push is only proven by the first push, so the first change (below) is the real test.If it fails: Permission denied or repository not found on import usually means the public key isn’t on the host yet, is on the wrong repository, or the URL isn’t the SSH form. A clone that works but a push that is refused has several possible causes: a deploy key added without write access, a protected branch, a permission missing on the host, a changed remote or a network problem. Read the error ReasonOS shows, which may not always name the cause, and fix it on the host; nothing in ReasonOS needs re-entering.
This describes the existing organization SSH-key path. Some deployments may have separately configured repository keys or a source GitHub App; use those only when your administrator has verified their setup. Do not replace existing read-only deploy keys with write-enabled keys to troubleshoot an App-backed project.
5

Connect AI (required)

Where: Your account › Profile & preferences › Personal AI accounts (each member), and the project’s Settings › AI provider keys (an admin). You need: a personal plan or a provider key, as in the table above.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; which credentials each agent accepts is explained in AI accounts and keys, and not every personal plan serves every agent.Your own plan (per member). Under Personal AI accounts 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). Managed credential selection then uses the compatible account linked to your identity. Credential selection follows the signed-in person. Invite only trusted people to a shared branch execution environment; do not treat it as a private laptop.A provider key (per project). Open the project’s settings and choose AI provider keys. 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 keys under Project settings › AI provider keys. Organization-wide keys live under Settings › AI › AI provider keys.You’ll see: the vendor’s card marked as connected, or the key listed as set (its value is never shown again).Check: Setup shows AI connected as saved, not verified as soon as a plan is linked or a key is set. On deployments that include it, press Check now on that step: ReasonOS asks each vendor for its model list with the credential it would use for you in that project (free, never a model call) and marks the step configured for the 24-hour freshness window when the list came back. An expired check can reduce the overview’s configured count without meaning the account was disconnected. ChatGPT sign-ins and Google subscriptions have no supported model-list check, so they can remain unverified even when usable. A fresh failed vendor check keeps the combined step unverified even if another vendor succeeded. The checklist is a current status summary, not a permanent graduation or an authorization gate. See Check a step now.If it fails: with nothing configured, the chat still opens, but the first message fails with an error that names Personal AI accounts. Resending the message does not help; configure a credential instead. An expired personal account shows as blocked in Setup: sign in with the vendor again. Details: AI accounts and keys.
6

Set your limits

Where: Settings › Compute › Compute & quotas. Who: an admin. Skip: yes — the defaults apply until you change them.
  • Branch servers and CI runs running at once. Both have no additional organization cap until you set a number; at the limit new servers and runs wait, running ones stay up. On a hosted deployment the operator may cap what you can set.
  • Model tokens per month. Model calls that go through the ReasonOS model relay are metered against this budget; at the limit new calls are refused and calls already streaming finish. Calls a member’s own CLI or account makes directly are not counted here. Empty sets no additional organization token cap; provider, plan and deployment limits still apply.
  • Cluster limits (remote build workers, HPC job slots) are recorded but only applied once a remote cluster is attached.
Project settings › Branch servers is where you stop a server. A normal stop preserves that branch’s workspace and ReasonOS context. Opening or reconnecting to a deliberately stopped branch leaves it stopped; choose Start server in the workspace, or Start a server on the branch list, to resume. An agent acting with your existing start permission can also explicitly start it; this uses branch compute. Only someone with the project’s Admin permission 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.Check: Setup shows Compute and model limits as configured once your organization has saved its own limits; until then saved, not verified means the defaults apply.
7

Open your first branch (required)

Where: the project’s page. Who: any member.Open the project and choose Open workspace for your branch. A first open starts its server and prepares the code. Disabling Start the main branch server now during project creation only defers that initial start. A deliberately stopped existing server stays stopped until you explicitly choose Start server.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. The tour uses the assistant, so it needs compatible AI access and may use model quota. It does not ask the assistant to edit or commit code; builds, tests and previews run at your direction and use branch compute.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.Teammates opening the same branch share its files and execution environment, subject to access and session policy. Personal terminal and conversation visibility follows the product’s permissions; do not assume another person can inspect or control your session. See Collaboration.You’ll see: the workspace with your files in the explorer, and Connected to RBS Server in the status bar.Check: Setup shows A branch server running as configured while a healthy server is reporting; a stopped or stale one shows saved, not verified, so stopping all servers can reduce the overview’s configured count again.If it fails: a branch that stays on Starting past a few minutes, or shows a start failure, is reported with its stage and time; Try again retries, and the page says when the cause is on the operator’s side. The number of servers that can run at once is the ceiling from the previous step.
8

Store environment variables and secrets

Where: on the project’s page, Build › Environment variables (opens Environment variables in project settings), or Secrets in a workspace’s tools sidebar. Who: someone who can manage the project’s settings. Skip: yes, until a build, test or app needs a value.Entries are encrypted and their values are write-only in Settings, then delivered to authorized tools as environment variables. Code and processes receiving a value can read it: this is not a guarantee against collaborators who can run code on that workspace or CI job. With the default base Write permission, ordinary members can run project code; treat those people as trusted recipients of values delivered there. Choose Workspace (branch servers) or CI (CI runs) and the environment it applies to, or Every environment. Several entries can be pasted at once from .env-style text, with a preview before anything is saved. Guide: Project secrets.Check: the entry is listed by name with its scope. A workspace entry is delivered to authorized project execution sessions; verify its presence in a new session after saving without printing the value (for example, test -n "$NAME" && echo set).If it fails: a value that is wrong can be replaced but never read back; re-enter it. A failed save keeps your draft and says so.
9

Import your issues from Linear

Where: the destination project’s Settings › Work › Import from Linear. Who: someone who can manage that project’s settings, with read access to the Linear project. Skip: yes, if you start your issues in ReasonOS.A Linear project is the import unit: its issues, status category, priority, labels, due dates, hierarchy, comments and source links come across, add-only, into the project’s Work issues. It is a migration path, not a two-way sync, and it never posts, mentions or wakes agents on anyone’s behalf.
  1. Choose Connect Linear and authorize read access (an operator must have configured the Linear app for your deployment first; the page says so if not).
  2. Choose the Linear project and review the preview: issue, comment, label and already-imported counts, the status mapping onto your Work statuses, and which people matched.
  3. Choose Start import, then follow its phases and counts under Import history. Accepting the job is not the same as finishing it.
Full details, including reruns, the 100-comment limit per issue, and what is not imported (cycles, relations): Import a Linear project.You’ll see: the issues on the project’s Work tab, each keeping its Linear identifier and a link back.Check: the final created, skipped and failed counts in Import history. Open Failed items for any failure’s source identifier and reason, fix the cause, and run the import again; a rerun skips what already came across.If it fails: waiting in the progress note means Linear’s API budget is exhausted and the job resumes on its own. Disconnecting Linear removes the connection, not the imported issues.
10

Connect Slack

Where: Settings › Integrations › Slack (admin), then each member’s own account link. Who: an organization admin to connect; every member links their own account. Skip: yes, until you want issues from messages or status updates in threads.
  1. Connect the workspace. Choose Connect Slack, pick the Slack workspace and approve the permissions it lists. One Slack workspace per organization. If the page says Slack isn’t set up on this installation, your deployment has no Slack app yet; ask whoever operates it.
  2. Link your account. Each member links their Slack account to their ReasonOS account from inside Slack the first time they use the app, so that actions carry the right name.
  3. Choose what a project does. Under the project’s Settings › Work, the Slack pages switch on, separately, Slack previews (issue cards when a link is shared), AI drafts in Slack, and Slack feeds for a channel; each extra permission is asked for only when you turn its feature on. AI drafts can send the selected Slack content to the configured model provider and use its applicable credential/quota; review the feature’s consent and budget before enabling it.
  4. Try it. In any channel the app can see, open a message’s More actions and choose Create ReasonOS issue; the form opens filled from the message, you choose the project, and the issue records where it came from. Nothing is posted to the channel.
Administrator guide: Connect Slack. What members can do, permissions and limits: Use Slack with Work. A channel can also receive short issue notices without the app, through an incoming webhook: Slack issue notifications.You’ll see: the workspace’s name on the Slack settings page, and the shortcuts and /reasonos available in Slack.Check: Setup shows Slack as saved, not verified once connected; press Check now on that step (deployments that include it) to confirm the saved token can read the channels the app has joined. Select a project on Setup to enable this check. It proves token access to channels, not that a particular post would land.If it fails: a shared or Slack Connect channel, an archived channel, or a direct message is refused by design; use a channel that belongs to your workspace alone, and invite the app to a private one first. Connecting a second workspace is refused until the first is removed.
11

Optional: CI and QA

  • CI. Add a ci.rbs file at the root of your repository and declare a ci_workflow. Its declared triggers determine whether pushes, merges, new branches or manual runs start it, and results appear on the project’s Runs tab. Setup shows CI as configured once a run on the default branch succeeded in the last 30 days. Guide: 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. Setup shows QA as configured once a run against a saved environment completed with a verdict. Guide: 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.

Your first change, end to end

This checks the path from an issue to a reviewed code change. You can work manually without an AI call. Set appropriate limits first: server and CI work use hosted compute; provider-key calls bill the provider account, while personal-account calls use that member’s provider quota. Confirm your deployment’s plan and prices in Billing before enabling paid work.
  1. Write it down. On the project’s Work tab, create an issue that says what should change and how you’ll know it’s done. Imported Linear issues work the same way.
  2. Create the linked branch. For a manual path without a model call, choose Create branch or stack in the issue’s Development section, choose Feature branch, and create it from the default branch. Open that linked branch’s workspace and edit the file yourself; do not press an agent-start button. Either way the issue and the branch stay linked. You can instead use Run with agent when compatible AI access and the project’s workflow approvals are configured; it uses model quota. See Run an issue with an agent for saved transcripts, run inspection, Stop and continuation.
  3. Save, check and publish the change. Open the linked branch’s workspace, edit and save the file, and review its diff in Source Control. Run the project’s build and tests when applicable. Stage the intended files, enter a commit message, and choose Commit. A commit is not necessarily published: in the workspace terminal, use git push origin HEAD to publish the assigned branch, then verify the project’s branch list shows the new commit. Do not switch the shared workspace to another branch or force-push to bypass a refusal.
  4. Open a change request from the branch. If the project has a configured CI workflow, its checks appear on the review screen; creating a change request alone does not configure CI. Guide: Change requests.
  5. Review and merge. Follow the project’s review and merge rules; merging lands the change on the default branch and, for a repository with an external origin, publishes it there. Guide: Reviewing and landing changes.
Check: the commit is on the default branch of your ReasonOS-hosted repository or external origin, the change request is merged, and the issue shows the change in its links. If the push was refused, read the error ReasonOS shows: a deploy key without write access (see Connect your code), a protected branch, a missing permission on the host, a changed remote or a network problem are each refused differently, and the message may not identify the cause.

Where setup stands

On deployments that include it, Settings › Setup shows this checklist for your workspace or a chosen project, with a link from each step to where it’s done. Until all five required steps (workspace, sign-in security, code, AI access and a first branch server) are configured, a project’s overview shows how many are done and the next one, linked to Settings › Setup. If the page or the setup tools aren’t available on your deployment, follow the settings steps in this guide. On a ReasonOS MCP connection, the setup_status tool lists each setup step with its status, why, and what to do next. project_setup_status does the same for one project, and it’s the one a branch-server session offers. They cover the workspace, sign-in security, your team, code, AI access, limits, a first branch server, CI, your own CI runners, QA, incoming data and Slack. Reading the status changes nothing and calls no outside service. Incoming data is always Unknown for now; check the project’s Observe page.

Check a step now

On deployments that include it, AI access and Slack can be checked when you ask. In a project’s Settings › Setup, press Check now on the AI or Slack step; through MCP, ask your assistant to run check_setup_item for the project. Nothing is checked when the page opens or when status is read.
  • AI access asks each vendor’s model list (free, never a model call) with the credential ReasonOS would use for you in that project, and shows one result per vendor. A result proves only that this credential can list models, not completion access or quota. A ChatGPT sign-in and a Google subscription have no model list to read, and an operator-configured deployment fallback credential is not yours to check, so these stay unverified.
  • Slack asks Slack for the channels the ReasonOS app has joined in one workspace. If a deployment offers a workspace selector, choose the installation to check; this does not imply you can connect a second workspace on a deployment that permits only one. It proves the saved token can read channels, not that a post would land.
A successful result carries the time the provider actually answered, which can be up to an hour earlier when the model list was recently fetched. A failed one carries the time of the attempt. A step that could not be checked, or a check whose outcome is unknown, shows no time and claims no answer. The newest result is kept for that exact credential: a failed check marks the step unverified straight away, and replacing a key, re-linking an account or reinstalling Slack starts over. If the credential or your access changes while a check runs, nothing is recorded and the result says to check again. Every check is recorded in the organization’s audit log with you and, for an assistant, its agent identity. A check may renew an expiring sign-in, as any use of it does. Checking again is a new check, not a replay; when a check got no answer, read the status before checking again.

Keys and credentials at a glance

If something doesn’t work

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: people, roles, security and plan management. 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.