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

# Lua SDK reference

<View title="Developer" />

<View title="Federal docs" />

<View title="EU docs" />

This topic documents how to get started with the Lua SDK, and links to reference information on all of the supported features. We also provide documentation for running the SDK in [NGINX](/docs/guides/sdk/nginx) and [HAProxy](/docs/guides/sdk/haproxy).

<Note>
  **SDK quick links**

  LaunchDarkly's SDKs are open source. In addition to this reference guide, we provide source, API reference documentation, and sample applications:

  <table>
    <thead>
      <tr>
        <th>Resource</th>
        <th>Location</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>SDK API documentation</td>
        <td>[SDK API docs](https://launchdarkly.github.io/lua-server-sdk/modules/launchdarkly-server-sdk.html)</td>
      </tr>

      <tr>
        <td>Supported SDK Versions</td>
        <td>[Lua server SDK](/docs/sdk/concepts/supported-versions#lua-server-sdk)</td>
      </tr>

      <tr>
        <td>GitHub repository</td>
        <td>[lua-server-sdk](https://github.com/launchdarkly/lua-server-sdk)</td>
      </tr>

      <tr>
        <td>Sample applications</td>
        <td>[Lua](https://github.com/launchdarkly/hello-lua-server) <br /> [Lua with HAProxy](https://github.com/launchdarkly/hello-haproxy) <br /> [Lua with OpenResty NGINX](https://github.com/launchdarkly/hello-nginx)</td>
      </tr>

      <tr>
        <td>Published module</td>
        <td>[LuaRocks](https://luarocks.org/modules/launchdarkly)</td>
      </tr>
    </tbody>
  </table>
</Note>

## Get started

After you complete the [Getting Started](/docs/home/getting-started) process, follow these steps to get started using the LaunchDarkly SDK in your Lua application.

The Lua server-side SDK is implemented using a foreign function interface that calls the C++ server-side SDK. You need to install the C++ server-side SDK dynamic library somewhere accessible by the linker.

To learn more, read [C++ SDK reference (server-side)](/docs/sdk/server-side/c-c--).

### Install the SDK

First, include the library:

<CodeGroup>
  ```lua title="Lua" lines wrap theme={null}
  local ld = require("launchdarkly_server_sdk")
  ```
</CodeGroup>

<Note>
  **The Lua SDK uses an SDK key**

  The Lua SDK uses an SDK key. Keys are specific to each project and environment. They are available on the **SDK keys** page under **Settings**. To learn more about key types, read [Keys](/docs/sdk/concepts/client-side-server-side#keys-and-credentials).
</Note>

### Initialize the client

After you install and import the SDK, create a single, shared instance of `LDClient`. Specify your SDK key here to authorize your application to connect to a particular environment within LaunchDarkly.

<Warning>
  **LDClient must be a singleton**

  It's important to make `LDClient` a singleton for each LaunchDarkly project. The client instance maintains internal state that allows LaunchDarkly to serve feature flags without making any remote requests. Do not instantiate a new client with every request.

  If you have multiple LaunchDarkly projects, you can create one `LDClient` for each. In this situation, the clients operate independently. For example, they do not share a single connection to LaunchDarkly.
</Warning>

Calling `clientInit` initiates a remote call to the LaunchDarkly service to fetch feature flags. This call blocks up for the time that you provide in milliseconds. If you request a feature flag before the client completes initialization, you will receive the default flag value.

Here is an example:

<CodeGroup>
  ```lua title="Lua" lines wrap theme={null}
  -- This will block for 1 second
  local client = ld.clientInit("YOUR_SDK_KEY", 1000, config)
  ```
</CodeGroup>

To learn more about the specific configuration properties that are available in this SDK, read [`clientInit`](https://launchdarkly.github.io/lua-server-sdk/modules/launchdarkly-server-sdk.html#clientInit).

### Evaluate a context

You can use `client` to check which variation a particular context will receive for a given feature flag.

Here's how:

<CodeGroup>
  ```lua title="Lua SDK v2+" lines wrap theme={null}
  if client:boolVariation(context, "example-flag-key", false) then
      print "feature is enabled"
  else
      print "feature is disabled"
  end
  ```

  ```lua title="Lua SDK v1.x" lines wrap theme={null}
  if client:boolVariation(user, "example-flag-key", false) then
      print "feature is enabled"
  else
      print "feature is disabled"
  end
  ```
</CodeGroup>

## Supported features

This SDK supports the following features:

* [SDK configuration](/docs/sdk/features/config#lua), including
  * [Application metadata configuration](/docs/sdk/features/app-config#lua)
  * [Service endpoint configuration](/docs/sdk/features/service-endpoint-configuration#lua)
* [Aliasing users](/docs/sdk/features/aliasing-users#lua)
* [Anonymous contexts and users](/docs/sdk/features/anonymous#lua)
* [Context configuration](/docs/sdk/features/context-config#lua)
* [Flag variation evaluation](/docs/sdk/features/evaluating#lua)
* [Flag variation evaluation details](/docs/sdk/features/evaluation-reasons#lua)
* [Flushing events](/docs/sdk/features/flush#lua)
* [Getting all flags](/docs/sdk/features/all-flags#lua)
* [Identifying and changing contexts](/docs/sdk/features/identify#lua)
* [Logging](/docs/sdk/features/logging#lua)
* [Offline](/docs/sdk/features/offline-mode#lua)
* [Private attributes](/docs/sdk/features/private-attributes#lua)
* [Relay Proxy configuration](/docs/sdk/features/relay-proxy-configuration)
  * [Using proxy mode](/docs/sdk/features/relay-proxy-configuration/proxy-mode#lua)
  * [Using daemon mode](/docs/sdk/features/relay-proxy-configuration/daemon-mode#lua)
* [Tracking custom events](/docs/sdk/features/events#lua)
* [Storing data](/docs/sdk/features/storing-data#lua)