Tusk Drift is in public beta. Reach out to support@usetusk.ai for cloud access.

​
Prerequisites

  • Node.js service (backend) where the SDK will be installed
  • Tusk account with Team or Enterprise access
  • Dev/staging environment for initial rollout (recommended)

​
Overview

Tusk Drift SDK captures real API calls from your service and deterministically replays them to detect regressions. During replay, outbound requests are intercepted and served from recorded data so results are stable, side-effect free, and fast enough for CI.

​
Supported technologies

  • HTTP/HTTPS: All versions (Node.js built-in)
  • PostgreSQL: pg@8.x, pg-pool@2.x–3.x
  • JSON Web Tokens: jsonwebtoken@5.x–9.x
  • JWKS RSA: jwks-rsa@1.x–3.x
  • GraphQL: graphql@15.x–16.x
To see a complete list of supported packages and versions, view our public repo’s README.

​
Setup

1

Install the Tusk CLI

Build the CLI locally and verify installation:
# Go 1.25+
git clone https://github.com/Use-Tusk/tusk-drift-cli.git
cd tusk-drift-cli
make deps
make build
./tusk --help
2

Set up the Tusk Drift config

Create your .tusk/config.yaml in the root of your service using the onboarding wizard:
cd <path/to/your/service>
tusk init
The wizard will generate .tusk/config.yaml. You can also create the .tusk directory and config file manually in your service root. See the configuration docs for details.
3

Install the Drift SDK

Install the SDK in your service:
npm install @use-tusk/drift-sdk
4

Obtain a Tusk Drift API key

Sign in to the Tusk web app, navigate to Settings > API Keys and click Create key. Name the key (e.g., “Tusk Drift”), copy it on creation, and store it securely.
5

Initialize and import SDK

Create a file tdInit.ts to initialize the Tusk Drift SDK.
// tdInit.ts
import { tdSdk } from '@use-tusk/drift-sdk';

tdSdk.initialize({
  apiKey: process.env.TUSK_DRIFT_API_KEY,
  env: process.env.NODE_ENV ?? 'development',
  logLevel: process.env.TUSK_DRIFT_LOG_LEVEL ?? 'info',
});

export { tdSdk };
In your main server file (e.g., server.ts, index.ts, app.ts), import this file at the very top before any other imports. This ensures proper instrumentation of all dependencies.
// server.ts (or index.ts/app.ts)
import './tdInit'; // must be first
// other imports below
6

Mark the app as ready

Once your server is listening, signal readiness so recording/replay begins only after initialization completes:
// server.ts
import { tdSdk } from "./tdInit";

// ... other imports ...

const app = express();

// Your application setup...

app.listen(8000, () => {
  // Mark app as ready for recording/replay
  tdSdk.markAppAsReady();
  console.log("Server started and ready for Tusk Drift");
});
7

Configure recording policies

In .tusk/config.yaml, add or adjust a recording section. These controls help enterprises manage data capture and cost:
recording:
  sampling_rate: 0.1             # 10% of requests recorded (set 1.0 to capture all)
  export_spans: true              # export spans to Tusk backend and local files
  enable_env_var_recording: true  # record/replay env vars that affect behavior
  • sampling_rate: 0.0–1.0. Use lower rates for production, increase temporarily during onboarding.
  • export_spans: If disabled, spans are written locally under .tusk/traces only.
  • enable_env_var_recording: Recommended when business logic depends on environment configuration.