Skip to main content

​
Prerequisites

  • Node.js or Python backend service (using Python 3.12+)
  • Tusk Drift CLI installed in repo 
    curl -fsSL https://cli.usetusk.ai/install.sh | sh

​
Overview

Our AI setup agent uses Claude to autonomously configure Tusk Drift for your service to make initial setup easy. Run the command below and watch as Tusk Drift onboards itself to your repo: 
tusk setup --api-key "your-claude-api-key"
You will still need to approve running a few commands and/or provide text input during the agent’s flow. However, unlike our manual tusk init wizard, it automatically analyzes the codebase, makes decisions, and handles edge cases dynamically. Completing this flow means you can skip the Installation and Initialization guides.

​
Setup Phases

The agent progresses through 9 phases, each with specific tools and goals.
If you prefer to only check repo compatibility and set up Tusk Drift manually, you can run tusk setup --eligibility-only --api-key "your-claude-api-key"
1

Detect Language

Identifies the project’s language/runtime by checking for markers (package.json, requirements.txt, etc.).Why it matters: Tusk Drift currently only supports Node.js and Python. Early detection of unsupported languages (Go, Java, etc.) prevents wasted effort and provides clear messaging about future support.
2

Check Compatibility

Verifies project dependencies are compatible with the Tusk Drift SDK by checking against the SDK manifest.Why it matters: The SDK instruments specific packages (pg, mysql2, ioredis, @grpc/grpc-js, etc.). Unsupported packages won’t be recorded/replayed, leading to test failures against real services.
3

Gather Project Info

Collects configuration details: package manager, module system (ESM/CJS), entry point, start command, port, health endpoint, Docker setup, service name.Why it matters: Accurate detection of these values is critical for SDK instrumentation and config generation. Wrong module system = broken imports. Wrong port = failed health checks.
4

Confirm App Starts

Verifies the service starts correctly before SDK instrumentation.Why it matters: Establishes a baseline. If the app doesn’t start without the SDK, we can’t proceed. If it breaks after SDK instrumentation, the SDK is the cause.Automated steps:
  1. Start service with discovered start command
  2. Wait for health endpoint to respond
  3. Make HTTP request to verify
  4. Stop service
5

Instrument SDK

Installs the SDK and add initialization code to the application.Why it matters: This is the core setup step. The SDK must be imported first to intercept all outbound calls. ESM and CJS require different initialization patterns.Automated steps:
  1. Install Tusk Drift SDK via detected package manager
  2. Create init file with appropriate loader
  3. Import SDK at entry point or modify start script with --import flag
  4. Add TuskDrift.markAppAsReady()/tusk_drift.mark_app_as_ready() in listen callback
6

Create Config

Generates .tusk/config.yaml with all gathered project info, such as the service name, port, start/stop commands.Why it matters: The config file drives tusk run. Incorrect values result in failed test execution. Docker setups require additional TCP communication settings and override files.
7

Simple Test

Records and replays a trace using the health endpoint.Why it matters: End-to-end validation that recording and replay work. Catches SDK initialization issues, missing markAppAsReady(), wrong paths, etc.Automated steps:
  1. Start service with TUSK_DRIFT_MODE=RECORD
  2. Make request to health endpoint
  3. Stop service, verify trace exists via tusk_list
  4. Run tusk_run to replay
  5. Debug and retry if needed (up to 3 attempts)
8

Complex Test (Optional)

Tests an endpoint that makes external calls (HTTP, database, Redis).Why it matters: Validates the SDK captures external dependencies correctly. Simple health checks don’t exercise the mocking system—real-world endpoints do. May be skipped if no suitable endpoint is found, authentication is required, or user prefers to skip.
9

Summary

Provides a setup report documenting what was done, test results, and next steps.Why it matters: Provides a clear record of the setup for debugging and documentation. Saved to .tusk/SETUP_REPORT.md.