---
title: "Stacks"
description: "Isolated package sets that let components use library versions the platform does not ship"
source_url: https://ai-ops.com/docs/components/stacks
---

# Stacks

Navigate to **Components > Stacks** to manage isolated package sets. A stack holds a set of Python packages that only the component environments attached to it can see.

Use a stack when a component needs a library the platform does not ship, or a version that conflicts with the one it does. Components that need nothing special run on the platform's built-in packages and require no stack at all.

---

## How Stacks Work

You upload wheels into a stack. Koios builds the stack from those wheels and runs every attached component environment inside a dedicated worker process.

Packages in a stack take precedence over the platform's, so a stack containing `pandas 2.3.1` gives its components that version even though the platform ships a different one. Everything the platform provides that the stack does not override stays available.

Each stack in use costs one worker process. Budget roughly 200 MB of memory per stack, plus its own pool of connections to the configuration database — 10 by default, able to grow to 30 under load. On a server running many stacks it is usually the connection count, not memory, that binds first. Built stacks also take disk space alongside your other stored data; the stack's Overview tab shows how much.

Reuse a stack across environments rather than creating one per environment. If you do need many, `KOIOS_DB_POOL_SIZE` and `KOIOS_DB_MAX_OVERFLOW` in the environment file tune the per-worker pool.

> [!CAUTION] Uploaded code runs with full privileges
> Only upload wheels from sources you trust. Code installed into a stack runs with full platform privileges on the Koios server.

---

## Stack List

The stack list page shows:

| Column | Description |
|--------|-------------|
| **Status** | Build state, or the state of the worker process running it |
| **Name** | Stack name |
| **Description** | Optional description |
| **Wheels** | Number of wheels installed |
| **Environments** | Number of component environments attached |
| **Worker Memory** | Memory used by the worker process, when one is running |
| **Updated** | Last change |

Click a row to open the stack detail page.

### Status Values

| Status | Meaning |
|--------|---------|
| **Pending** | Queued for building |
| **Building** | Being built now |
| **Build failed** | The build did not finish. Open the **Build** tab for the log |
| **Incompatible** | The stack built, but the component engine cannot run inside it. A wheel here replaces something the engine imports for itself. The **Build** tab lists what the compatibility check found, and the wheel it blamed is marked **Blocked** on the **Wheels** tab |
| **Running** | A worker process is executing attached environments |
| **Worker failed** | The worker stopped unexpectedly. It restarts automatically |
| **Not in use** | Built and ready, but no enabled environment is attached |

---

## Creating a Stack

1. Click **Add Stack** on the list page
2. Enter a name and an optional description
3. Click **Create Stack**

The stack is created empty. Add packages to it next.

---

## Adding Packages

Open the stack and go to the **Wheels** tab. There are two ways to add packages.

### Uploading Wheels

Drag `.whl` files onto the upload area, or click to browse. You can drop several at once — the whole batch triggers a single rebuild.

> [!WARNING] Upload every dependency
> Koios installs exactly the wheels you upload and does not download anything else. Upload the package **and** every package it depends on. A missing dependency surfaces as a failed component environment rather than a failed build.

Wheels must be built for Linux (`manylinux`), for this server's CPU architecture, and for the Python version shown on the stack's Overview tab. Anything else is rejected on upload with a message naming the problem.

Uploads are also refused when:

- **The wheel is part of the Koios runtime.** `koios-component-builder`, `koios-component-engine`, `koiosutility`, and `koioslicense` are provided to every stack already. Your own copy would replace what the component engine itself imports, and workers in that stack would not start. Leave them out of your wheel set — your component can import them without installing them.
- **A wheel of the same filename is already in the stack.** Remove the existing one first to replace it.
- **The file is larger than 500 MiB.**

### Importing a Bundle

A `.kps` bundle collects a package and its full dependency tree in one file. Build one on a development machine with the component builder:

```bash
koios-component-builder export-stack -r requirements.txt --name my-stack
```

Or capture the environment you are working in:

```bash
koios-component-builder export-stack --from-env --name my-stack
```

The bundle downloads Linux wheels for each dependency regardless of the machine you build it on, which makes it the practical way to move a large dependency set onto an air-gapped server.

Click **Import Bundle** on the list page to create a stack from a bundle, or **Import bundle** on the Wheels tab to add its packages to an existing stack.

A bundle may be up to 2 GiB. The 500 MiB limit still applies to each wheel inside it.

