> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stigg.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Running the Sidecar service

## Prerequisites

* Docker
* Redis instance, if a persistent cache is in use

## Usage

Run the service, replacing `<tag>` with the latest version in the [ECR Public Gallery](https://gallery.ecr.aws/stigg/sidecar):

```shell theme={null}
docker run -it -p 80:80 \
  -e SERVER_API_KEY="<FULL_ACCESS_KEY>" \
  public.ecr.aws/stigg/sidecar:<tag>
```

## Sidecar SDK

To interface with the Sidecar service API, use the Sidecar SDK. For details, see:

<Card title="Sidecar SDK" icon="code" horizontal href="/api-and-sdks/integration/backend/sidecar" />

The SDK exposes a convenient `stigg.api` field which returns the same client as the `Stigg.create_client` SDK function. You can:

* Use `stigg.api` wherever you would otherwise use `Stigg.create_client`
* Rely on exactly the same interface and behavior
* Know that the Sidecar SDK depends on the same underlying API client and simply exposes it for convenience

<Warning>
  Since Sidecar SDK version `3.0.0`, the TLS connection method has been deprecated in favor of non-TLS. Please ensure you are running a compatible Sidecar image version `2.494.0` or later. For backwards compatibility details, check the [changelog](https://docs.stigg.io/api-and-sdks/changelog/backend/sidecar#3-0-0). TLS self-signed certificates will **expire on January 26, 2026**, so upgrading the Sidecar image is strongly recommended.
</Warning>

### Available options

Execution of the Sidecar service can be customized using the following **environment variables**:

<ResponseField name="SERVER_API_KEY" type="string" required="true">
  The full access key of the [environment](/documentation/managing-your-account/environments/index).
</ResponseField>

<ResponseField name="API_URL" type="string" default="https://api.stigg.io">
  The URL of the Stigg API.
</ResponseField>

<ResponseField name="EDGE_ENABLED" type="boolean" default="true">
  Whether entitlements will be accessed from [Edge](/documentation/high-availability-and-scale/accessible-from-everywhere).
</ResponseField>

<ResponseField name="EDGE_API_URL" type="string" default="https://edge.api.stigg.io">
  The Edge URL from which entitlements will be accessed.
</ResponseField>

<ResponseField name="WS_ENABLED" type="boolean" default="true">
  Whether to listen for updates using WebSockets.
</ResponseField>

<ResponseField name="WS_URL" type="string" default="wss://api.stigg.io">
  The WebSocket API URL.
</ResponseField>

<ResponseField name="REDIS_ENVIRONMENT_PREFIX" type="string">
  Identifier of the environment, used to prefix the keys in Redis. If provided, Redis will be used as the cache layer.
</ResponseField>

<ResponseField name="REDIS_HOST" type="string" default="localhost">
  Redis host.
</ResponseField>

<ResponseField name="REDIS_PORT" type="number" default="6379">
  Redis port.
</ResponseField>

<ResponseField name="REDIS_DB" type="number" default="0">
  Redis DB identifier.
</ResponseField>

<ResponseField name="REDIS_USERNAME" type="string">
  Redis username.
</ResponseField>

<ResponseField name="REDIS_PASSWORD" type="string">
  Redis password.
</ResponseField>

<ResponseField name="REDIS_TLS" type="boolean" default="0">
  Redis use TLS encryption. (Default=0)
</ResponseField>

<ResponseField name="REDIS_KEYS_TTL_IN_SECS" type="number" default="604800 (7 days)">
  Time period for Redis to keep the data before eviction in seconds.
</ResponseField>

<ResponseField name="ENTITLEMENTS_FALLBACK" type="string">
  [Global entitlement fallback strategy](#global-fallback-strategy) in JSON format.
</ResponseField>

<ResponseField name="GRPC_PORT" type="number" default="80">
  Service port (HTTP/2)
</ResponseField>

<ResponseField name="PORT" type="number" default="8443">
  *Deprecated* TLS service port (HTTP/2 TLS)
</ResponseField>

<ResponseField name="CACHE_MAX_SIZE_BYTES" type="number" default="50% of total available memory size">
  Maximum size of the in-memory cache in bytes. If not set, the Sidecar allocates up to 50% of the available memory.
</ResponseField>

<ResponseField name="HEALTH_ENDPOINT_URL" type="string" default="livez">
  Health endpoint URL.
</ResponseField>

<ResponseField name="READY_ENDPOINT_URL" type="string" default="readyz">
  Ready endpoint URL.
</ResponseField>

<ResponseField name="METRICS_PORT" type="number" default="8080">
  The port of the [health](#health) and [metrics](#metrics) endpoints.
</ResponseField>

<ResponseField name="LOG_LEVEL" type="string" default="warn">
  Log level, can be one of: `error`, `warn`, `info`, `debug`.
</ResponseField>

<ResponseField name="LOG_MESSAGE_KEY" type="string" default="msg">
  Log string key for the 'message' in the JSON object.
</ResponseField>

<ResponseField name="LOG_ERROR_KEY" type="string" default="err">
  Log string key for the 'error' in the JSON object.
</ResponseField>

<ResponseField name="NODE_OPTIONS" type="string" default="--max-old-space-size-percentage=75">
  Node.js runtime flags. The default allocates 75% of container memory to the V8 heap, leaving room for the OS and non-heap allocations. Override to fine-tune memory allocation for your container setup.
</ResponseField>

<ResponseField name="OFFLINE" type="boolean" default="false">
  Enables offline mode for local development.
</ResponseField>

### Error handling

When the Sidecar encounters startup errors, such as an invalid API key or network errors to the Stigg API, it continues to run and serves entitlements from the:

1. [Persistent cache](#persistent-caching) (if available)
2. [Global fallback strategy](#global-fallback-strategy)