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.
Stack List
The stack list page shows:
Click a row to open the stack detail page.
Status Values
Creating a Stack
- Click Add Stack on the list page
- Enter a name and an optional description
- 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.
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, andkoioslicenseare 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:
Or capture the environment you are working in:
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:
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
- Open a component environment
- Open the environment settings from the gear on the environment bar and select Configuration
- Choose the stack under Stack
- 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.