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

# Installation

> Install Sovara and prepare your local development environment.

Install the Sovara CLI first so you can check whether an existing Sovara
environment is already available. Then choose a local, remote, or headless
setup and install the SDK for your agent's language.

## Sovara CLI

Sovara's CLI gives you terminal access to run inspection, trace queries, logs,
and shared skill guidance. The Python SDK and TypeScript SDK do not install the
`sovara` command.

<Tabs>
  <Tab title="macOS, Linux, WSL">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -fsSL https://apps.sovara-labs.com/cli/install.sh | sh
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    ```powershell theme={"theme":{"light":"github-light","dark":"github-dark"}}
    irm https://apps.sovara-labs.com/cli/install.ps1 | iex
    ```
  </Tab>

  <Tab title="Windows CMD">
    ```cmd theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -fsSL https://apps.sovara-labs.com/cli/install.cmd -o install.cmd && install.cmd && del install.cmd
    ```
  </Tab>
</Tabs>

Open a new terminal window if `sovara` is not found immediately, then verify the
installation:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara --version
```

Install the Sovara skill for Codex and Claude Code:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara install-skill --target both
```

## Connect to Sovara

Check the app environment already configured for the CLI:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara status
```

* If `sovara status` succeeds, keep using that environment. You do not need to
  install the desktop app unless you want a local desktop workspace.
* For a local desktop workspace, install and open the desktop app below, sign
  in, and run `sovara status` again.
* For a remote or team deployment, set `SOVARA_APP_SERVER_URL` for CLI app
  commands and run `sovara status` again.
* For a headless or CI agent host, the desktop app is not required. Configure
  the execution-server URL and agent token through the [Python API
  reference](/sdks/python/api-reference) or [TypeScript API
  reference](/sdks/typescript/api-reference).

## Sovara desktop app for local use

The desktop app gives you a local workspace for recording, inspecting, and
improving agent runs. Choose the installer for your operating system.

<div className="install-downloads">
  <div className="install-downloads-header">
    <span>Latest installers</span>
  </div>

  <div className="install-download-grid">
    <section className="install-download-card">
      <div className="install-os-mark">
        <img className="install-os-logo install-os-logo-light" src="https://mintcdn.com/sovaralabs/Okv9wjTZjwBwF8U8/assets/icons/apple-logo-light.svg?fit=max&auto=format&n=Okv9wjTZjwBwF8U8&q=85&s=0d42f86ff0fd8814e0e1280038ea063d" alt="" width="814" height="1000" data-path="assets/icons/apple-logo-light.svg" />

        <img className="install-os-logo install-os-logo-dark" src="https://mintcdn.com/sovaralabs/Okv9wjTZjwBwF8U8/assets/icons/apple-logo-dark.svg?fit=max&auto=format&n=Okv9wjTZjwBwF8U8&q=85&s=d338148007bfc1fa6fff7d173f0cf457" alt="" width="814" height="1000" data-path="assets/icons/apple-logo-dark.svg" />
      </div>

      <div className="install-card-title">macOS</div>
      <p>For Apple Silicon Macs.</p>

      <a className="install-download-link" href="https://apps.sovara-labs.com/api/update/download?platform=darwin&arch=arm64">
        Apple Silicon (.dmg)
      </a>
    </section>

    <section className="install-download-card">
      <div className="install-os-mark">
        <img className="install-os-logo install-os-logo-light" src="https://mintcdn.com/sovaralabs/Okv9wjTZjwBwF8U8/assets/icons/windows-logo-light.svg?fit=max&auto=format&n=Okv9wjTZjwBwF8U8&q=85&s=0b631ef53da1ab74b8ff48137ce6b49f" alt="" width="567" height="633" data-path="assets/icons/windows-logo-light.svg" />

        <img className="install-os-logo install-os-logo-dark" src="https://mintcdn.com/sovaralabs/Okv9wjTZjwBwF8U8/assets/icons/windows-logo-dark.svg?fit=max&auto=format&n=Okv9wjTZjwBwF8U8&q=85&s=7ca2a3d1a0be48d9a2c1dcb0c1718f70" alt="" width="567" height="633" data-path="assets/icons/windows-logo-dark.svg" />
      </div>

      <div className="install-card-title">Windows</div>
      <p>For Windows machines.</p>

      <a className="install-download-link" href="https://apps.sovara-labs.com/api/update/download?platform=win32&arch=x64">
        Windows (.exe)
      </a>
    </section>

    <section className="install-download-card">
      <div className="install-os-mark">
        <img className="install-os-logo install-os-logo-light" src="https://mintcdn.com/sovaralabs/Okv9wjTZjwBwF8U8/assets/icons/linux-logo-light.svg?fit=max&auto=format&n=Okv9wjTZjwBwF8U8&q=85&s=93f198d74cb5521bc7bade2ab7d6a59c" alt="" width="960" height="1127" data-path="assets/icons/linux-logo-light.svg" />

        <img className="install-os-logo install-os-logo-dark" src="https://mintcdn.com/sovaralabs/Okv9wjTZjwBwF8U8/assets/icons/linux-logo-dark.svg?fit=max&auto=format&n=Okv9wjTZjwBwF8U8&q=85&s=09aec204496cb7467496408c149d0993" alt="" width="926" height="1089" data-path="assets/icons/linux-logo-dark.svg" />
      </div>

      <div className="install-card-title">Linux</div>
      <p>For Debian/Ubuntu and Fedora/Red Hat-based distributions.</p>

      <a className="install-download-link" href="https://apps.sovara-labs.com/api/update/download?platform=linux&arch=x64&format=deb">
        Debian / Ubuntu Intel/AMD (.deb)
      </a>

      <a className="install-download-link" href="https://apps.sovara-labs.com/api/update/download?platform=linux&arch=arm64&format=deb">
        Debian / Ubuntu arm64 (.deb)
      </a>

      <a className="install-download-link" href="https://apps.sovara-labs.com/api/update/download?platform=linux&arch=x64&format=rpm">
        Fedora / Red Hat Intel/AMD (.rpm)
      </a>

      <a className="install-download-link" href="https://apps.sovara-labs.com/api/update/download?platform=linux&arch=arm64&format=rpm">
        Fedora / Red Hat arm64 (.rpm)
      </a>
    </section>
  </div>
</div>

After the installer finishes, open Sovara and sign in, then verify the local
connection:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara status
```

Keep the desktop app running while using the local workspace. In platform mode,
the CLI and SDKs use the signed-in desktop session instead of asking for an
agent token.

## Python SDK

Install `sovara` in the Python environment where your agent runs. Use the same
package manager that owns your project environment.

<Tabs>
  <Tab title="uv">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    uv add sovara
    ```
  </Tab>

  <Tab title="pip">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    python -m pip install sovara
    ```
  </Tab>

  <Tab title="poetry">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    poetry add sovara
    ```
  </Tab>
</Tabs>

## TypeScript SDK

Install `@sovara/runner` in the Node.js project where your agent runs.

<Tabs>
  <Tab title="npm">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    npm install @sovara/runner
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    pnpm add @sovara/runner
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    yarn add @sovara/runner
    ```
  </Tab>
</Tabs>