+++
title = "Add Bonsai to your Heroku app"
weight = 162
updated = 2026-10-08
aliases = ["/docs/add-bonsai-to-your-heroku-app.html", "/docs/managed-search/elasticsearch-and-opensearch/deployment/heroku/add-bonsai-to-your-heroku-app/", "/docs/deployment/heroku/add-bonsai-to-your-heroku-app/"]

[extra]
weight = 1
+++

We offer a free Hobby plan for development and testing on Heroku. A list of all available plans and capacities can be found at [https://elements.heroku.com/addons/bonsai#pricing](https://elements.heroku.com/addons/bonsai#pricing).

The free Hobby plan, the Staging plan, and the ephemeral add-ons Heroku creates for Review Apps and CI run OpenSearch 3 only, and can only be added to apps in Heroku's US region (AWS us-east-1). For apps in other regions, such as Europe, choose a Standard or Business plan. See [Choosing a search engine and version](#choosing-a-search-engine-and-version) for what each plan offers.

There are two ways to add Bonsai to your Heroku app:

1.  Through the Heroku CLI tool
2.  Through the Heroku app dashboard

## Using the Heroku CLI tool

You can add Bonsai to your app with this command:

```bash
$ heroku addons:add bonsai
----- Adding bonsai to some-appname-4005... done, v18 (free)
```

You can verify that the operation was successful by running `heroku config:get BONSAI_URL`:

```bash
$ heroku config:get BONSAI_URL
----- [http://username:password@redwood-12345.us-east-1.bonsai.io/](http://username:password@redwood-12345.us-east-1.bonsai.io/)
```

If this value is null, then Bonsai was not properly added to your account. Try again and look for error messages. If you still have problems, [give us a shout](mailto:support@bonsai.io).

Once the Add-on has been successfully added, you can check on the status of your cluster by running

```bash
$ heroku addons:open bonsai -a
```

## Choosing a search engine and version

Bonsai add-ons accept two options, `engine` and `version`. Options are only read when the add-on is created: Heroku has no way to change them on an existing add-on. You can pass them with the Heroku CLI or in your app.json.

On the command line, place options at the end of the command, after a double dash (`--`):

```bash
heroku addons:create bonsai:[plan] [-a APP_NAME] -- --engine=opensearch --version=2
```

Plans are written as `bonsai:<plan>`, for example `bonsai:standard-fir`. Run `heroku addons:plans bonsai` to list every plan, or see [Bonsai on Heroku Elements](https://elements.heroku.com/addons/bonsai#pricing) for what each one offers.

* **`engine`**: `opensearch` or `elasticsearch`. If you leave it out, Bonsai creates an OpenSearch cluster, on every plan.
* **`version`**: a full or partial version, such as `2`, `2.19`, or `7.10.2`. Bonsai provisions the nearest available release within that major version. It never switches to a different major version. If you leave it out, you get the newest release available for your plan, engine, and region.

If the engine or version you ask for isn't available for your plan in your app's region, the add-on is not created. Heroku shows an error that names what you asked for, what is available, and other regions where the plan is available. This applies to every plan, free ones included.

### Region

Bonsai creates your cluster in the AWS region of your Heroku app: Common Runtime apps in the `us` region get us-east-1, and apps in the `eu` region get eu-west-1. Add-ons for apps in a Private Space are provisioned in the space's region. A Heroku app can't change regions, so to use a different region, create the app in that region:

```bash
heroku create --region eu
```

### Using app.json

The same options work in your app.json. Values are strings:

```json
{
  "name": "Small Sharp Tool",
  "description": "This app does one little thing, and does it well.",
  "keywords": [
    "productivity",
    "HTML5",
    "scalpel"
  ],
  "addons" : [
    {
      "plan": "bonsai:[plan]",
      "options": {
        "engine": "opensearch",
        "version": "2"
      }
    }
  ]
}
```

For further help with your app.json and addons, see Heroku's documentation here: [Heroku App JSON Schema](https://devcenter.heroku.com/articles/app-json-schema#add-ons)

### Review Apps and Heroku CI

For Review Apps and CI apps, Heroku replaces the plan in your app.json with Bonsai's review-app plan, but it still passes the options. That plan is a free plan that runs OpenSearch 3, so Bonsai is only available to Review Apps and CI apps in Heroku's US region. Remove the `engine` and `version` options from your Review App configuration unless they match what that plan offers (OpenSearch 3), or the add-on won't be created.

## Using the Heroku dashboard

To add Bonsai through the Heroku UI, open up your application in the Heroku dashboard.

{{ image(src="heroku-dashboard.png", alt="Heroku Dashboard", automatically_determine_ratio=true) }}

Click on either the Resources tab, or the “Configure Add-ons” link. This menu will have a search bar for various Add-ons. Begin typing “bonsai,” and the autocomplete will find the Bonsai Elasticsearch Add-on:

{{ image(src="heroku-resources-search.png", alt="Searching for Bonsai in Heroku Resources tab", automatically_determine_ratio=true) }}

Click on the Add-on to add it to your application. This will bring up a new screen where you will be able to select a payment plan for your new cluster. See the [Bonsai Heroku Add-ons](https://elements.heroku.com/addons/bonsai#pricing) page for details about what each plan offers.

{{ image(src="heroku-dashboard-provision.png", alt="Heroku dashboard showing provision button", automatically_determine_ratio=true) }}

When you are ready, click on “Provision.” Your new cluster will be instantly created. Your dashboard will now show this:

{{ image(src="heroku-dashboard-provisioned.png", alt="Heroku dashboard showing provisioned Bonsai cluster", automatically_determine_ratio=true) }}

When Bonsai is added to your application, a new environment variable called `BONSAI_URL` is created and initialized with the URL to your cluster. This is the URL that you will need in order to interact with your cluster.

Your application should be configured to read this URL directly from the environment, and should not be hard-coded or shared with others. If you would like to confirm that Elasticsearch is up and running, you can retrieve the URL by clicking no the Settings tab in the Heroku Dashboard.

There will be a section called “Config Vars”:

{{ image(src="heroku-config-vars-section.png", alt="Heroku Settings Config Vars section", automatically_determine_ratio=true) }}

Click on “Reveal Config Vars” to see your environment variables. This will reveal the value of each variable like so:

{{ image(src="heroku-revealed-config-vars.png", alt="Heroku revealed Config Vars showing BONSAI_URL", automatically_determine_ratio=true) }}

You can copy the contents of the `BONSAI_URL` to your clipboard and paste it into a browser or curl command to see the response from Elasticsearch:

{{ image(src="json-inspection.png", alt="inspecting json response", automatically_determine_ratio=true) }}

```bash
$ curl https://username:password@somehost-1234567.us-east-1.bonsai.io
{
  "name" : "PvRcoFq",
  "cluster_name" : "elasticsearch",
  "cluster_uuid" : "DNlbVYS0TIGYwbQ6CUNwTw",
  "version" : {
    "number" : "5.4.3",
    "build_hash" : "eed30a8",
    "build_date" : "2017-06-22T00:34:03.743Z",
    "build_snapshot" : false,
    "lucene_version" : "6.5.1"
  },
  "tagline" : "You Know, for Search"
}
```

**HTTP 401: Authentication required**

If you're seeing this message, then you're not including the correct authentication credentials in your request. For more details, see [401 Authorization Required](@/docs/troubleshooting/http-errors/http-401-authorization-required/index.md). Double check that the request includes the credentials shown in your dashboard and try again.

### Keep Your URL Secret

Because the URL includes authentication information, anyone with the fully-qualified URL can access your cluster. Treat the URL like a password: don't hard-code it into applications, don't check it into source control, and for Pete's sake, never ever paste it into a StackOverflow question. If you need to share your cluster URL with us for support purposes, the auth-less host name is all you need:

Bad: “My cluster is `https://username:password@somehost-1234567.us-east-1.bonsaisearch.net`”

Good: “My cluster is `somehost-1234567`”

If your URL is leaked somehow, you can regenerate the credentials.

Adding Bonsai to your app automatically creates a cluster for you. It also adds a variable called `BONSAI_URL` to your application's environment, which will contain the canonical URL and credentials to your cluster. This automation makes it fast and easy to get started with your new cluster.