OpenSearch Dashboards: what the repository actually gives you

The gap OpenSearch Dashboards fills, and who it leaves out

OpenSearch stores and aggregates data, but it has no user interface of its own for exploring that data. OpenSearch Dashboards is the browser layer that sits in front of it. The README describes it as "an open-source data visualization tool designed to work with OpenSearch", and the package.json description is more specific: a "browser based analytics and search dashboard for OpenSearch".

That second phrasing matters more than the first. The project is not a general-purpose BI product that happens to speak OpenSearch. Its query model, its saved-object model and its index-pattern concept all assume an OpenSearch cluster on the other end. If your data lives in a warehouse and you want charts over it, this is the wrong tool and no amount of configuration will make it the right one.

The audience is correspondingly narrow. It is for teams that already operate OpenSearch and need dashboards, saved searches and visualizations over the indices in that cluster. It is also, and this is easy to miss from the README alone, a platform for people who write plugins. The repository carries a plugins/ directory and eighteen example directories under examples/, including embeddable_examples, expressions_example, ui_action_examples and state_management_example. Those exist because the intended extension path is code, not configuration.

How the pieces fit: a Node server, a browser bundle and a plugin registry

The repository is a TypeScript monorepo. The top level holds a src/ tree, a packages/ directory, a plugins/ directory and a config/ directory, with build tooling driven by Yarn. The package.json pins the package manager as [email protected], so the classic Yarn 1 workflow is what the scripts assume.

Runtime is split. A Node process serves the application, and the browser receives a bundle that renders the visualizations. The scripts in package.json reflect that split: "osd" runs scripts/osd and "opensearch" runs scripts/opensearch, so the same checkout can start the Dashboards process and, for development, a local OpenSearch process.

The extension surface is the part that distinguishes this from a packaged appliance. Plugins register against core services, and the examples directory is effectively executable documentation of those registrations. A plugin can contribute embeddables, expressions, UI actions, URL generators or state containers, and each of those has a matching example folder. The types entry point is opensearch_dashboards.d.ts, which is the contract plugin authors compile against.

Configuration is file-driven. The config/ directory is where the server reads its settings from, and the file is opensearch_dashboards.yml. That name is the one people search for, and it is worth being precise: the file is YAML, it lives under config/ in a source checkout, and a packaged distribution places it in the config directory that ships alongside the binary. The README does not document the full key list. The documentation site linked from the README is the place that does.

Installing OpenSearch Dashboards and getting to a first dashboard

The README does not contain install instructions. It links to the Downloads page at opensearch.org/downloads.html and to the documentation at opensearch.org/docs, and it points developers at DEVELOPER_GUIDE.md for a development environment. So there are two legitimate paths, and they are different jobs.

For a running instance, take the packaged artifact from the downloads page and unpack it. The distribution ships a config directory and a start script; the documentation site covers the platform-specific steps. The README is silent on those steps, and it is also silent on upgrade and rollback procedure, which is a real gap if you are planning a production rollout from the repository alone.

For a source build, the developer guide is the entry point. The repository's own scripts are the ones to use rather than raw Node invocations, because the preinstall and postinstall hooks do setup work:

yarn install
yarn osd bootstrap

The first command installs dependencies and triggers the preinstall and postinstall scripts declared in package.json. The second is the bootstrap step the developer guide describes for preparing the checkout. Expect this to take a while and to need network access.

Once the process is running, it listens on a port that you set in config/opensearch_dashboards.yml. The README does not state a default port, so read the file in your distribution rather than assuming one. The same file is where you point the server at your OpenSearch cluster. The documentation covers the accepted key set; the README does not enumerate it, and this article will not invent keys that the repository does not show.

After the server is up, the first real task is defining an index pattern over an index in your cluster, then building a visualization against it and saving that visualization to a dashboard. That is the core loop the product exists to serve, and it is the loop to test before you commit to anything larger.

What the repository does not tell you, and where that hurts

