Skip to main content
We recommend installing uv, which is a fast Python package and project manager, before starting this tutorial.
Interested in contributing to the official Tracecat Registry? Check out the contributing guide on GitHub for more information.All accepted contributions are then maintained by the Tracecat team!

​
Prerequisites

​
Linting

You can safely skip this section if you do not need automatic linting and formatting. This setup, however, is required for contributors.
Tracecat uses ruff and pre-commit hooks for linting and formatting code. The easiest way to set up both ruff and pre-commit is to cd into the custom-integrations-starter-kit directory, add the following .pre-commit-config.yaml file: 
# See https://pre-commit.com for more information
# See https://pre-commit.com/hooks.html for more hooks
default_language_version:
  python: python3.12
default_install_hook_types: [pre-commit, commit-msg]

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0
    hooks:
      - id: check-added-large-files
        args:
          - --maxkb=3000
      - id: check-toml
      - id: check-yaml
        args:
          - --unsafe
      - id: end-of-file-fixer
      - id: trailing-whitespace

  - repo: https://github.com/charliermarsh/ruff-pre-commit
    rev: v0.9.1
    hooks:
      - id: ruff
        args:
          - --fix
          - --show-fixes # Show what files were fixed
          - --verbose
      - id: ruff-format
        verbose: true
Then run the following commands: 
uv run pre-commit install
The pre-commit hooks will run automatically when you commit code to your local repository. Linting helps keep code consistent according to best practices.

​
Integrations Starter Kit

The recommended way to start developing custom integrations is to use the integrations starter kit.
1

Create new repo

The first step is to create a new repo from the custom-integrations-starter-kit template.Custom integrations template
2

Install package and tracecat_registry

The starter kit is a Python package with a pyproject.toml file. To install it, run the following command:
cd custom-integrations-starter-kit
uv sync
This installs the package and all dependencies from the lock file, ensuring reproducible builds. The dev dependencies include the tracecat and tracecat_registry[cli] Python packages.Find out more about the tracecat_registry package below.
3

Setup development environment

The final step is to link the local registry to your local Tracecat instance. Step-by-step instructions are available in the development environment section below.

​
Tracecat Registry

tracecat_registry requires tracecat to be installed.
Installing tracecat_registry will give you access to the tc CLI, which is used to validate your templates before syncing and running them in Tracecat. It also includes the tracecat_registry package, which contains necessary imports for building Tracecat Python UDFs.

​
Validation CLI

We highly recommend using this CLI to validate your templates before syncing and running them in Tracecat.This will save you a lot of time debugging syntax issues.
To check if your templates are valid, run the following command: 
uv run tc validate template <path-to-templates>
Registry CLI

​
Local testing

registry.register, Annotated, Doc, and RegistrySecret are used to convert your Python function arguments into Tracecat action inputs. They do not affect the function’s behavior in Python. You can continue using the function as normal in your scripts and tests.

​
Development Environment

This tutorial assumes you have a local Tracecat Docker Compose deployment.
This is for local development only.For production, please sync your custom integrations into Tracecat from a secure remote repository (e.g. GitHub, GitLab). Check out the custom integrations tutorial for more information.
You can point Tracecat to your local registry by setting the following environment variables in your .env file: 
TRACECAT__LOCAL_REPOSITORY_ENABLED=true
TRACECAT__LOCAL_REPOSITORY_PATH=<path-to-local-registry>
# E.g. TRACECAT__LOCAL_REPOSITORY_PATH=~/repos/org/custom-integrations-starter-kit
Don’t forget to restart Tracecat: 
docker compose up -d
Action templates and Python UDFs will be hot loaded into your Tracecat instance. Changes in your local registry are automatically reflected in Tracecat. No sync is required.