Self deployment can be tricky. We’d love to help on Discord!

Install Tracecat locally on your machine.

NOTE: The default setup is not intended for production use, but rather for development and testing purposes.

​
Prerequisites

​
Required

​
Optional

You don’t have to set up these services to run Tracecat, but they are required for certain features.

​
Setup

Please install the prerequisite tools beforehand.

Clone the Tracecat repository and navigate to the project root:

git clone git@github.com:TracecatHQ/tracecat.git
cd tracecat

From here, install the frontend dependencies using pnpm:

cd frontend
pnpm install

The frontend Docker container looks for node_modules on the host machine.

​
Environment variables

​
Manual

To manually set up environment variables, copy .env.example to create a .env file.

cp .env.example .env

You will have to replace the environment variables prefixed with your-.* with your own values.

The env.sh script runs commands to set up the database encryption key, API service key, and webhook signing secret for you.

Run the following command to create a .env file in the root directory:

chmod +x env.sh
bash env.sh

You’ll be prompted to enter your public facing Runner URL, OpenAI API key, and Resend API key. If you’d rather provide these later, you can skip each prompt step by pressing Enter.

If you use ngrok, the Runner URL should take the form https://<your-ngrok-domain>.ngrok-free.app. See the section Expose runner via ngrok for more details.

​
Expose runner via ngrok

Go to ngrok and create an account. Follow the instructions in getting started to install ngrok on your local machine. Then, go to ngrok dashboard and create a new domain (you get 1 free static domain). The domain should be in the format <some-random-phrase>.ngrok-free.app.

For example, if your ngrok domain is your-grnok-domain.ngrok-free.app, start ngrok by running the following command:

ngrok http --domain=your-ngrok-domain.ngrok-free.app 8001

If you don’t have a static domain, you can use a free ephermeral domain by running:

ngrok http http://localhost:8001

By binding ngrok to port 8001 on the host machine, incoming webhook requests are forwarded to the Runner container.

If correctly set up, your .env should contain:

TRACECAT__RUNNER_URL=https://your-ngrok-domain.ngrok-free.app

​
Linux users

If you are using Linux, you may encounter issues around being unable to resolve host.docker.internal from within the Docker containers.

To resolve this, you can add the following parameter to each of the services in the docker-compose.yaml file, as suggested by this StackOverflow post.

For example:

services:
  api:
    build: .
    container_name: api
    ports:
      - "8000:8000"
    volumes:
      - ./tracecat:/app/tracecat
      - app-storage:/var/lib/tracecat
    environment:
      API_MODULE: "tracecat.api.app:app"
      # Shared
      LOG_LEVEL: ${LOG_LEVEL}
      RABBITMQ_URI: ${RABBITMQ_URI}
      TRACECAT__APP_ENV: ${TRACECAT__APP_ENV}
      TRACECAT__DB_ENCRYPTION_KEY: ${TRACECAT__DB_ENCRYPTION_KEY}
      TRACECAT__DB_URI: ${TRACECAT__DB_URI}
      TRACECAT__SERVICE_KEY: ${TRACECAT__SERVICE_KEY}
      TRACECAT__SIGNING_SECRET: ${TRACECAT__SIGNING_SECRET}
      TRACECAT__API_URL: ${TRACECAT__API_URL}
      TRACECAT__RUNNER_URL: ${TRACECAT__RUNNER_URL}
      # Auth
      CLERK_FRONTEND_API_URL: ${CLERK_FRONTEND_API_URL}
      TRACECAT__DISABLE_AUTH: ${TRACECAT__DISABLE_AUTH}
      # Integrations
      OPENAI_API_KEY: ${OPENAI_API_KEY}
    restart: unless-stopped
    depends_on:
      rabbitmq:
        condition: service_healthy
    networks:
      - internal-network
    extra_hosts:
      - "host.docker.internal:host-gateway"
# Do the same for the rest of the services
# ...

​
Start Tracecat services

Finally, start Tracecat using docker compose:

docker compose up

​
Access Tracecat

The Tracecat frontend should now be running on port 3000. To access the frontend, open your browser and navigate to http://localhost:3000. You do not need to create an account for local usage.

Tracecat’s API and runner servers are also accessible via ports 8000 and 8001, respectively. You can view the API docs at http://localhost:8000/docs and the runner docs at http://localhost:8001/docs.

Congratulations! You have successfully installed Tracecat. This setup includes the essential components to set up a Tracecat proof-of-concept (PoC). For production-ready self-hosting solution, we recommend using one of our Cloud deployment strategies.

​
Stop Tracecat

To spin down all services, run the following command:

docker compose down --remove-orphans

​
Authentication

So far, we’ve shown how to run Tracecat locally without authentication and running with a default user.

If you want to enable authentication, you can set the TRACECAT__DISABLE_AUTH environment variable to false or 0 in the .env file. This requires you to have a Clerk account and set up the Clerk environment variables in .env.

# --- Authentication + Clerk ---
TRACECAT__DISABLE_AUTH=0
# Fill these in!
CLERK_FRONTEND_API_URL=...
CLERK_SECRET_KEY=...
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=...

Finally, you will need to add custom claims to your sessions - follow the steps in this Clerk blog post.

​
Troubldshooting

​
Docker networking

Some users face issues with Docker DNS resolution. What has often resolved their issues is to use host.docker.internal in certain places where container services are being referenced. This allows Docker containers to reference the Docker host machine.

For example, if you have a service api running in a container with port mapping 1234:8000 (mapping of port 1234 on the Docker host and 8000 in the container), from inside the Docker network you should be able to reference it using http://api:8000.

If you’re using Linux, please refer to the Linux users section. On MacOS and Windows WSL, you shouldn’t have this issue. If you do, please refer to the Docker networking docs or reach out to us on Discord for help.

Advanced ExampleDeployment