---
title: How to run the Unleash Proxy
---

import ApiRequest from '@site/src/components/ApiRequest'

:::info Placeholders

Placeholders in the code samples below are delimited by angle brackets (i.e. `<placeholder-name>`). You will need to replace them with the values that are correct in _your_ situation for the code samples to run properly.

:::

The [Unleash Proxy](../generated/unleash-proxy.md) provides a way for you to consume feature toggles in [front-end clients](../reference/sdks/index.md#front-end-sdks), such as the [JavaScript Proxy client](/docs/generated/sdks/client-side/javascript-browser.md) and [React Proxy client](/docs/generated/sdks/client-side/react.md).

Depending on your setup, the Proxy is most easily run in one of two ways, depending on your situation:

-   [Via Docker](#run-proxy-via-docker)
-   [As a Node.js app](#run-proxy-as-node-app)

If you're using a hosted version of Unleash, we can also run the proxy for you.

## Prerequisites

This is what you need before you can run the proxy:

-   A running Unleash server to connect to. You'll need its API path (e.g. `https://app.unleash-hosted.com/demo/api`) to connect the proxy to it.
-   A [client API token](../reference/api-tokens-and-client-keys#client-tokens) for the proxy to use.
-   If you're running the Proxy via Docker: [the `docker` command line tool](https://www.docker.com/).
-   If you're running the Proxy as a Node.js app: [Node.js and its command line tools](https://nodejs.org/).
-   A [Proxy client key](../reference/api-tokens-and-client-keys#proxy-client-keys). This can be any arbitrary string (for instance: `proxy-client-key`). Use this key when connecting a client SDK to the Proxy.

## How to run the Proxy via Docker {#run-proxy-via-docker}

We provide a [Docker image (available on on Docker Hub)](https://hub.docker.com/r/unleashorg/unleash-proxy) that you can use to run the proxy.

### 1. Pull the Proxy image

Use the `docker` command to pull the Proxy image:

```bash title="Pull the Unleash Proxy docker image"
docker pull unleashorg/unleash-proxy
```

### 2. Start the Proxy

When running the Proxy, you'll need to provide it with at least the configuration options listed below. Check the reference docs for the [full list of configuration options](../generated/unleash-proxy.md#configuration-options).

```bash title="Run the Unleash Proxy via Docker"
docker run \
    -e UNLEASH_PROXY_CLIENT_KEYS=<proxy-client-key> \
    -e UNLEASH_URL='<unleash-api-url>' \
    -e UNLEASH_API_TOKEN=<client-api-token> \
    -p 3000:3000 \
    unleashorg/unleash-proxy
```

If the proxy starts up successfully, you should see the following output:

```bash
Unleash-proxy is listening on port 3000!
```

## How to run the Proxy as a Node.js app {#run-proxy-as-node-app}

To run the Proxy via Node.js, you'll have to create your own Node.js project and use the Unleash Proxy as a dependency.

### 1. initialize the project

If you don't already have an existing Node.js project, create one:

```bash npm2yarn
npm init
```

### 2. Install the Unleash Proxy package

Install the Unleash Proxy as a dependency:

```shell npm2yarn
npm install @unleash/proxy
```

### 3. Configure and start the proxy

Import the `createApp` function from `@unleash/proxy` and configure the proxy. You'll need to provide at least the configuration options highlighted below. Check the reference docs for the [full list of configuration options](../generated/unleash-proxy.md#configuration-options).

Here is an example of what running the Proxy as a Node.js app might look like:

```js title="Sample app running the Unleash Proxy"
const port = 3000;

const { createApp } = require('@unleash/proxy');

const app = createApp({
    // highlight-start
    unleashUrl: '<unleash-api-url>',
    unleashApiToken: '<client-api-token>',
    clientKeys: ['<proxy-client-key>'],
    proxyPort: 3000,
    // highlight-end
});

app.listen(port, () =>
    console.log(`Unleash Proxy listening on http://localhost:${port}/proxy`),
);
```

## Verify that the proxy is working

When the proxy process has started up correctly, you can start querying its `/proxy` endpoint. If it's running correctly, you'll get back a JSON object with a list of toggles. The list may be empty if you haven't added any toggles for the corresponding project/environment yet.

<ApiRequest verb="get" url="proxy" endpointType="proxy" title="Request toggles from the Unleash Proxy"/>