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

# Quickstart

> Run Thumper and plant your first tripwire on a real machine.

Stand up the server, create a tripwire, deploy it onto a machine, and trigger it
by reading the bait. The agent runs on the **endpoint**, so the read it detects
is a real read on a real machine.

## Run the server

The whole stack - React UI, FastAPI server, database, and plugins - ships as one
Docker image:

```bash theme={null}
docker compose up --build        # → http://localhost:8000
```

Open the dashboard at [localhost:8000](http://localhost:8000). For a real
deployment, run this somewhere your endpoints can reach over the network (a VM, a
container host) rather than on your laptop - the agent on each machine calls back
to it.

<Accordion title="Run it from source instead (dev mode)">
  ```bash theme={null}
  # backend (Python 3.10+)
  pip install -e .
  uvicorn thumper.main:app --reload --app-dir server   # → http://localhost:8000

  # UI (separate terminal) - Vite proxies /api to the backend
  cd ui && npm install && npm run dev                   # → http://localhost:5173
  ```
</Accordion>

## Plant a tripwire on a machine

<Steps>
  <Step title="Create a tripwire">
    In the dashboard, create a tripwire - pick a token type (e.g. AWS access
    key), a source, and a path. It's a definition; nothing is planted yet.
  </Step>

  <Step title="Copy its install command">
    Open the tripwire and copy its **install command**. It's generated
    server-side and carries the install token, so it's ready to run as-is:

    ```bash theme={null}
    curl -fsSL 'http://YOUR-SERVER/api/install.sh?tripwire=<id>&token=<install-token>' \
      -o /tmp/thumper-install.sh && sudo sh /tmp/thumper-install.sh
    ```
  </Step>

  <Step title="Run it on the target machine">
    Run that command on the machine you want to protect - paste it into a shell,
    or push it through your MDM / SSH / Ansible. The agent downloads itself,
    **self-enrolls**, pulls its own unique honeytoken, plants the bait at the
    chosen path, and starts watching. (`sudo` is needed so macOS read detection
    can use `fs_usage`.)
  </Step>

  <Step title="Trigger it">
    On that machine, read the planted file the way an attacker scanning for
    credentials would:

    ```bash theme={null}
    cat ~/.aws/credentials
    ```

    The agent sees the read and fires an HMAC-signed, enriched callback to the
    server.
  </Step>

  <Step title="See the alert">
    The endpoint lights up as compromised on the dashboard, enriched with the
    host, user, and process that did the read - and the alert is delivered to
    every configured alert integration. Via the API:

    ```bash theme={null}
    curl -s http://YOUR-SERVER/api/alerts
    ```
  </Step>
</Steps>

<Note>
  For a server-only smoke test without a second machine, run the bundled agent
  with `--simulate`. It enrolls and fires one signed callback without planting
  anything:

  ```bash theme={null}
  sh agent/thumper_agent.sh run \
    --server http://localhost:8000 --enroll-token dev-enroll-token \
    --tripwire <id> --simulate
  ```
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Deploy integrations" icon="truck" href="/thumper/deploy-integrations">
    Push tripwires across a whole fleet via MDM or SSH.
  </Card>

  <Card title="How it works" icon="diagram-project" href="/thumper/how-it-works">
    The full path from definition to fired alert.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.