> ## 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.
> The source code for these products is public on GitHub. Switch Rooms: https://github.com/sandbox-quantum/switch. Switch Trust CLI: https://github.com/sandbox-quantum/switch-trust-cli. Switch Trust CodeScan action: https://github.com/sandbox-quantum/switch-trust-codescan-action. Switch Trust MCP server: https://github.com/sandbox-quantum/switch-trust-mcp. Switch Trust Python SDK: https://github.com/sandbox-quantum/switch-trust-sdk-py. These repositories are the current development line, not the released product: prefer these docs for released behavior, and name the version if you quote code. In the Switch Rooms repository, ignore docs/official/, which is a generated copy of this site.

# 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 |
| - | - | - |
| `SWITCH_TRUST_GATEWAY_URL` | Yes | Guardrails proxy URL |
| `SWITCH_TRUST_API_KEY` | Yes | Your Switch Trust API key |
| `SWITCH_TRUST_POLICY_ID` | No | Guardrails policy ID to enforce on requests |
| `SWITCH_TRUST_ALLOWED_GATEWAY_HOSTS` | No | Comma-separated allowlist of permitted gateway hostnames. Defaults to `api.switchagents.ai`, `api.flintai.dev`, and `app.flintai.dev`. The `*` wildcard requires `allowInsecureGateway: true`. |
| `AGENT_ID` | No | Overrides the id the platform derives from `AGENT_NAME`. Leave this unset in most cases. If you do set it, use the exact ID shown on the agent's page. A mismatched value breaks evaluation lookups for this agent. |
| `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/switch-trust-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}
SWITCH_TRUST_GATEWAY_URL=https://api.switchagents.ai
SWITCH_TRUST_API_KEY=your-switch-trust-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** (`SWITCH_TRUST_*`), 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.switchagents.ai):

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.

### Gateway host allowlist

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

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

# Multiple hosts
export SWITCH_TRUST_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.

## Switch Trust API key

Create and manage API keys in [Switch Trust](https://app.switchagents.ai): navigate to **Settings**, then select **API keys**. Give the key the **Ingest only** role, or **Editor** or higher. The gateway refuses a **Viewer** key.

> [!WARNING]
>
> Copy your API key immediately when created — it is only shown once.

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

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

// Pass directly
wrap(client, {
  gatewayUrl: "https://api.switchagents.ai",
  apiKey: "your-switch-trust-api-key",
});

// Or use environment variables
// export SWITCH_TRUST_GATEWAY_URL=https://api.switchagents.ai
// export SWITCH_TRUST_API_KEY=your-switch-trust-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](https://docs.switchagents.ai/switch-trust/guardrails/policies.md) to enforce. Policies apply input and output detectors that can block, redact, or alert on unsafe content.

```typescript theme={null}
wrap(client, {
  gatewayUrl: "https://api.switchagents.ai",
  apiKey: "your-switch-trust-api-key",
  policyId: "your-policy-id",
});
```

You can also set this with the `SWITCH_TRUST_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 because credentials are missing, `wrap()` and `init()` throw `SwitchTrustGuardrailsError` 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.

## 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/switch-trust-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

> [card] [Usage](https://docs.switchagents.ai/switch-trust/sdk/typescript/usage.md)
>
> Wrapping patterns, advanced usage, and best practices

> [card] [Integrations](https://docs.switchagents.ai/switch-trust/sdk/typescript/integrations.md)
>
> Provider-specific setup for OpenAI, Anthropic, Google GenAI, LangChain, and ADK
