> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/stormkit-io/stormkit-io/llms.txt
> Use this file to discover all available pages before exploring further.

# Runtimes

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

<Note>
  You must be an **administrator** to access runtime management.
</Note>

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](https://mise.jdx.dev/)** (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

<Steps>
  <Step title="Log into Dashboard">
    Log into your **Stormkit Dashboard**.
  </Step>

  <Step title="Open Admin Panel">
    Click on your **Profile** in the top right corner, then select **Admin**.
  </Step>

  <Step title="Navigate to Runtimes">
    Go to **System** > **Installed runtimes** (or navigate directly to `/admin/runtimes`).
  </Step>
</Steps>

## Managing Installed Runtimes

### Adding a Runtime

<Steps>
  <Step title="Click Add Row">
    In the Installed Runtimes section, click **Add Row**.
  </Step>

  <Step title="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`
  </Step>

  <Step title="Save Changes">
    Click **Save** to install the runtime.
  </Step>
</Steps>

**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              |

<Note>
  Refer to the [mise documentation](https://mise.jdx.dev/) for a complete list of supported tools and their naming conventions.
</Note>

### Removing a Runtime

<Steps>
  <Step title="Locate Runtime">
    Find the runtime you want to remove in the list.
  </Step>

  <Step title="Click Remove Icon">
    Click the **×** icon next to the runtime.
  </Step>

  <Step title="Save Changes">
    Click **Save** to apply the removal.
  </Step>
</Steps>

<Warning>
  Removing a runtime that's actively used by deployed applications may cause deployment failures. Ensure no applications depend on the runtime before removing it.
</Warning>

## 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

<Steps>
  <Step title="Navigate to Runtimes">
    Go to **System** > **Installed runtimes** in the Admin Dashboard.
  </Step>

  <Step title="Toggle Switch">
    Use the switch under **Auto install** to enable or disable the feature.
  </Step>

  <Step title="Save Changes">
    Click **Save** to apply your preference.
  </Step>
</Steps>

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

## Mise Runtime Manager

Stormkit relies on **[mise](https://mise.jdx.dev/)** 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

<Steps>
  <Step title="Navigate to Mise Section">
    Scroll to the **Mise** section in the runtime management page.
  </Step>

  <Step title="Click Upgrade">
    Click **Upgrade to latest** to install the newest stable release of mise.
  </Step>

  <Step title="Wait for Completion">
    Stormkit will fetch and install the latest version. This may take a few moments.
  </Step>

  <Step title="Verify Version">
    The displayed version number will update after the upgrade completes.
  </Step>
</Steps>

<Warning>
  Upgrading mise does **not** automatically upgrade installed runtimes. You'll need to update runtime versions manually in the Installed Runtimes section.
</Warning>

## 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

<Warning>
  Follow these best practices for production deployments:
</Warning>

* **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

```bash .nvmrc theme={null}
# ✅ 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:

```bash theme={null}
# 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:

```bash .env theme={null}
# 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:**
   ```bash theme={null}
   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:**
   ```bash theme={null}
   # .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:**
   ```bash .env theme={null}
   STORMKIT_RUNNER_CONCURRENCY=8
   ```
4. **Persist mise cache** by mounting the home directory (see [Custom Images](/self-hosting/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](/self-hosting/custom-images) for details.

## Monitoring Runtime Usage

Track runtime usage through deployment logs:

```bash theme={null}
# 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](https://mise.jdx.dev/)
* [mise Plugin Registry](https://mise.jdx.dev/plugins.html)
* [Supported Tools and Versions](https://mise.jdx.dev/lang/)

## Next Steps

<CardGroup cols={2}>
  <Card title="Custom Images" icon="docker" href="/self-hosting/custom-images">
    Build custom Docker images with system dependencies
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/self-hosting/troubleshooting">
    Common issues and solutions
  </Card>
</CardGroup>