---
title: "Run the examples"
url: "https://docs.yugabyte.com/stable/explore/cluster-setup-local/"
---

# Run the examples

Set up clusters to run Explore examples.

Set up YugabyteDB to run Explore examples

Docs MCP Server

Developing with YugabyteDB? Access the YugabyteDB Docs AI from your IDE or CLI. See [Docs MCP Server](/stable/reference/docs-mcp-server/ "Docs MCP Server").

Use the following instructions to set up universes for running the examples in Explore.

- [![Server Icon](/icons/database.svg) Local](/stable/explore/cluster-setup-local/)
- [![Cloud Icon](/icons/cloud.svg) YugabyteDB Aeon](/stable/explore/cluster-setup-aeon/)
- [![Server Icon](/icons/server.svg) YugabyteDB Anywhere](/stable/explore/cluster-setup-anywhere/)

## Set up YugabyteDB universe

You can run examples using a universe set up on your local machine, assuming you have [Installed](/stable/quick-start/linux/ "Installed") YugabyteDB.

Use the [yugabyted](/stable/reference/configuration/yugabyted/ "yugabyted") utility to create and manage universes.

### Single-node universe

If a local universe is currently running, first [destroy it](/stable/reference/configuration/yugabyted/#destroy-a-local-universe "destroy it").

You can create a single-node local universe with a replication factor (RF) of 1 by running the following command:

```sh
./bin/yugabyted start --advertise_address=127.0.0.1
```

Or, if you are running macOS Monterey, use the following command:

```sh
./bin/yugabyted start --advertise_address=127.0.0.1 \
                      --master_webserver_port=9999
```

To check the status of a running single-node universe, run the following command:

```sh
./bin/yugabyted status
```

For more information, refer to [Quick Start](/stable/quick-start/linux/#create-a-local-cluster "Quick Start").

### Multi-node universe

The following instructions show how to *simulate* a multi-node universe on a single computer. To deploy an actual multi-zone universe using yugabyted, follow the instructions in [Create a multi-zone cluster](/stable/reference/configuration/yugabyted/#create-a-multi-zone-cluster "Create a multi-zone cluster").

Set up a local cluster

If a local universe is currently running, first [destroy it](/stable/reference/configuration/yugabyted/#destroy-a-local-universe "destroy it").

Start a local three-node universe with an RF of `3` by first creating a single node, as follows:

```bash
./bin/yugabyted start \
                --advertise_address=127.0.0.1 \
                --base_dir=${HOME}/var/node1 \
                --cloud_location=aws.us-east-2.us-east-2a
```

On macOS, the additional nodes need loopback addresses configured, as follows:

```sh
sudo ifconfig lo0 alias 127.0.0.2
sudo ifconfig lo0 alias 127.0.0.3
```

Next, join more nodes with the previous node as needed. `yugabyted` automatically applies a replication factor of `3` when a third node is added.

Start the second node as follows:

```sh
./bin/yugabyted start \
                --advertise_address=127.0.0.2 \
                --base_dir=${HOME}/var/node2 \
                --cloud_location=aws.us-east-2.us-east-2b \
                --join=127.0.0.1
```

Start the third node as follows:

```sh
./bin/yugabyted start \
                --advertise_address=127.0.0.3 \
                --base_dir=${HOME}/var/node3 \
                --cloud_location=aws.us-east-2.us-east-2c \
                --join=127.0.0.1
```

After starting the yugabyted processes on all the nodes, configure the data placement constraint of the universe, as follows:

```sh
./bin/yugabyted configure data_placement --base_dir=${HOME}/var/node1 --fault_tolerance=zone
```

This command can be executed on any node where you already started YugabyteDB.

To check the status of a running multi-node universe, run the following command:

```sh
./bin/yugabyted status --base_dir=${HOME}/var/node1
```

## Connect to universes

To run the examples in your universe, you use either the ysqlsh or ycqlsh CLI to interact with YugabyteDB via the YSQL or YCQL API.

You can start ysqlsh as follows:

```sh
./bin/ysqlsh
```

```output
ysqlsh (15.2-YB-2026.1.2.0-b0)
Type "help" for help.

yugabyte=#
```

You can start ycqlsh as follows:

```sh
./bin/ycqlsh
```

```output
Connected to local cluster at 127.0.0.1:9042.
[ycqlsh 5.0.1 | Cassandra 3.9-SNAPSHOT | CQL spec 3.4.2 | Native protocol v4]
Use HELP for help.
ycqlsh>
```

## Set up YB Workload Simulator

YB Workload Simulator is a Java application that simulates workloads against YugabyteDB and provides live metrics of latency and throughput from the application's point of view.

The application is used to demonstrate the following Explore topics:

- [Horizontal scalability](/stable/explore/linear-scalability/scaling-universe/ "Horizontal scalability")
- [Resiliency](/stable/explore/fault-tolerance/macos/ "Resiliency")
- [Multi-region deployment](/stable/explore/multi-region-deployments/synchronous-replication-ysql/ "Multi-region deployment")

The application uses the YugabyteDB JDBC [Smart Driver](/stable/develop/drivers-orms/smart-drivers/ "Smart Driver"), which features universe- and topology-aware connection load balancing. The driver automatically balances application connections across the nodes in a universe, and rebalances connections when a node fails. For more information, see [YB Workload Simulator](https://github.com/YugabyteDB-Samples/yb-workload-simulator/ "YB Workload Simulator").

### Download

YB Workload Simulator requires Java 11 or later installed on your computer. JDK installers for Linux and macOS can be downloaded from [Oracle](http://jdk.java.net/ "Oracle"), [Adoptium (OpenJDK)](https://adoptium.net/ "Adoptium (OpenJDK)"), or [Azul Systems (OpenJDK)](https://www.azul.com/downloads/?package=jdk "Azul Systems (OpenJDK)"). Homebrew users on macOS can install using `brew install openjdk`.

Download the YB Workload Simulator JAR file using the following command:

```sh
wget https://github.com/YugabyteDB-Samples/yb-workload-simulator/releases/download/v0.0.8/yb-workload-sim-0.0.8.jar
```

### Use the application

To start the application against a running local universe, use the following command:

```sh
java -jar \
    -Dnode=127.0.0.1 \
    ./yb-workload-sim-0.0.8.jar
```

The `-Dnode` flag specifies the IP address of the node to which to connect.

The `-Dspring.datasource` flag enables [topology-aware load balancing](/stable/develop/drivers-orms/smart-drivers/#topology-aware-load-balancing "topology-aware load balancing") for the application connections. If you created a universe using different zones, replace the zones with the corresponding zones in your universe, comma-separated, in the format `cloud.region.zone`.

To view the application UI, navigate to `http://<machine_ip_or_dns>:8080` (for example, `http://localhost:8080`).

### Start a read and write workload

You can start a workload that performs read and write operations across all the nodes of the universe as follows:

1. In the [application UI](http://localhost:8080 "application UI"), click the hamburger icon at the top of the page beside Active Workloads for Generic.
2. Select **Usable Operations**.
3. Under **Create Tables**, click **Run Create Tables Workload** to add tables to the database.
4. Under **Seed Data**, click **Run Seed Data Workload** to add data to the tables.
5. Under **Simulation**, select the **Include new Inserts** option, and click **Run Simulation Workload**.
6. Click **Close**.

The Latency and Throughput charts show the workload running on the universe.