Skip to content

Installing Orb control plane

Orb consists of two major components:

  1. The Control Plane—comprised of microservices, communication systems, databases, etc.—deploys to a central location (usually a cloud environment on Kubernetes).
  2. The Orb Agent—a lightweight observability agent—deploys to all the infrastructure you wish to monitor.


The instructions below are for installing the Control Plane. If you just need to install the Orb Agent (orb-agent), see these instructions instead.

The Control Plane can be self-hosted, or you can use our free Orb SaaS service. Self-hosting gives you full privacy and control but is more complex. On the other hand, our SaaS gets you up and running quickly since you only need to create a free account on and then install the Orb Agent to your infrastructure.

The Orb SaaS platform ( is now in active development. This free service allows you to enjoy the benefits of the Orb platform without having to run your own control plane.

If you need to install the Orb Agent to be used with, see these instructions.


Start by cloning the orb project in your local environment using the following command:

git clone

A Kubernetes environment is required for both development environments and production deployment. For development, the kind tool is preferred. For production deployments, use orb-helm.

Port Requirements

In order for the agent to be able to communicate with the control plane, the following outgoing ports must be permitted:

Protocol Port number
MQTT 8883
HTTP 443*

* port 443 is only required if you want the agent to auto-provision

Follow the steps from orb/kind to set up a local k8s cluster and deploy Orb.

Upon successful installation, visit our Getting Started section to keep moving forward with Orb.


To connect an agent to the self-hosted development control plane, disable TLS verification using the environmental variable below in your provisioning command:


See example here.


Is the installation/deployment not working correctly? Found a bug? Come talk to us live on Slack in the #orb channel, or file a GitHub issue here.

Setting up a prometheus sink

In addition to deploying Orb, you can optionally set up a Prometheus instance to act as a metrics data Sink. You may wish to do this if you do not already have an existing time series database to send Orb Policy metric output to, and would like to host your own.

  scrape_interval: 5m
  scrape_timeout:  1m        
  - job_name: "prometheus"
      username: 'MYUSER'
      password: 'MYPASSWORD'

You will need to generate password using htpasswd as described in the prometheus documentation


version: "3"
    image: prom/prometheus:latest
      - 9090:9090
      - "/storage-docker/prometheus/prometheus.yaml:/etc/prometheus/prometheus.yml"
      - "/storage-docker/prometheus/web-config.yaml:/etc/prometheus/web-config.yml"
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--web.config.file=/etc/prometheus/web-config.yml'
      - '--enable-feature=remote-write-receiver'
    image: grafana/grafana:latest
      - 3000:3000
      - prometheus