Runtime Management

This document explains how to manage runtimes in your self-hosted Stormkit instance using the Admin Dashboard.

Overview

Stormkit’s runtime management system allows you to control which programming languages, package managers, and tools are available during your app deployments.

You can:

• Install and manage multiple runtimes (Node.js, Go, npm, Angular CLI, etc.)
• Specify exact versions or use latest
• Enable or disable automatic runtime installation
• Use a flake.nix file to provide system-level tools via Nix
• Upgrade the underlying runtime manager (mise)

Accessing the Runtime Management Page

1. Log into your Stormkit Dashboard.
2. Click on your Profile > Admin
3. Navigate to: System > Installed runtimes

Managing Installed Runtimes

Adding a Runtime

1. Click Add Row.
2. Enter:
   • Runtime name — e.g., node, go, npm, npm:@angular/cli
   • Runtime version — Specific version (e.g., 24, 1.24) or latest
3. Click Save.

Removing a Runtime

• Click the × icon next to the runtime you want to remove.
• Click Save to apply changes.

Auto Install

When Auto install is enabled, Stormkit automatically installs required runtimes during deployment based on your app’s version configuration files.

• Enabled: Runtimes will be installed automatically if missing.
• Disabled: Only pre-installed runtimes will be available.

To toggle:

1. Use the switch under Auto install.
2. Save your changes.

The following files are recognized automatically:

Nix Flakes

If your repository contains a flake.nix file, Stormkit will automatically run nix develop during the install runtimes step to bootstrap the Nix development shell. The packages defined in the flake are then available for all subsequent build commands — no additional configuration required.

A typical flake.nix that provides ffmpeg and imagemagick during builds:

{
  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";

  outputs = { self, nixpkgs }: let
    system = "x86_64-linux";
    pkgs = nixpkgs.legacyPackages.${system};
  in {
    devShells.${system}.default = pkgs.mkShell {
      packages = [ pkgs.ffmpeg pkgs.imagemagick ];
    };
  };
}

flake.nix and mise.toml can coexist — mise handles language runtimes while the flake covers system-level tools.

Mise Runtime Manager

Stormkit relies on the mise open-source tool for runtime management. Current version is displayed in the Mise section.

Upgrading Mise

1. Click Upgrade to latest.
2. Stormkit will fetch and install the newest stable release of mise.

Note: Upgrading mise does not automatically upgrade installed runtimes. You’ll need to update those manually.

Persisting the Nix Store

Stormkit uses Nix as a backend for maintaining system level dependencies. By default, the Nix store lives at /nix inside the container. Without a persistent volume at that path, packages are re-downloaded every time the container restarts.

As of April 2026, the official docker-compose.yaml mounts a named nix volume at /nix for both the workerserver and hosting services. If you set up Stormkit before this date, add the following to your docker-compose.yaml to benefit from cached Nix packages:

1. Declare the volumes at the top-level volumes section:

volumes:
  workerserver_nix:
  hosting_nix:

2. Mount them in the respective service definitions:

# workerserver
- workerserver_nix:/nix

# hosting
- hosting_nix:/nix

After updating, run docker compose up -d to recreate the containers with the new mount. The Nix store will be populated on first use and reused on subsequent restarts.

volumes:
  workerserver_nix:
  hosting_nix:

# workerserver
- workerserver_nix:/nix

# hosting
- hosting_nix:/nix

Best Practices

• Pin versions for production apps to ensure predictable builds.
• Keep mise updated for the latest runtime management features.
• Use latest only for development or experimental environments.
• Regularly review installed runtimes and remove unused ones.

Related Documentation

• Mise Runtime Manager
• Nix Package Manager