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:

Then run the following commands:

pip install pre-commit  # Or `uv pip install pre-commit`
pre-commit install  # Or `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.

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
pip install -e ".[dev]"  # Or `uv pip install -e ".[dev]"`

This -e flag installs the package in editable mode, which allows you to make changes to the package and have them reflected immediately. The .[dev] flag installs core and dev dependencies, which includes 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:

tc validate template <path-to-templates>  # Or `uv run tc validate template <path-to-templates>`

​
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.