Runtimes

Manage programming language runtimes, package managers, and development tools in your self-hosted Stormkit instance using mise

You must be an administrator to access runtime management.

Stormkit’s runtime management system allows you to control which programming languages, package managers, and tools are available during your app deployments. This guide explains how to manage runtimes using the Admin Dashboard.

Overview

Stormkit uses mise (formerly rtx), a powerful open-source runtime manager that provides:

• Multi-language support - Node.js, Go, Python, Ruby, Rust, and more
• Version management - Install and switch between multiple versions
• Package manager support - npm, pnpm, yarn, and CLI tools
• Automatic detection - Reads version files from your repository
• Global and project-specific runtimes

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
• Upgrade the underlying runtime manager (mise)

Accessing Runtime Management

1. Log into Dashboard

   Log into your Stormkit Dashboard.

2. Open Admin Panel

   Click on your Profile in the top right corner, then select Admin.

3. Navigate to Runtimes

   Go to System > Installed runtimes (or navigate directly to /admin/runtimes).

Managing Installed Runtimes

Adding a Runtime

1. Click Add Row

   In the Installed Runtimes section, click Add Row.

2. Enter Runtime Details

   Fill in the following fields:

   • Runtime name - e.g., node, go, npm, npm:@angular/cli, python
   • Runtime version - Specific version (e.g., 24, 1.24, 3.11) or latest
3. Save Changes

   Click Save to install the runtime.

Examples:

Runtime Name	Version	Description
node	24	Node.js version 24
node	latest	Latest stable Node.js
go	1.24	Go version 1.24
npm	10	npm version 10
npm:@angular/cli	latest	Angular CLI
npm:typescript	5.3.3	TypeScript 5.3.3
python	3.11	Python 3.11
ruby	3.2	Ruby 3.2

Refer to the mise documentation for a complete list of supported tools and their naming conventions.

Removing a Runtime

1. Locate Runtime

   Find the runtime you want to remove in the list.

2. Click Remove Icon

   Click the × icon next to the runtime.

3. Save Changes

   Click Save to apply the removal.

Removing a runtime that’s actively used by deployed applications may cause deployment failures. Ensure no applications depend on the runtime before removing it.

Auto Install

The Auto install feature allows Stormkit to automatically detect and install runtimes based on version configuration files in your repository.

How Auto Install Works

• Enabled: Stormkit scans your repository for version files and automatically installs required runtimes during deployment
• Disabled: Only pre-installed runtimes (configured in the Admin Dashboard) are available

Recognized Version Files

Stormkit automatically detects runtime versions from these files:

Runtime	Recognized Files
Node.js	.nvmrc, .node-version
Go	.go-version
Python	.python-version, .python-versions
Ruby	.ruby-version, Gemfile

Example: If your repository contains a .nvmrc file with content 22, Stormkit will automatically install Node.js version 22 during deployment.

Toggling Auto Install

1. Navigate to Runtimes

   Go to System > Installed runtimes in the Admin Dashboard.

2. Toggle Switch

   Use the switch under Auto install to enable or disable the feature.

3. Save Changes

   Click Save to apply your preference.

Even with Auto Install enabled, you can pre-install runtimes in the Admin Dashboard to speed up deployments by avoiding repeated downloads.

Mise Runtime Manager

Stormkit relies on mise for runtime management. The current version is displayed in the Mise section of the runtime management page.

Why Mise?

mise provides several advantages over traditional version managers:

• Unified interface for multiple languages
• Fast installation with parallel downloads
• Automatic version detection from project files
• Plugin ecosystem for extended tool support
• Active development and regular updates

Upgrading Mise

1. Navigate to Mise Section

   Scroll to the Mise section in the runtime management page.

2. Click Upgrade

   Click Upgrade to latest to install the newest stable release of mise.

3. Wait for Completion

   Stormkit will fetch and install the latest version. This may take a few moments.

4. Verify Version

   The displayed version number will update after the upgrade completes.

Upgrading mise does not automatically upgrade installed runtimes. You’ll need to update runtime versions manually in the Installed Runtimes section.

Runtime Configuration Examples

Example 1: Modern JavaScript Stack

Runtime Name        | Version
--------------------|----------
node                | 24
npm                 | 10
npm:typescript      | latest
npm:@angular/cli    | 18

Use case: Angular application requiring Node.js 24, npm 10, and Angular CLI 18.

Example 2: Go Application