The README is a contributor on-ramp, not an operator manual. It lists project resources, a code of conduct, the license and the copyright notice, and it links outward for everything operational. That is a defensible choice for a project of this size, but it means the repository alone will not answer the questions a deployment team actually has.

Four gaps stand out. First, there is no documented rollback path in the README, so version pinning and backup of saved objects become your problem to design. Second, the README does not state default credentials or a default port, which is why both are common search queries; the answers live in the documentation and in your own config file, not here. Third, the README does not describe a compatibility matrix between Dashboards versions and OpenSearch versions, even though the two are released in lockstep. Fourth, the README gives no sizing guidance, and a Dashboards process that renders heavy visualizations against a large cluster is not free.

There is a structural limitation too. Because the product is coupled to OpenSearch's query and aggregation model, anything that model does not express is awkward to build. If you need a visualization backed by a different engine, or a metric that requires computation outside the cluster, you are writing a plugin rather than configuring a chart. The examples directory shows how, and it also shows how much code that involves.

OpenSearch Dashboards versus Grafana, and versus Kibana

The two comparisons people actually make are Grafana and Kibana, and they fail in different ways.

Grafana is a visualization layer that treats many data sources as first-class, with OpenSearch as one of them. The difference in approach is where the query model lives. Grafana keeps its own panel and data-source abstraction and adapts to each backend. OpenSearch Dashboards does not abstract away OpenSearch; it exposes it. That means Dashboards gets OpenSearch-specific features without a translation layer, and it means you cannot point it at a store that is not OpenSearch. If your dashboards must span OpenSearch and a SQL warehouse in one pane, Grafana's model fits and this one does not.

Kibana is the closer comparison, because the two share an architectural lineage and a plugin-based extension model. The practical difference is the cluster each one targets: Kibana is built for Elasticsearch, Dashboards for OpenSearch. Choosing between them is usually a consequence of which search engine you already run, not an independent decision. The repository does not publish a feature-by-feature comparison, and treating the two as interchangeable because the interfaces look similar is a mistake when plugins and APIs are involved.

A third option worth naming is simply the OpenSearch APIs directly. If your need is a scheduled report or a small internal page, calling the search and aggregation APIs from your own service avoids running a second Node process and its plugin surface entirely.

Licence, maintenance and the cost of keeping up

The project is licensed under Apache-2.0, stated in the README and shipped as LICENSE.txt, with copyright held by OpenSearch Contributors and details in NOTICE.txt. For most adopters that is a permissive licence with the usual obligations around attribution and notice retention. What that means for a modified distribution or for bundling the code into a commercial product is a question for your own legal review; the repository does not answer it and this article should not pretend to.

The repository is not archived, and the most recent push recorded is 2026-07-06. Releases are frequent and versioned in two lines at once: 2.19.6 on 2026-07-06, 3.7.0 on 2026-06-09 and 3.6.0 on 2026-04-14. That cadence is the real upgrade cost. A two-track release line means you must decide early whether you track 2.x or 3.x, and that decision propagates to every plugin you write, because plugins compile against the types in opensearch_dashboards.d.ts and against core services that change between major lines.

The repository carries the machinery for this: changelogs/, release-notes/, a RELEASING.md, a Jenkinsfile and a build_and_test workflow. None of it removes the work of reading release notes before you move a cluster. If you write plugins, budget for a compatibility pass on each major bump; if you only consume the packaged distribution, the upgrade is closer to a redeploy plus a saved-object check.

Editorial conclusion

Adopt OpenSearch Dashboards if you already run OpenSearch and want its query and aggregation model surfaced in a browser, and if you accept that the product is a plugin host first and a finished BI tool second. Do not adopt it as a standalone analytics product over a non-OpenSearch store, and do not expect the repository README to walk you through a production deployment; it points to the documentation site and the downloads page instead. Verify first that a released artifact exists for your platform on the OpenSearch downloads page, that the Dashboards version you pick matches your OpenSearch cluster version, and that you know which config directory your deployment reads config/opensearch_dashboards.yml from. If those three checks pass, the plugin examples under examples/ are the fastest way to judge whether the extension model fits your team.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes