Skip to Content
OpenInspect
Get started

Quickstart

Sign in to an existing OpenInspect deployment, start a session against a repository, and read the first result.

Last reviewed View as MarkdownEdit on GitHubGive feedback

This page takes you from signing in to reading the agent's first result in one session.

The new-session composer with repository and branch pickers above the prompt box
The composer. Pick a repository and branch, write the prompt, and send with the button or Cmd/Ctrl+Enter by default.

Prerequisites

  • Your team already runs an OpenInspect deployment and you have its URL.
  • You have been admitted to the workspace. Admission is configured by the operator, and by workspace Owners and Administrators under Settings › Workspace access › Who can sign in (allowed GitHub users, email addresses, email domains, or GitHub organization membership).
  • Your role is Member or higher. Viewers can read sessions they have access to but cannot create or prompt them. Workspace roles and team membership are separate; see Workspace access.
  • For a GitHub-backed deployment, the GitHub App is installed on the repository you want to work in. If it is not, the repository does not appear in the picker. Other source-control providers use their configured repository access.
  • For a team-owned session, you are a current member of an active team and that team has grants for every selected repository. A newly created team starts without repository grants; ask a team lead or workspace administrator to configure them under Teams.
  • At least one model is enabled under Settings › Models, with its provider credentials configured. An administrator does this once.

Sign in

Open the deployment URL. The sign-in page shows only the providers the operator configured: GitHub, Google, or both.

Sign-in has two stages. First your identity provider verifies who you are. Then the workspace's admission rules decide whether you may join the workspace. If you land on the Access Denied page ("Your account is not authorized to use this application."), your identity was verified but admission failed. Contact an administrator of the deployment; there is nothing to fix on your side.

New users receive the Member role. For GitHub pull requests, signing in with GitHub lets them be authored as you when your OAuth token is available at creation time (see Your first pull request).

Start a new session

The home page is the new-session composer, headed "Welcome to" followed by the deployment's app name. The text area's placeholder reads "What do you want to build?". You can also open it from anywhere with Cmd/Ctrl+Shift+O.

Before choosing a target, open the composer's session access selector. Review both the team context (the owning team, or No team when allowed) and the audience: Workspace, the selected team's audience, or Private. A draft initialized from the active sidebar team uses that team's default visibility; the required-team fallback also uses its team's default. Changing the team inside the composer preserves the current audience rather than applying the new team's default. For example, choosing a team while the audience is Workspace leaves it Workspace-visible. Review and explicitly change the audience before sending if needed. Team visibility requires a team. If the workspace requires team ownership and you have no eligible membership, the composer says Join a team to create a session. See Teams.

Ownership is fixed when the session is created. Workspace visibility does not remove team ownership, and changing the sidebar's discovery scope is not a way to transfer a session. Private access is enforced in every deployment mode, but non-private Team read isolation requires TEAMS_ENFORCEMENT=on; the default is shadow. See Multiplayer and sharing and Deployment.

Explicit team and audience choices are remembered in user-scoped localStorage in this browser and restored when you return, but only while the sidebar context matches. Changing sidebar scope discards that saved choice and uses the new context's defaults. Composer choices do not change sidebar scope. Invalid stored choices are ignored, and team selection is rechecked against current memberships and the required-team policy.

Above the text area, the target picker decides what the sandbox works on. Its search field reads "Search environments and repositories...". Choices reflect the selected team context and your access. Choose one of:

TargetWhat you get
A single repositoryOne clone. A branch selector appears beside the picker, preselected to the repository's default branch.
Multiple repositoriesAn ad-hoc ordered set of up to 10 repositories, chosen with a "Choose repositories" control. The first is the primary. Each is cloned at its default branch. Ad-hoc sets do not get prebuilt images.
An environmentA saved repository set with a base branch per repository, its own secrets, and optional prebuilt images. Environments are listed first when any exist.
No repositoryAn empty sandbox for scratch work ("Start without cloning a repository").

A team-owned environment can launch only into a session owned by that same team. Eligible workspace-owned environments can also appear in a team's catalog, but all their repositories must satisfy that team's grants. Check both the owning team and the environment before sending.

Secrets resolve from global values, then the owning team's values (if any), then the target environment or selected repositories; later values override earlier ones. Environment sessions do not inherit their member repositories' secrets. In an ad-hoc set the primary repository wins duplicate keys, and the composer offers to save the set as an environment. See Secrets.

If the picker says "No repositories found", check the selected team's repository grants as well as the deployment's repository access (for GitHub, the App installation and its repository selection). Installation access alone does not grant a team access. You can start without a repository if your role and team-creation policy allow it.

Choose the model and reasoning effort

The model menu sits in the composer's footer. It lists only models enabled under Settings › Models. Picking a model resets the reasoning effort to that model's default; the effort options depend on the model, and models without configurable effort show none.

The same menu has an Agent row that selects the harness:

  • OpenCode is the default and runs every enabled model.
  • Claude Agent runs Anthropic models only. It is the harness that can use a connected Claude account instead of an API key.
  • Codex runs the OpenAI models that support it, with an OpenAI API key or a connected ChatGPT account.

