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

# Configuring Failpath Across Deployment Environments

> Set up Failpath correctly for local development, production deployments, and test environments, including platform-specific environment variable guides.

Failpath relies on a single environment variable — `FAILPATH_PROJECT_KEY` — to authenticate your SDK and CLI. Where and how you set that variable depends on which environment your code is running in. This page covers local development, deployed backends, and test environments.

## Development

When you run `npx failpath init`, the CLI writes your project key to a `.env` file in your repository root and adds `.env` to your `.gitignore` automatically. In local development, this file is all you need — both the CLI commands (`publish`, `sync`) and the SDK will read from it.

```bash theme={"dark"}
# .env (created by `npx failpath init` — do not commit this file)
FAILPATH_PROJECT_KEY=fp_project_xxx
```

<Note>
  The `init` command updates your `.gitignore` to exclude `.env` automatically. If you use a different env file convention (for example `.env.local`), make sure your project key file is listed in `.gitignore` before committing.
</Note>

## Production and deployed backends

A repository `.env` file is not available in most deployed environments. You must set `FAILPATH_PROJECT_KEY` directly in your runtime environment using your platform's secret or environment variable management.

| Platform               | Where to set the variable                                                                              |
| ---------------------- | ------------------------------------------------------------------------------------------------------ |
| **Node.js (standard)** | Server environment or a secrets manager (e.g. AWS Secrets Manager, Doppler) injected at startup        |
| **Vercel**             | Project Settings → Environment Variables                                                               |
| **Railway**            | Service Settings → Variables                                                                           |
| **Render**             | Service Dashboard → Environment                                                                        |
| **Fly.io**             | `fly secrets set FAILPATH_PROJECT_KEY=fp_project_xxx`                                                  |
| **Convex**             | Deployment dashboard → Environment Variables (the repository `.env` is not read by Convex deployments) |
| **Docker**             | Pass via `--env` flag or an `env_file` in your Compose configuration                                   |

<Warning>
  Never commit `FAILPATH_PROJECT_KEY` to source control. Treat it as a secret with the same care as a database password or API key. If you accidentally expose it, rotate your project key from the Failpath dashboard immediately.
</Warning>

## Disabling in tests

Set `enabled: false` to prevent the SDK from sending any telemetry during your test suite. When disabled, `step()` still executes the wrapped function and returns its result normally — only the network calls are skipped.

```typescript theme={"dark"}
const failpath = createFailpathClient({
  projectKey: process.env.FAILPATH_PROJECT_KEY ?? "test",
  enabled: process.env.NODE_ENV !== "test",
});
```

The `?? "test"` fallback ensures the SDK does not throw when `FAILPATH_PROJECT_KEY` is not set in your test environment.

If your tests need to assert which events are emitted, use the mock client instead:

```typescript theme={"dark"}
import { createMockFailpathClient } from "@failpath/sdk/testing";

const failpath = createMockFailpathClient();
const run = failpath.run("checkout", { runId: "test_run" });

await run.step("validate-cart", async () => "ok");

expect(failpath.events).toMatchObject([
  { flowKey: "checkout", stepKey: "validate-cart", status: "running" },
  { flowKey: "checkout", stepKey: "validate-cart", status: "success" },
]);
```

## Local API development

If you are developing against a local instance of the Failpath API itself, you can override the default endpoint (`https://api.failpath.dev`) by setting `FAILPATH_DEV_ENDPOINT` in your shell, or by passing `--endpoint` to any CLI command:

```bash theme={"dark"}
npx failpath publish --endpoint http://localhost:3001
```

This option is intended for Failpath contributors and local API development only. Do not set `FAILPATH_DEV_ENDPOINT` in production deployments.