Runtime Name        | Version
--------------------|----------
go                  | 1.24
node                | 22

Use case: Go backend with a Node.js-based build toolchain.

Example 3: Python Data Science Project

Runtime Name        | Version
--------------------|----------
python              | 3.11
node                | latest

Use case: Python application with Node.js for asset compilation.

Example 4: Multi-Version Node.js

Runtime Name        | Version
--------------------|----------
node                | 22
node                | 20
node                | 18

Use case: Testing applications across multiple Node.js versions (managed per-project using .nvmrc).

Best Practices

Production Environments

Follow these best practices for production deployments:

• Pin specific versions rather than using latest to ensure predictable builds
• Test version upgrades in a staging environment before applying to production
• Keep mise updated for the latest runtime management features and security patches
• Document runtime requirements in your repository’s README

Version Pinning

.nvmrc

# ✅ Good: Specific version
22.1.0

# ⚠️ Acceptable: Major version
22

# ❌ Avoid in production: Latest
latest

Pre-installation Strategy

For frequently used runtimes:

1. Pre-install in Admin Dashboard to avoid download time during deployments
2. Use Auto Install as fallback for project-specific versions
3. Monitor runtime usage and remove unused versions periodically

Version File Best Practices

Include version files in your repository:

# Create .nvmrc for Node.js version
echo "22" > .nvmrc

# Create .go-version for Go version
echo "1.24" > .go-version

# Commit to repository
git add .nvmrc .go-version
git commit -m "Pin runtime versions"

Environment Variables

Runtime management uses these environment variables from your Stormkit configuration:

.env

# Redis for caching runtime installations
REDIS_ADDR=redis:6379

# PostgreSQL for storing runtime configuration
POSTGRES_HOST=db
POSTGRES_PORT=5432
POSTGRES_DB=stormkit_db
POSTGRES_USER=stormkit_admin

# Runner concurrency affects parallel runtime installations
STORMKIT_RUNNER_CONCURRENCY=4

Troubleshooting

Runtime Installation Fails

Symptoms: Deployment fails with “runtime not found” or “installation failed” errors.

Solutions:

1. Check version format:

   ✅ Correct: node@22, go@1.24
   ❌ Incorrect: node@v22, go@v1.24
   

2. Verify internet connectivity - Stormkit needs to download runtimes from upstream sources

3. Check mise compatibility - Some tools may not be available in older mise versions

4. Review logs:

   docker compose logs -f workerserver
   

Auto Install Not Working

Symptoms: Runtimes aren’t automatically detected from version files.

Solutions:

1. Verify Auto Install is enabled in Admin Dashboard
2. Check version file format:
   # .nvmrc should contain only the version
   22
   
   # Not:
   v22
   node 22
   
3. Ensure version file is in repository root or project directory
4. Check file is committed to git (not in .gitignore)

Slow Deployments

Symptoms: Deployments take longer than expected.

Solutions:

1. Pre-install frequently used runtimes in Admin Dashboard
2. Use specific versions instead of latest to enable caching
3. Increase runner concurrency:
   .env

   STORMKIT_RUNNER_CONCURRENCY=8
   
4. Persist mise cache by mounting the home directory (see Custom Images)

Version Conflicts

Symptoms: Different projects require incompatible runtime versions.

Solutions:

• Use project-specific version files (.nvmrc, .go-version, etc.)
• Enable Auto Install to handle per-project versions automatically
• mise automatically switches versions based on project context

Advanced Configuration

Installing CLI Tools

Install npm-based CLI tools globally:

Runtime Name              | Version
--------------------------|----------
npm:@angular/cli          | 18
npm:@nestjs/cli           | latest
npm:typescript            | 5.3.3
npm:vite                  | latest

Multiple Versions of Same Runtime

Install multiple versions for testing:

Runtime Name        | Version
--------------------|----------
node                | 22
node                | 20
node                | 18

Projects will use the version specified in their .nvmrc file.

Custom Mise Configuration

For advanced mise configuration, you can customize the workerserver Docker image. See Custom Images for details.

Monitoring Runtime Usage

Track runtime usage through deployment logs:

# View recent deployments
docker compose logs -f workerserver | grep "runtime"

# Check installed runtimes
docker compose exec workerserver mise ls

Related Documentation

• mise Runtime Manager Official Docs
• mise Plugin Registry
• Supported Tools and Versions

Next Steps

Custom Images

Build custom Docker images with system dependencies

Troubleshooting

Common issues and solutions