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

# Onboarding

> Set up your workspace repository and choose your first training workflow

Use onboarding once before running the quickstart or building a custom rollout. By the end, you should have a platform workspace, a connected GitHub repository, a local clone, and an authenticated CLI session.

Osmosis setup starts in the [Platform](https://platform.osmosis.ai). The platform creates or provides a **workspace repository** on GitHub, and your local **workspace directory** is a clone of that repository.

## Common Setup

Complete these steps before using [Run the Multiply Example](/platform/quickstart) or [Create Your Own Rollout](/platform/create-your-own-rollout).

<Steps>
  <Step title="Create or join a platform workspace">
    If you are creating a new workspace, sign in to the platform and create it there. If you were invited, accept the invitation and open the existing workspace.
  </Step>

  <Step title="Set up the workspace repository">
    Workspace owners or admins connect a GitHub account or organization, install the Osmosis GitHub App, and create the workspace repository from the platform.

    Repositories created from the platform include the starter examples `multiply-local-strands`, `multiply-local-openai`, and `multiply-harbor-strands`.

    Invited workspace members use the workspace repository that already exists. Do not create a second repository for the same workspace.
  </Step>

  <Step title="Clone the workspace repository">
    The platform shows clone commands once a repository is connected. Choose HTTPS, SSH, or GitHub CLI:

    <CodeGroup>
      ```cli HTTPS theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
      git clone https://github.com/<owner>/<repo>.git
      cd <repo>
      ```

      ```cli SSH theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
      git clone git@github.com:<owner>/<repo>.git
      cd <repo>
      ```

      ```cli GitHub CLI theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
      gh repo clone <owner>/<repo>
      cd <repo>
      ```
    </CodeGroup>
  </Step>

  <Step title="Install and authenticate the CLI">
    Install the Osmosis CLI and connect it to your account:

    <CodeGroup>
      ```bash pip theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
      pip install osmosis-ai
      ```

      ```bash pipx theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
      pipx install osmosis-ai
      ```

      ```bash uv tool theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
      uv tool install osmosis-ai
      ```
    </CodeGroup>

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
    osmosis auth login
    ```

    Run platform commands from inside the workspace directory. The CLI reads GitHub `origin` to identify the platform workspace connected to this repository.
  </Step>

  <Step title="Verify local workspace context">
    From the cloned workspace directory, confirm the CLI can resolve your workspace:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
    osmosis doctor
    osmosis auth whoami
    ```
  </Step>
</Steps>

## Choose Your First Workflow

<CardGroup cols={2}>
  <Card title="New to RL" icon="rocket" href="/platform/quickstart">
    Run the included `multiply-local-openai` example end to end with copy-paste commands.
  </Card>

  <Card title="Already have a task or dataset" icon="wand-magic-sparkles" href="/platform/create-your-own-rollout">
    Use the workspace's project-local Agent Skills to plan training, create a rollout, and validate it locally.
  </Card>
</CardGroup>

## Workspace Repository vs Directory

| Term                     | Meaning                                                                                                                                  |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Workspace repository** | The GitHub repository connected to a platform workspace. The platform creates or connects it and uses it as the source of rollout code.  |
| **Workspace directory**  | Your local clone of the workspace repository. Run CLI commands from here so Osmosis can infer the connected workspace from Git `origin`. |

## If Setup Is Blocked

The platform may show a GitHub banner when the workspace is missing required repository setup.

| State                       | What to do                                                                    |
| --------------------------- | ----------------------------------------------------------------------------- |
| No GitHub account connected | Workspace owners or admins should connect GitHub from **Git Integration**.    |
| No repository connected     | Workspace owners or admins should create or connect the workspace repository. |
| GitHub App disconnected     | Reconnect the GitHub App before submitting a training run.                    |
| Repository needs setup      | Open **Git Integration** and follow the repository repair flow.               |

<Note>
  For details on how Git Sync controls the code version used for training, see [Git Sync](/cli/workspace/git-sync).
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Run the Multiply Example" icon="rocket" href="/platform/quickstart">
    Copy and paste the shortest path from cloned repository to training run.
  </Card>

  <Card title="Create Your Own Rollout" icon="wand-magic-sparkles" href="/platform/create-your-own-rollout">
    Build a task-specific rollout with project-local Agent Skills and evaluation run gates.
  </Card>

  <Card title="Workspace Repository" icon="code-branch" href="/cli/workspace/repository">
    Understand how the CLI maps your Git clone to a platform workspace.
  </Card>
</CardGroup>