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

# OpenHands integration guide

[OpenHands](https://www.openhands.dev/) is an open-source, model-agnostic AI agent platform for software development that executes real engineering work end-to-end across your codebase. Follow the steps below to connect OpenHands with a model hosted on SambaCloud.

## Prerequisites

Before starting, ensure you have:

* A [SambaCloud](https://cloud.sambanova.ai/?utm_source=openhands\&utm_medium=external\&utm_campaign=cloud_signup) account and [API key](https://cloud.sambanova.ai/apis?utm_source=openhands\&utm_medium=external\&utm_campaign=cloud_signup)
* Access to [OpenHands Cloud](https://app.all-hands.dev) or a self-hosted OpenHands instance

If you plan to use Agent Canvas, you also need Node.js 22.12+ and [`uv`](https://docs.astral.sh/uv/getting-started/installation/).

## Setup

Follow the steps below to connect OpenHands with a SambaNova model through the settings panel.

<Steps>
  <Step title="Open LLM settings in OpenHands">
    Log in to OpenHands and navigate to **Settings**.

    Open the **Language Model (LLM)** section and click **Advanced** to reveal the custom model configuration fields.
  </Step>

  <Step title="Add SambaNova as a custom model">
    Enter your SambaNova model using the `sambanova/` prefix.

    Example:

    ```text theme={}
    sambanova/MiniMax-M2.7
    ```

    Verify the following settings:

    * **Custom Model**: `sambanova/<model-name>`
    * **Base URL**: `https://api.sambanova.ai/v1`
    * **API Key**: Your SambaNova API key

    Click **Save Changes** after completing the configuration.
  </Step>

  <Step title="(Optional) Configure an organization-wide default">
    If you are an OpenHands Cloud organization administrator, you can configure SambaNova as the default model for your team.

    Navigate to **Settings → LLM Profiles** and create a new profile using the same:

    * **Custom Model**
    * **Base URL**
    * **API Key**

    Set the profile as the organization default. Team members can still override the setting with personal configurations if needed.
  </Step>

  <Step title="(Optional) Configure an organization-wide default">
    If you are an OpenHands Cloud organization administrator, you can configure SambaNova as the default model for your team.

    Hover over your profile icon in the lower left, select **Organization**, then select the **LLM** tab. Configure the same values from Step 2:

    * **Custom Model**: `sambanova/<model-name>`
    * **Base URL**: `https://api.sambanova.ai/v1`
    * **API Key**: Your SambaNova API key

    Click **Save Changes**. All organization members will use this LLM configuration unless they configure personal overrides.
  </Step>

  <Step title="Start using SambaNova models">
    Create a new conversation in OpenHands and assign a software engineering task, such as:

    * *Find and fix the bug in my Python script*
    * *Write unit tests for this function*
    * *Refactor this code to use async/await*

    OpenHands will use your selected SambaNova model to plan, write code, execute commands, and iterate on solutions.
  </Step>
</Steps>

## Self-hosted and Docker configuration

If you're running OpenHands with Docker, configure SambaNova using environment variables:

```bash theme={}
docker run -d \
  -p 3000:3000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e LLM_MODEL="sambanova/MiniMax-M2.7" \
  -e LLM_BASE_URL="https://api.sambanova.ai/v1" \
  -e LLM_API_KEY="<your-sambanova-api-key>" \
  --name openhands \
  docker.all-hands.dev/all-hands-ai/openhands:latest
```

Open `http://localhost:3000` in your browser to access the OpenHands interface. To view logs, run `docker logs openhands`.

<Note>
  To pin a specific version instead of `latest`, check the current stable tag on the [OpenHands releases page](https://github.com/All-Hands-AI/OpenHands/releases) (for example, `1.8.0`).
</Note>

## Agent Canvas

[Agent Canvas](https://docs.openhands.dev/openhands/usage/agent-canvas/setup) is a lightweight local runner for OpenHands that you can install via npm or Docker.

**Install via npm** (requires Node.js 22.12+ and [`uv`](https://docs.astral.sh/uv/getting-started/installation/) – Agent Canvas uses a Python runtime under the hood, managed by `uv`):

```bash theme={}
npm install -g @openhands/agent-canvas
agent-canvas
```

**Or run via Docker:**

```bash theme={}
mkdir -p ~/projects ~/.openhands

docker run -d \
  --name agent-canvas \
  -p 8000:8000 \
  -v ~/.openhands:/home/openhands/.openhands \
  -v ~/projects:/projects \
  ghcr.io/openhands/agent-canvas:latest
```

Open `http://localhost:8000` in your browser, then navigate to **Settings → LLM** and configure SambaNova as your provider:

* **Custom Model**: `sambanova/<model-name>` (e.g. `sambanova/MiniMax-M2.7`)
* **Base URL**: `https://api.sambanova.ai/v1`
* **API Key**: Your SambaNova API key

## Additional resources

* [OpenHands documentation](https://docs.openhands.dev/overview/): Full setup, configuration, and agent usage reference
* [Agent Canvas](https://docs.openhands.dev/openhands/usage/agent-canvas/setup): Lightweight local runner for OpenHands via npm or Docker
* [Supported SambaCloud models](/en/models/sambacloud-models): List of models available for use with SambaNova