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

# OpenWorker integration guide

[OpenWorker](https://github.com/andrewyng/openworker) is an open-source AI coworker that runs on your desktop and delivers finished work, not just chat: a polished document, a Slack reply with the numbers, an updated calendar, a sorted inbox. It is model-agnostic, so you can bring your own API key for OpenAI, Anthropic, Google, or an open-weight provider, or run fully local with Ollama. Follow the steps below to connect OpenWorker with a model hosted on SambaCloud.

## Prerequisites

Before starting, ensure you have:

* A [SambaCloud](https://cloud.sambanova.ai/?utm_source=openworker\&utm_medium=external\&utm_campaign=cloud_signup) account and [API key](https://cloud.sambanova.ai/apis?utm_source=openworker\&utm_medium=external\&utm_campaign=cloud_signup)
* OpenWorker installed on your machine (see below)

If you plan to run OpenWorker from source, you also need Python 3.10+, Node.js 20+, and the Rust toolchain (via [`rustup`](https://rustup.rs/)) for the desktop shell.

## Install OpenWorker

You can install OpenWorker in one of two ways.

### Option 1: Download the desktop app

Download the latest OpenWorker build for your operating system from the project's [releases page](https://github.com/andrewyng/openworker/releases):

* **macOS**: `.dmg` installer (Apple Silicon)
* **Windows**: `.exe` installer or `.msi` package

Open the downloaded file and follow the standard installation flow for your platform, then launch OpenWorker.

### Option 2: Run from source

Clone the repository and bootstrap a local development environment:

```bash theme={}
git clone https://github.com/andrewyng/openworker
cd openworker

# 1. One-time bootstrap, creates the Python venv at .venv
#    (on Windows, run from Git Bash or WSL)
bash packaging/setup_dev_env.sh

# 2. Start the local agent server
.venv/bin/openworker-server --cwd ~/some/project --port 8765
#    (Windows: .venv\Scripts\openworker-server.exe)

# 3. In a second terminal, start the UI
cd surfaces/gui
npm install
npm run dev        # browser UI on the Vite dev port
```

Once the UI is running, open the URL printed by `npm run dev` in your browser.

<Note>
  `setup_dev_env.sh` builds the virtual environment with whichever `python3` comes first on your `PATH`. The `python3` that ships with macOS is 3.9, which fails with `Package 'coworker' requires a different Python`. Put a 3.10+ `python3` ahead of it before running the script, and delete any `.venv` a failed attempt left behind, because the script reuses an existing one.
</Note>

## Setup

SambaCloud serves an OpenAI-compatible API, so you connect it through OpenWorker's OpenAI provider with a custom endpoint.

<Steps>
  <Step title="Open the provider settings">
    The desktop app opens a **Welcome** screen on first launch that asks you to pick a model provider. The browser UI you get from [Option 2: Run from source](#option-2-run-from-source) does not show it, and neither does the desktop app once you have dismissed it. In both of those cases, open **Settings** and select the **Models** section instead.
  </Step>

  <Step title="Point the OpenAI provider at SambaCloud">
    Select **OpenAI** from the provider list, then:

    1. In **OpenAI API key**, paste your SambaCloud API key.
    2. Click **Custom endpoint** to expand it, and enter `https://api.sambanova.ai/v1` in the field. This is what sends requests to SambaCloud instead of `api.openai.com`.
    3. Click **Test**.

    The form has no separate save button. **Test** checks the key against the endpoint and saves both fields, then returns to the provider list with the card marked **✓ Connected**. If the test fails, nothing is saved.

    In the **Welcome** flow, continue with **Next** once the card shows **✓ Connected**. The **Skip setup** link answers with "Nothing works without a model" whether or not you have saved a provider, so ignore that prompt if your key is already in — you can skip the remaining connector steps safely.

    The check lists the models at that endpoint rather than running a completion, so a key that SambaCloud no longer accepts for inference can still pass it.

    <Frame>
      <img src="https://mintcdn.com/sambanova-systems/vcvNoUQva9JfefDk/images/docs/integrations/openworker/openworker-openai-endpoint.png?fit=max&auto=format&n=vcvNoUQva9JfefDk&q=85&s=55e1607aab760616a9b2560f9a34c7e7" alt="OpenWorker Welcome screen with the OpenAI provider connected, the key tested and saved, and the custom endpoint set to the SambaCloud API" width="1800" height="1065" data-path="images/docs/integrations/openworker/openworker-openai-endpoint.png" />
    </Frame>
  </Step>

  <Step title="Add a SambaCloud model">
    Saving the key does not change the model list: the picker still offers only the OpenAI models OpenWorker curates, and none of them exist on SambaCloud. Add the model you want as a custom entry, for example `MiniMax-M2.7`.

    Type the model ID exactly as SambaCloud publishes it, with no prefix. Models added under the OpenAI provider are stored as typed and sent to the endpoint unchanged. See [Supported SambaCloud models](/docs/en/models/sambacloud-models) for the full list of model IDs.

    The new row carries a **Make default** button. Click it to use the model for every new session, or leave the default alone and pick the model per session from the model button in the composer. Until you do one of the two, OpenWorker keeps a GPT model as the default and every task fails with `model_not_found`.

    Deselect the GPT models in the same list once your SambaCloud model is the default. They stay in the picker otherwise, and choosing one sends an OpenAI model ID to SambaCloud, which rejects it.

    <Frame>
      <img src="https://mintcdn.com/sambanova-systems/vcvNoUQva9JfefDk/images/docs/integrations/openworker/openworker-models-default.png?fit=max&auto=format&n=vcvNoUQva9JfefDk&q=85&s=6da311752d0ddbbf4592f806460d32e6" alt="Settings Models pane with MiniMax-M2.7 selected and badged as the default, and the four OpenAI GPT models deselected" width="1800" height="1065" data-path="images/docs/integrations/openworker/openworker-models-default.png" />
    </Frame>
  </Step>

  <Step title="Delegate work to OpenWorker">
    Open a new task in OpenWorker and describe the finished deliverable you want, such as:

    * *Draft a status update from the last week of activity in this project folder*
    * *Reply to the latest thread in my Slack #launch channel with the current KPI numbers*
    * *Triage my inbox and archive newsletters, then summarize the rest*

    OpenWorker will plan the steps, call the SambaNova model, use the integrations you have connected, and return the finished artifact.

    <Frame>
      <img src="https://mintcdn.com/sambanova-systems/vcvNoUQva9JfefDk/images/docs/integrations/openworker/openworker-session-minimax.png?fit=max&auto=format&n=vcvNoUQva9JfefDk&q=85&s=16fd7bc112b2e9b8b66aa19740453853" alt="An OpenWorker session answering on MiniMax-M2.7, shown under the session title and in the composer's model button" width="1800" height="1065" data-path="images/docs/integrations/openworker/openworker-session-minimax.png" />
    </Frame>
  </Step>
</Steps>

## Configure the agent server from the command line

If you are running OpenWorker from source, you can set the startup model with the `--model` flag instead of using the model picker:

```bash theme={}
.venv/bin/openworker-server --cwd ~/some/project --port 8765 --model MiniMax-M2.7
```

Then start the UI as shown in [Option 2: Run from source](#option-2-run-from-source).

To make a SambaCloud model the startup model for every run, set it in the global config file rather than passing `--model` each time:

```toml theme={}
# macOS and Linux: ~/.config/coworker/config.toml
# Windows:         %APPDATA%\coworker\config.toml
model = "MiniMax-M2.7"
```

The endpoint is not configurable through the environment. It comes from the OpenAI provider profile you save in **Settings > Models**, so complete the setup steps above at least once before driving the server from the command line.

<Note>
  Both `--model` and `model =` set the startup model only. The moment you pick a model in **Settings > Models**, OpenWorker saves that choice next to the config file, in `prefs.json`, and the saved choice wins on every later launch. From then on `--model` and `model =` are ignored, with no message on startup. Change the model in the UI instead, or delete the `default_model` entry from `prefs.json`.
</Note>

<Warning>
  OpenWorker reads `OPENAI_API_KEY` from the environment before the key you saved in **Settings > Models**. If you already export an OpenAI key for other tools, unset it in the shell you start the server from. Otherwise that key is sent to `https://api.sambanova.ai/v1` and every request fails with `invalid_api_key`. The desktop app does not inherit your shell environment, so this affects the from-source path.
</Warning>

<Note>
  OpenWorker runs locally on your machine. Your data leaves your device only through the model provider and the integrations you explicitly connect. When using SambaCloud, prompts and completions are sent to `https://api.sambanova.ai/v1`.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Every task fails with model_not_found">
    OpenWorker still has a GPT model set as the default. Go to **Settings > Models**, click **Make default** on your SambaCloud model, and deselect the GPT models so the picker can't send an OpenAI model ID to SambaCloud.
  </Accordion>

  <Accordion title="Requests fail with invalid_api_key">
    OpenWorker reads `OPENAI_API_KEY` from the environment before the key saved in **Settings > Models**. Unset it in the shell you start the server from, or your other OpenAI key gets sent to `https://api.sambanova.ai/v1` instead. This only affects the from-source path.
  </Accordion>

  <Accordion title="The server ignores --model or model =">
    OpenWorker saved your last **Settings > Models** choice to `prefs.json`, and the saved model wins on every later launch with no startup message. Change the model in the UI, or delete the `default_model` entry from `prefs.json`.
  </Accordion>

  <Accordion title="setup_dev_env.sh fails with Package 'coworker' requires a different Python">
    The script built the virtual environment with the system `python3`, which is 3.9 on macOS. Put a 3.10+ `python3` ahead of it on your `PATH`, delete the `.venv` the failed attempt left behind, and rerun the script.
  </Accordion>
</AccordionGroup>

## Additional resources

* [OpenWorker on GitHub](https://github.com/andrewyng/openworker): Source code, releases, and issue tracker
* [OpenWorker releases](https://github.com/andrewyng/openworker/releases): Prebuilt desktop installers for macOS and Windows
* [Supported SambaCloud models](/docs/en/models/sambacloud-models): Model IDs you can add to OpenWorker as custom models