> For the complete documentation index, see [llms.txt](https://docs.warpstream.com/warpstream/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.warpstream.com/warpstream/getting-started/run-the-agent-locally.md).

# Run the Agents Locally

First, [install the WarpStream Agent](/warpstream/getting-started/install-the-warpstream-agent.md) for your platform.

## Playground vs. Local

There are two ways to run WarpStream locally:

1. `playground` mode
2. `local` mode

`playground` mode is designed for interactive local development. It signs up for a temporary WarpStream account that is valid for a few hours, starts a local Agent with an embedded Kafka cluster, Schema Registry cluster, and Tableflow cluster, and uses the real hosted WarpStream control plane so that you have full access to WarpStream's featureset, API, and UI to explore as much of the product as possible. If you just want to test something manually, or explore the product, this is the best option.

`local` mode is designed for non-interactive local development like automated CI environments. Unlike `playground` mode, `local` mode has no dependency on WarpStream's hosted control plane and instead uses a fake in-memory control plane in the Agent binary itself. This makes it suitable for CI environments where hundreds or even thousands of ephemeral WarpStream clusters need to be spawned simultaneously without being subjected to ratelimits.

{% hint style="warning" %}
Both `playground` and `local` mode store data in memory, so any data written will no longer be accessible once the process exits. They're also heavily ratelimited in terms of the amount of Kafka traffic they can handle and are not suitable at all for benchmarking.
{% endhint %}

## Docker

{% tabs %}
{% tab title="Playground" %}
{% code overflow="wrap" %}

```bash
docker run -p 8080 -p 9092:9092 -p 9094:9094 public.ecr.aws/warpstream-labs/warpstream_agent:latest playground
```

{% endcode %}
{% endtab %}

{% tab title="Local" %}
{% code overflow="wrap" %}

```bash
docker run -p 8080 -p 9092:9092 -p 9094:9094 public.ecr.aws/warpstream-labs/warpstream_agent:latest local
```

{% endcode %}
{% endtab %}
{% endtabs %}

Once the docker container is running, there will be a Kafka TCP server listening on port 9092 and a Schema Registry HTTP server listening on port 9094.

This means you're ready to run any application locally that expects to connect to Kafka, and it'll connect to WarpStream instead if you set the bootstrap URL to `localhost:9092`.

You can also replace the URL of your schema registry clients to `localhost:9094` and it'll connect to WarpStream's Schema Registry instead.

If you encounter any problems connecting an application running *outside* of Docker to the WarpStream agent running inside of Docker, follow [our instructions below for diagnosing connection issues](#diagnosing-connection-issues).

## Standalone Binary

Alternatively, if you installed the standalone WarpStream Agent binary and it is in your `PATH`, you can just run:

{% tabs %}
{% tab title="Playground" %}
{% code overflow="wrap" %}

```bash
warpstream playground
```

{% endcode %}
{% endtab %}

{% tab title="Local" %}
{% code overflow="wrap" %}

```bash
warpstream local
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Both `playground` and `local` mode store data in memory, so any data written will no longer be accessible once the process exits.
{% endhint %}

Once that completes, run the following command to test the Kafka connection:

{% code overflow="wrap" %}

```bash
warpstream kcmd -type diagnose-connection -bootstrap-host localhost -bootstrap-port 9092
```

{% endcode %}

If that succeeds, then you're ready to run any application locally that expects to connect to Apache Kafka, and it'll connect to WarpStream instead if you set the bootstrap URL to `localhost:9092`.

If the diagnostic command returns an error, follow the provided instructions to diagnose and fix it.

To test the Schema Registry connection, you can send a request to the server with `curl` as follows:

```bash
curl -X POST "http://localhost:9094/subjects/foo/versions" \
     -H "Content-Type: application/json" \
     -d '{"schema": "{\"type\":\"long\"}"}'
```

If you receive a valid response, such as `{"id":1}`, then you're ready to run any application locally that expects to connect to a schema registry by replacing schema registry URL with `localhost:9094`.

## SASL and ACLs in Local Mode

`local` mode can start with named SASL users and Kafka ACL enforcement. This is intended for CI and integration tests that need allow/deny behavior without the hosted WarpStream control plane or console.

{% hint style="info" %}
These flags are only available on `warpstream local`. In `playground` mode, create credentials and enable ACLs from the WarpStream console instead. See SASL Authentication and ACLs.
{% endhint %}

#### Flags

| Flag                          | Description                                                                                                                                                                                 |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-saslUser username:password` | Repeatable. Creates a SASL user. Implies SASL authentication. The ACL principal is `User:<username>`. The first `:` splits the username from the password, so passwords may contain colons. |
| `-superUsers`                 | Repeatable, or comma-separated. Marks those SASL usernames as cluster superusers. Each name must match a `-saslUser` username. Superusers bypass ACL checks.                                |
| `-enableACLs`                 | Turns on Kafka ACL enforcement. Requires SASL and at least one superuser.                                                                                                                   |
| `-requireSASLAuthentication`  | Existing flag. If you set this without `-saslUser`, `local` mints a single auto-generated superuser and prints the username and password at startup.                                        |

`-saslUser` implies SASL even if you omit `-requireSASLAuthentication`.

{% hint style="warning" %}
`-enableACLs` is rejected unless SASL is on and at least one superuser exists. Once ACLs are enabled, Kafka is default-deny: only superusers can access a resource that has no matching ACL.
{% endhint %}

#### Start a local cluster with ACLs

{% tabs %}
{% tab title="Standalone Binary" %}
{% code overflow="wrap" %}

```bash
warpstream local \
  -saslUser admin:admin-secret \
  -saslUser alice:alice-secret \
  -saslUser bob:bob-secret \
  -superUsers admin \
  -enableACLs
```

{% endcode %}
{% endtab %}

{% tab title="Docker" %}
{% code overflow="wrap" %}

```bash
docker run -p 8080 -p 9092:9092 -p 9094:9094 \
  public.ecr.aws/warpstream-labs/warpstream_agent:latest \
  local \
  -saslUser admin:admin-secret \
  -saslUser alice:alice-secret \
  -saslUser bob:bob-secret \
  -superUsers admin \
  -enableACLs
```

{% endcode %}
{% endtab %}
{% endtabs %}

Connect Kafka clients with SASL/PLAIN (or SASL/SCRAM-SHA-512) using those usernames and passwords. For example, `admin` / `admin-secret` authenticates as principal `User:admin`.

## Diagnosing Connection Issues

The WarpStream Agent binary ships with a utility for diagnosing connection issues. However, diagnosing connection issues cannot be done in a general purpose manner from within a Docker container. Therefore even if you're running the Agent in a Docker container locally, you'll need to follow our ["Installation Script" Agent installation instructions](/warpstream/getting-started/install-the-warpstream-agent.md) to install the raw WarpStream Agent binary locally before proceeding.

Once the binary is installed, run the following command to test the connection:

{% code overflow="wrap" %}

```bash
warpstream kcmd -type diagnose-connection -bootstrap-host localhost -bootstrap-port 9092
```

{% endcode %}

If that succeeds, then you're ready to run any application locally that expects to connect to Apache Kafka, and it'll connect to WarpStream instead if you set the bootstrap URL to `localhost:9092`.

If the diagnostic command returns an error, follow the provided instructions to diagnose and fix.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.warpstream.com/warpstream/getting-started/run-the-agent-locally.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.