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

# Configuration

> Configure gateway URL, API keys, and environment variables

The Flint AI TypeScript SDK needs two pieces of information to route traffic through the guardrails proxy: a **gateway URL** and an **API key**. You can provide these as options passed to `wrap()` or `init()`, or as environment variables.

## Environment variables

Set these variables in your shell or deployment environment to avoid hard coding credentials:

| Variable                        | Required | Description                                                                                                                                      |
| ------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `FLINTAI_GATEWAY_URL`           | Yes      | Guardrails proxy URL                                                                                                                             |
| `FLINTAI_API_KEY`               | Yes      | Your Flint AI API key                                                                                                                            |
| `FLINTAI_POLICY_ID`             | No       | Guardrails policy ID to enforce on requests                                                                                                      |
| `FLINTAI_ALLOWED_GATEWAY_HOSTS` | No       | Comma-separated allowlist of permitted gateway hostnames. Defaults to `app.flintai.dev`. The `*` wildcard requires `allowInsecureGateway: true`. |
| `AGENT_ID`                      | No       | Agent identifier attached to guardrails requests                                                                                                 |
| `AGENT_NAME`                    | No       | Agent name attached to guardrails requests                                                                                                       |

Environment variables are read automatically. When they are set, you can call `wrap()` without passing credentials:

```typescript theme={null}
import OpenAI from "openai";
import { wrap } from "@sandboxaq/flintai-sdk-ts";

const client = new OpenAI();
wrap(client);
```

### `.env` file support

A `.env` file is **not** read by default. Install `dotenv` as a peer dependency, then pass `loadDotenv` to load it:

```bash theme={null}
npm install dotenv
```

```bash title=".env" theme={null}
FLINTAI_GATEWAY_URL=https://app.flintai.dev
FLINTAI_API_KEY=your-flintai-api-key
```

```typescript theme={null}
wrap(client, { loadDotenv: true });          // loads <cwd>/.env
wrap(client, { loadDotenv: "/path/to/.env" }); // loads a specific trusted file
```

### Precedence

When the same setting is provided in more than one place, the SDK uses this order:

1. **Explicit options** passed to `wrap()` or `init()`
2. **Environment variables** (`FLINTAI_*`), including any loaded from a `.env` file

## Gateway URL

The gateway URL is your Flint AI guardrails proxy endpoint. Find it in [Flint AI Platform](https://app.flintai.dev):

1. Navigate to **Agents** and select your agent
2. Open the **Sessions** tab
3. The gateway URL is shown in the code snippet

<Note>
  The gateway URL must use `https://`. Plaintext `http://` is only allowed for loopback hosts (`localhost`, `127.0.0.1`, `::1`), and only when you pass `allowInsecureGateway: true` — intended for local development. The SDK warns when insecure access is enabled.
</Note>

### Gateway host allowlist

By default, the SDK only allows connections to `app.flintai.dev`. This prevents credentials from being accidentally sent to an unintended endpoint. To use a self-hosted gateway, set `FLINTAI_ALLOWED_GATEWAY_HOSTS`:

```bash theme={null}
# Single host
export FLINTAI_ALLOWED_GATEWAY_HOSTS=gateway.yourcompany.com

# Multiple hosts
export FLINTAI_ALLOWED_GATEWAY_HOSTS=gateway.yourcompany.com,gateway-staging.yourcompany.com
```

<Warning>
  The `*` wildcard allows any host and cannot be enabled through the environment alone — you must also pass `allowInsecureGateway: true` in code. A wildcard host can redirect your API key, provider credentials, and all prompt and response traffic to an unintended endpoint, so reserve it for local development.
</Warning>

## Flint AI API key

Create and manage API keys in [Flint AI Platform](https://app.flintai.dev): navigate to **Settings**, then select **API Keys**.

<Warning>
  Copy your API key immediately when created — it is only shown once.
</Warning>

Pass the key directly or set the `FLINTAI_API_KEY` environment variable:

```typescript theme={null}
import { wrap } from "@sandboxaq/flintai-sdk-ts";

// Pass directly
wrap(client, {
  gatewayUrl: "https://app.flintai.dev",
  apiKey: "your-flintai-api-key",
});

// Or use environment variables
// export FLINTAI_GATEWAY_URL=https://app.flintai.dev
// export FLINTAI_API_KEY=your-flintai-api-key
wrap(client);
```

You still set your LLM provider key the way your agent normally does. That is usually the standard per-provider environment variable your framework expects (such as `OPENAI_API_KEY`), or set on the provider client directly. The SDK does not require any additional LLM provider key of its own. The `apiKey` here is your Flint AI key.

## Policy ID

A policy ID tells the gateway which guardrails policy to enforce. Policies apply input and output detectors that can block, redact, or alert on unsafe content.

```typescript theme={null}
wrap(client, {
  gatewayUrl: "https://app.flintai.dev",
  apiKey: "your-flintai-api-key",
  policyId: "your-policy-id",
});
```

You can also set this with the `FLINTAI_POLICY_ID` environment variable.

## Fail-closed behavior

The SDK defaults to `requireGuardrails: true`. If a valid client is passed but guardrails configuration is missing — for example, missing credentials — `wrap()` and `init()` throw `FlintAIGuardrailsError` instead of sending traffic unguarded.

To allow operation without guardrails (for example, in local development), opt out explicitly:

```typescript theme={null}
wrap(client, { dangerouslyDisableGuardrails: true });
```

`dangerouslyDisableGuardrails: true` is the preferred, self-documenting opt-out — it is easy to find in a code search. It is equivalent to `requireGuardrails: false`, and the two cannot be combined with `requireGuardrails: true`.

<Warning>
  Disabling guardrails is not silent. Either opt-out emits a `SECURITY CONTROL DISABLED` console warning — once per process, including the resolved agent identifier — so unguarded deployments stay detectable in your logs.
</Warning>

## Inspect your posture

Call `status()` (or `client.guardrailsStatus()`) at runtime to read the effective posture rather than trusting the opt-out flag alone:

```typescript theme={null}
import { status } from "@sandboxaq/flintai-sdk-ts";

const posture = status();
// { active, requireGuardrails, provider, agentId, agentName }
```

`active` is `true` only when traffic is actually routed through the gateway. `status()` returns `null` before `init()` runs.

## Next steps

<CardGroup cols={2}>
  <Card title="Usage" icon="code" href="/flintai/platform/sdk/typescript/usage">
    Wrapping patterns, advanced usage, and best practices
  </Card>

  <Card title="Integrations" icon="plug" href="/flintai/platform/sdk/typescript/integrations">
    Provider-specific setup for OpenAI, Anthropic, Google GenAI, LangChain, and ADK
  </Card>
</CardGroup>