Configuration

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:

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:

npm install dotenv

.env

FLINTAI_GATEWAY_URL=https://app.flintai.dev
FLINTAI_API_KEY=your-flintai-api-key

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:

Explicit options passed to wrap() or init()
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:

Navigate to Agents and select your agent
Open the Sessions tab
The gateway URL is shown in the code snippet

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 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:

# Single host
export FLINTAI_ALLOWED_GATEWAY_HOSTS=gateway.yourcompany.com

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

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.

Flint AI API key

Create and manage API keys in Flint AI Platform: navigate to Settings, then select API Keys.

Copy your API key immediately when created — it is only shown once.

Pass the key directly or set the FLINTAI_API_KEY environment variable:

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.

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:

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.

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:

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.

Overview

Get started

Discovery

Evaluation

SDK

Rules

Resources

Environment variables

`.env` file support

Precedence

Gateway URL

Gateway host allowlist

Flint AI API key

Policy ID

Fail-closed behavior

Inspect your posture

Next steps

Usage

Integrations

​Environment variables

​.env file support

​Precedence

​Gateway URL

​Gateway host allowlist

​Flint AI API key

​Policy ID

​Fail-closed behavior

​Inspect your posture

​Next steps

Usage

Integrations

Environment variables

`.env` file support

Precedence

Gateway URL

Gateway host allowlist

Flint AI API key

Policy ID

Fail-closed behavior

Inspect your posture

Next steps