Setting up external repositories

In Thymis, you can set up external repositories to manage your projects and modules. This allows you to package your software and integrate it with Thymis for deployment on IoT devices.

Steps to Set Up an External Repository

1. Create a Git Repository

Create a Git repository for your project. This repository will contain the Nix expressions and Thymis Modules that define how to build and deploy your software. You can use any Git hosting service, such as GitHub, GitLab, or Bitbucket. Make sure your repository is available to Thymis, either by making it public or by providing access credentials if it is private.

Currently, using access credentials requires access to the host where Thymis is running, as Thymis does not yet support providing access credentials through the UI. If you are using a self-hosted Thymis instance, you can set up SSH keys or access tokens to allow Thymis to access your private repositories. If you are using Thymis Cloud, you can request the Thymis team to set up access to your private repositories.

2. Structure Your Repository

Your repository should follow a specific structure to be compatible with Thymis. The recommended structure is:

my-project/
├── README.md # Project readme — must contain the string: "contains thymis modules"
├── flake.nix # Nix flake file, entry point for your Nix expressions
└── python_module_name_for_your_project/ # (optional) Directory for Thymis Python modules — make unique across projects
    ├── __init__.py # Python module init file
    └── module.py # Python module file — contains the Thymis module code

⚠️ Security Note: External modules run with full privileges inside the Thymis Controller environment. They can read/write project data, access connected devices, and execute arbitrary Nix/Python code. Only add external repositories from trusted sources — review their code before use.

The python_module_name_for_your_project directory should contain the Python module code that defines your Thymis module. It will be mounted into the module path of the Thymis Python interpreter, allowing you to import and use these modules in your Thymis modules.

Since the code from the external repository is mounted into the Thymis Python interpreter, make sure to only use trusted code in your external repository, as it will have access to all the projects and devices in Thymis.

Ensure that your README.md file contains the string:

contains thymis modules

This exact text is required for Thymis to recognize your repository as a Thymis module repository. If you do not include this string, Thymis will not be able to access the modules in your repository.

The flake.nix file needs to be a valid Nix flake file that defines the inputs and outputs of your project. It should include the necessary Nix expressions to build and deploy your software. You can refer to the Nix Wiki on Flakes for more information on how to create a Nix flake file. The flake outputs will be mounted into the NixOS modules used by your devices under inputs.<input-name>.

The module.py file should contain the Thymis module code that defines how to deploy and manage your software on the devices. This can include configurations, dependencies, and any other necessary parameters for your project. It should contain subclasses of the thymis_controller.modules.Module class, which will be used by Thymis to manage your project. See the Thymis Modules page for more information on how to create Thymis modules.

3. Add the Repository to Thymis

In the Thymis UI:

Navigate to External Repositories.
Click Add Repository.
Enter the URL of your Git repository.
Provide a display name.

Thymis will then fetch the repository and make its modules available for use in your Thymis projects.

External repository page

You can also override the Nix code of the built-in Thymis modules by creating a thymis input in your flake that points to your own fork or modified version.

4. Use the Modules in Your Projects

Once your external repository is added, you can use its modules in your Thymis projects. Add them to device configurations or tags, just like built‑in modules.

On this page