> For the index of every page in Orbital's docs, read https://docs.beta.runorbital.dev/llms.txt. # Start your first run > Add a repository as a project, run explain-repo and read its answer You add a repository you already have as a [project](/projects/) and run the `explain-repo` workflow on it. One agent step reads the repository and answers with its purpose, who it is for, how it is built and how to run it. About 10 minutes. The run itself usually takes one to three minutes. The run only reads. It makes no worktree, no branch and no pull request. ## Before you start You need a Mac for the app. On Linux or Windows, [install the `orbital` command](/get-started/install/) with npm and run `orbital serve` instead. The steps in the browser are the same. You also need a repository on your machine to explain. ## 1. Install Orbital and sign in to a harness 1. **Download Orbital.** Download it for [Apple Silicon](https://releases.runorbital.dev/macos/Orbital-latest-arm64.dmg) or [Intel](https://releases.runorbital.dev/macos/Orbital-latest-x64.dmg). 2. **Drag Orbital to Applications.** Open the disk image and drag Orbital to **Applications**. 3. **Install a harness and sign in.** Orbital ships no [harness](/harnesses/), so install one yourself. Any of the three runs this first run. **Claude Code** Run `npm install -g @anthropic-ai/claude-code@latest`. Then run `claude` in a terminal and follow the login. The [Claude Code setup guide](https://code.claude.com/docs/en/setup) has other ways to install it. **Codex** Run `npm install -g @openai/codex@latest`, then `codex login`. The [Codex guide](https://learn.chatgpt.com/docs/codex/cli) has other ways to install it. Codex starts only in a Git repository, so add a repository, not a plain folder, as your project. **OpenCode** Run `npm install -g opencode-ai@latest`, then `opencode auth login`. The [OpenCode guide](https://opencode.ai/docs/) has other ways to install it. 4. **Open Orbital.** Open it from **Applications**. Orbital finds `git`, `claude`, `codex` and `opencode` on your login shell's `PATH`. **Settings > Harnesses** shows each harness. A harness it cannot find reads "Not installed", with the command to install it. [Install Orbital](/get-started/install/) has the details for each harness. ## 2. Add the repository as a project The first time Orbital opens, it asks you to "Give your agents a place to work." ![The first-launch wizard with the heading Give your agents a place to work, the steps Welcome, Project and First run, and a Set up a project button.](/screenshots/first-launch.webp?v=5ece35762f) *The wizard opens on the first launch.* 1. **Start the project setup.** Choose **Set up a project**. 2. **Pick a folder.** Choose **Choose folder** and pick a repository on your machine. A plain folder works too, except on Codex; see [plain folders and Git](/projects/#plain-folders-and-git). Orbital names the project after the folder. ![The first-launch wizard while a project is being added, with the same Welcome, Project and First run steps.](/screenshots/add-project.webp?v=2d32cbc234) *Orbital names the project after the folder you pick.* 3. **Add the project.** Choose **Add project**. The project is ready when the app says "Your project is ready." 4. **Go to the first run.** Choose **Prepare first run**. Already past the first launch? Open **Projects** and choose **New project**. Name it, then choose **Add folder** on the project's page. The first folder you add is the project's primary folder. [Projects and folders](/projects/) explains more. ## 3. Run explain-repo 1. **Open a new session.** Choose **New task** in the sidebar. The project you added is selected at the top. 2. **Choose Workflow mode.** Make sure the switch under the text box says **Workflow**, not **Chat**. 3. **Pick the workflow.** Open the workflow menu and choose `explain-repo`. 4. **Write the goal.** In the text box, write what you want to know, for example `Explain this repository to a new team member`. This is the run's goal. ![The Start page asking what to do in a project, with the goal box, the harness picker, the workflow picker and the Chat and Workflow switch.](/screenshots/start-page.webp?v=0428f5d705) *Set the switch to Workflow, pick explain-repo, then write your goal.* 5. **Pick a harness.** In the harness picker, choose the harness you signed in to: Claude Code, Codex or OpenCode. 6. **Start the run.** Choose **Start run**. The step only reads the repository and explains it. Its prompt tells it not to change, create or delete any file, and to run only commands that read. It works the same on Claude Code, Codex and OpenCode. ![explain-repo has one step, explain, and then done.](/shipped/explain-repo.svg?v=900c23c839) The run page opens. The **Session** tab shows the `explain` step working: the files the agent reads and its reply as it writes it. [Watch a run](/runs/watch-a-run/) explains the rest of the page. ## 4. Read the answer The answer is the agent's last message in the **Session** tab, just above "Run ended: success". It has four parts: 1. Purpose: what the repository does. 2. Who it is for. 3. How it is built. 4. How to run it. The agent says where it found each fact. It also says so when the repository does not tell. The **Context** tab keeps the same answer as `response.explain`. ## If the run stops A run that cannot start its harness stops. It is [Paused](/runs/#standings), and its badge reads "Waiting on you". The step shows why, for example that the harness is not installed or not signed in. Fix that, then choose **Resume**. [Troubleshooting](/troubleshooting/) lists the common causes. ![A run page on the Session tab showing its steps one by one and ending in Stopped with an error, with run facts such as project, workflow, branch, harness, model, run ID and path on the right.](/screenshots/run-thread.webp?v=f4f203d47e) *The Session tab says where and why a run stopped.* ## Next steps - [Implement a feature](/examples/feature-pull-request/): deliver a change as a pull request. - [Research report](/examples/research-report/): turn a question into a written report. - [Runs](/runs/): what a run is and what you can do with one. - [Permissions](/roles/#permissions): what a run asks you before its agent acts, on each harness. - [How Orbital works](/concepts/how-orbital-works/): the ideas behind the run you just watched. - [Write your first workflow](/workflows/write-a-workflow/): write a workflow of your own.