The model list is filtered to what the chosen harness can run. The harness is fixed when the session is created.

The composer remembers your last model, effort, harness, and provider choices in this browser.

If your deployment has connected provider accounts

When the selected model belongs to OpenAI, xAI, or Anthropic, a provider authentication menu appears beside the skill selector even if no account is connected. "Use default" follows the deployment's policy; you can select a connected account only if one is available and the harness supports it, or choose "No account" for API-key mode. OpenCode runs Anthropic on an API key, not a connected Claude account.

Choose skills

The skill selector sits beside the model menu. Managed skills are reusable instruction files that administrators assign to repositories, environments, or globally.

SelectionResult
All applicableEvery enabled skill whose assignment matches the target. This is the default.
None"Start without managed skills."
Personal profileThe enabled, applicable skills saved in one of your profiles.

The number beside the selector previews how many skills will be installed. Skills are pinned at session creation; a later edit to a skill does not change an existing session. See Managed skills.

Attach images if useful

Click the paperclip ("Attach images"), paste, or drag files onto the composer. Accepted formats are PNG, JPEG, WebP, and GIF, up to 6 images per message and 10 MiB each. Attachments are useful for a screenshot of a bug, a design mock, or an error dialog. See Attaching images.

Send a bounded first request

A good first prompt names one outcome, the place in the code it concerns, and how the agent should verify the result. Keep the scope small enough to review in a few minutes. Good vs. bad prompts shows the difference for eight common task types.

In packages/web, the "Copy link" button on the session header does not show any confirmation after copying. Add a brief "Copied" state on the button for two seconds after a successful copy, matching how the branch-name copy button in the sidebar behaves. Add or update the component test, run the web test suite for the files you touched, and report the command you ran and its result. Do not open a pull request yet.

Unsent prompt text is saved separately from team/audience preferences, in this tab's sessionStorage for your account. It returns after a reload or navigation back in the same tab. A successful send clears the submitted draft; a failed send keeps it. Emptying the prompt or successfully signing out clears it, and storage ends with the tab. Attachments are not part of this text draft. If browser storage is unavailable, the text stays only in memory.

Send with the send button or Cmd/Ctrl+Enter (the default keyboard shortcut; it can be customized). Typing in the composer already starts warming a sandbox ("Warming sandbox..." appears beside the send button), so the session is often ready by the time you send. Restoring a saved draft alone does not start warming; the next input change can, or sending creates the session directly. You are taken to the session page at /session/<id>.

Watch the boot

The session header names each boot phase as it runs:

  1. Starting runtime
  2. Cloning repository (all repositories in a multi-repository session)
  3. Running setup.sh (.openinspect/setup.sh, if the repository has one; skipped when starting from a prebuilt image)
  4. Starting services (.openinspect/start.sh, if present)
  5. Installing skills
  6. Starting agent

Multi-repository sessions add the repository name, as in "Running setup.sh for acme/api". A setup.sh failure is reported as a warning and the boot continues; the status popover says which phase failed.

Your prompt waits until the sandbox reports ready, then runs. Closing the browser does not stop the session: the sandbox keeps working, and the session page catches up when you return.

Read the result

When the turn ends, three things tell you what happened:

  • The final response in the timeline. The agent should state what it changed, what it ran, and anything it could not finish.
  • Changes in the right sidebar and the changes panel, which compares the working tree with session start. Use the previous and next file controls and the layout toggle to read the diff.
  • Validation evidence in the timeline: the commands the agent ran and their output, and any screenshots it captured under Media.

If the result is not what you wanted, send a follow-up in the same session. The sandbox state, including installed dependencies and the branch, is preserved.

Troubleshooting

SymptomCauseFix
Access Denied page after signing inYour identity was verified but the workspace's admission rules did not include you.Ask a workspace Owner or Administrator to add you (GitHub user, email, domain, or organization), then sign in again.
"You don't have permission to create sessions."Your role is Viewer.Ask a workspace Owner or Administrator to change your role under Settings › Workspace access.
"No repositories found."The selected team lacks grants, or the source-control integration has no accessible repositories.Check team context and ask a lead or administrator to check grants; ask the operator to check installation access.
"Join a team to create a session." or team_requiredWorkspace policy requires an owning team.Join an eligible team or ask its lead to add you, then choose it in the composer.
environment_team_mismatch or target_team_missing_grantThe environment belongs to another team, or the selected team lacks a repository grant.Choose an environment allowed for this team, or ask a lead or administrator to review repository grants.
Send button disabled with "Select at least one repository"Multiple repositories is selected but the set is empty.Choose at least one repository, or switch to a single repository or No repository.
Model menu is empty or the send fails with a model availability messageNo enabled model can run on the selected harness.Switch the harness to OpenCode, or ask a workspace Owner or Administrator to enable a model under Settings › Models.
Boot stops with a failed phasestart.sh in the primary repository exited non-zero, or the boot exceeded its budget.Read the header's status popover for the phase, fix the script, and send the prompt again to start a new sandbox.

Next steps

On this page