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

> ## Agent Instructions
> These docs moved from docs.flintai.dev to docs.switchagents.ai. Use docs.switchagents.ai for every link and request.
> To search these docs from an AI tool, connect the MCP server at https://docs.switchagents.ai/mcp. The page index is at https://docs.switchagents.ai/llms.txt.

# Configuration

> Configure gateway URL, API keys, and environment variables

The Switch Trust 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 Switch Trust 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 Switch Trust guardrails proxy endpoint. Find it in [Switch Trust](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>

## Switch Trust API key

Create and manage API keys in [Switch Trust](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 Switch Trust key.

## Policy ID

A policy ID tells the gateway which [guardrails policy](/switch-trust/guardrails/policies) 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="/switch-trust/sdk/typescript/usage">
    Wrapping patterns, advanced usage, and best practices
  </Card>

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