---

## The Compatibility Check

Every build ends with a compatibility check: Koios starts the component engine's own machinery inside the finished stack and confirms it still works there. The **Build** tab shows the result as a **Compatibility check** card listing each check with its outcome and how long it took — on a clean build as well as a failing one, so you can see what it covers before you ever need it.

If a check fails, the stack is marked **Incompatible** and the previous working build keeps running. When the check can name the wheel responsible, the stack's Overview offers **Remove this wheel and rebuild**, which deletes it and runs the build and the check again. When it cannot point at one file, use the build log to work out which package to remove.

### Knowing What You Are Replacing

The **Wheels** tab has a **Platform** column showing how each wheel relates to what Koios already provides:

| Label | Meaning |
|-------|---------|
| — | Koios does not ship this package; the wheel simply adds it |
| **Same as platform** | Koios already provides this package at this version, so the wheel changes nothing |
| **Shadows _version_** | Workers in this stack load the package from your wheel instead of the platform's copy |
| **Blocked** | The compatibility check named this wheel as the reason the engine cannot start here |

Click **Platform packages** on that tab for a searchable list of everything the platform already provides, so you can check before uploading whether you need a wheel at all.

---

## When a Component Crashes

Component code runs in a worker process separate from the component engine service, so a crash cannot take the platform down. It is contained to the environments that worker hosts — the ones attached to that stack. Environments attached to no stack share a worker of their own, so a crash there does not touch stack-backed environments.

When a worker goes down:

- Its environments are marked failed, with the reason
- The process restarts on its own, waiting a little longer before each attempt — 1 second, doubling up to a 60-second ceiling
- Once a worker has run for five minutes without incident, the crash count resets
- A worker that keeps crashing is reported once as a crash loop rather than filling the event log with one entry per attempt

---

## Attaching a Stack to an Environment

1. Open a component environment
2. Open the environment settings from the gear on the environment bar and select **Configuration**
3. Choose the stack under **Stack**
4. Click **Save Configuration**

Instances in that environment now run inside the stack. Clearing the field detaches the environment, and its instances go back to running on the platform's built-in packages.

Attaching an environment to a stack that failed to build is allowed, but its instances will not run until the build succeeds.

---

## Rebuilding

Koios rebuilds a stack automatically whenever its wheels change. To rebuild on demand — after a Koios upgrade, or to retry a failed build — open the stack and choose **Rebuild stack** from the actions menu.

The previous build keeps serving throughout. Components carry on running on the packages they already have while the new build is prepared, and they are recycled onto it only once it has actually replaced the installed packages. If the rebuild fails, they keep running on the last good build.

Renaming a stack or editing its description changes nothing about what is installed, so it restarts nothing.

---

## Deleting a Stack

Deleting is blocked while any environment is attached. Detach every environment first; the error message names the ones still using it.

Uploaded wheels are included in backups, so restoring a backup restores your stacks. The built stacks themselves are not backed up — the restore rebuilds them from the stored wheels before it finishes, so they are ready as services come back up.

---

## Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|
| Build failed with a "No solution found" or missing-file error | A dependency was not uploaded | Upload the missing wheels, or import a bundle built with `export-stack` |
| Upload rejected for platform tags | The wheel targets macOS or Windows | Obtain the `manylinux` build of the package |
| Upload rejected for architecture | The wheel is a Linux build for a different CPU architecture | Obtain the build matching the architecture named in the message |
| Upload rejected as part of the Koios runtime | The wheel installs a package the component engine imports for itself | Remove it from your wheel set — your component can import it without installing it |
| Upload rejected as already present | A wheel with the same filename is in the stack | Remove the existing wheel first, then upload the replacement |
| Upload rejected as too large | The file is over 500 MiB | Split the dependency set across uploads, or import a bundle |
| Upload rejected for Python version | The wheel targets a different Python | Match the version shown on the stack's Overview tab |
| Component fails with an import error | The package is present but one of its dependencies is not | Upload the missing dependency and rebuild |
| Stack shows **Incompatible** after a build | A wheel replaces a package the engine imports for itself, at a version it cannot use | Use **Remove this wheel and rebuild** on the stack's Overview. If no wheel was named, read the **Build** tab and remove the offending one by hand. The previous working build keeps running until you do |
| Environment stays stopped | Its stack has not finished building, or the build failed | Check the stack's status and build log |