> ## 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.

# Quickstart

> Record and inspect your first Sovara run.

When you open the Sovara app for the first time, you will see a tutorial using a pre-recorded example project.
Complete this tutorial before continuing with this section.
In this quickstart, we will record our first own run!

## Create a sample project

Let's create a minimal sample project with a script that calls an LLM.
Open the terminal and create a new folder for that project:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
mkdir sovara-quickstart
cd sovara-quickstart
```

Select which language you want to use below.

<Tabs>
  <Tab title="Python">
    ### Create the Python project file

    Create a `pyproject.toml` in the `sovara-quickstart` folder. `uv run quickstart.py`
    uses this file to install the OpenAI client and the Sovara SDK into the
    project's environment.

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    cat > pyproject.toml <<'EOF'
    [project]
    name = "sovara-quickstart"
    version = "0.1.0"
    description = "Sovara quickstart example."
    requires-python = ">=3.10"
    dependencies = [
        "openai",
        "sovara",
    ]
    EOF
    ```

    ### Create an example script

    Create `quickstart.py` in the project folder.
    You can use the following script which simply calls OpenAI's GPT 5.4 mini.
    It assumes that you have set `OPENAI_API_KEY` as environment variable.
    If this is not the case, you need to modify the script accordingy.

    ```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    from openai import OpenAI
    from sovara import SovaraClient  # [!code ++]

    openai_client = OpenAI()
    sovara_client = SovaraClient(project_name="quickstart")  # [!code ++]

    with sovara_client.run("quickstart run"):  # [!code ++]
        response = openai_client.responses.create(
            model="gpt-5.4-mini",
            input="In one sentence, describe what a good quickstart should do.",
        )
    print(response.output_text)
    ```
  </Tab>

  <Tab title="TypeScript">
    ### Create the TypeScript project file

    Create a `package.json` in the `sovara-quickstart` folder. `npm install` uses
    this file to install the OpenAI client, the Sovara runner, and `tsx`.

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    cat > package.json <<'EOF'
    {
      "name": "sovara-quickstart",
      "version": "0.1.0",
      "type": "module",
      "private": true,
      "dependencies": {
        "@sovara/runner": "latest",
        "openai": "latest",
        "tsx": "latest"
      }
    }
    EOF

    npm install
    ```

    ### Create an example script

    Create `quickstart.ts` in the project folder.
    You can use the following script which simply calls OpenAI's GPT 5.4 mini.
    It assumes that you have set `OPENAI_API_KEY` as environment variable.
    If this is not the case, you need to modify the script accordingly.

    ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
    import OpenAI from "openai";
    import { SovaraClient } from "@sovara/runner"; // [!code ++]

    const openai_client = new OpenAI();
    const sovara_client = new SovaraClient({ projectName: "quickstart" }); // [!code ++]

    await sovara_client.run("quickstart run", async () => { // [!code ++]
      const response = await openai_client.responses.create({
        model: "gpt-5.4-mini",
        input: "In one sentence, describe what a good quickstart should do.",
      });
      console.log(response.output_text);
    }); // [!code ++]
    ```
  </Tab>
</Tabs>

## Record the run

Run the command from the `sovara-quickstart` folder. The Sovara desktop app
should stay open while the command runs.

<Tabs>
  <Tab title="Python">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    uv run quickstart.py
    ```
  </Tab>

  <Tab title="TypeScript">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    npx tsx quickstart.ts
    ```
  </Tab>
</Tabs>

## Inspect the run

Go to the Sovara desktop app. A new project `quickstart` should have been created automatically.
You might need to refresh the projects page at the top right corner to see it.
When you open the project and go to Runs in the side bar, you should see a run called `quickstart run`.

Open the run to inspect its (single) step. You should be able to find the model's input and output, and the print statement which is logged in a tab in the right most panel.