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

# Setup Agent

> Run one CLI command to set up Tusk Drift in 5 minutes

## Prerequisites

* **Node.js or Python** backend service (using Python 3.9+)
* **Tusk Drift CLI** installed in repo, see instructions below:

<Tabs>
  <Tab title="Linux/macOS">
    ```bash theme={null}
    curl -fsSL https://cli.usetusk.ai/install.sh | sh
    ```
  </Tab>

  <Tab title="Windows">
    Download the latest release from [GitHub Releases](https://github.com/Use-Tusk/tusk-cli/releases/latest):

    1. Download `tusk-cli_*_Windows_x86_64.zip`
    2. Extract the ZIP file
    3. Move `tusk.exe` to a directory in your PATH, or add the extracted directory to your PATH
  </Tab>
</Tabs>

## Overview

Our AI setup agent autonomously configures Tusk Drift for your backend service to make initial setup easy.

`cd` to the root of your service and **run the command below** to use the setup agent:

```bash theme={null}
tusk drift setup
```

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 drift init` wizard, it automatically analyzes the codebase, makes decisions, and handles edge cases dynamically.

Completing this flow means you can skip the [Installation](/api-tests/installation) and [Initialization](/api-tests/initialization/) guides.

## Setup Phases

The agent progresses through 9 phases, each with specific tools and goals.

<Info>
  If you prefer to only check repo compatibility and [set up Tusk Drift
  manually](/api-tests/installation#2-create-the-tusk-drift-config), you can run
  `tusk drift setup --eligibility-only`
</Info>

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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.

    **Automated steps:**

    1. Install Tusk Drift SDK via detected package manager
    2. Create init file
    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
  </Accordion>

  <Accordion title="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 drift run`. Incorrect values result in failed test execution. Docker setups require additional TCP communication settings and override files.
  </Accordion>

  <Accordion title="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)
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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`.
  </Accordion>
</AccordionGroup>