Component Libraries

Navigate to Components > Libraries to manage component library packages. A library is a .kcl (Koios Component Library) file containing one or more component types that can be instantiated on an environment canvas.

To build one, see the Component Builder SDK.

Library List

The library list page shows all uploaded libraries grouped by name. Each row displays:

Column	Description
Name	Library name
Version	The active version. Not active appears here when no version is active, an up-arrow when a newer version has been uploaded, and +N more when other versions exist
Components	Number of component types in the active version (the latest version when none is active)
Description	Library description from the package metadata
Created	When the active version was uploaded (the latest version when none is active)

Click a row to open the library detail page.

Uploading a Library

Click Upload Library at the top of the list page
Drag and drop a .kcl file into the upload area (or click to browse)
Koios validates the package metadata and extracts component definitions
On success, you are taken to the library detail page

File format

Libraries must be packaged as .kcl files using the Koios Component Builder. See Building Components for details.

The first version of a new library is activated automatically, provided the security audit built into the package is clean. If the audit reports high-risk findings, or is present but cannot be read, the version installs inactive so you can review the findings before it goes live. Uploading a new version of an existing library never activates it on its own — you are prompted to review and activate it.

Upload Limits and Safety

Maximum size: 500 MiB. Uploads above this size are rejected before the file is read into memory. A full data-science stack (numpy + pandas + scipy + sklearn) lands around 110 MiB, leaving plenty of headroom for typical ONNX bundles and additional dependencies.
Safe extraction. The platform rejects archives that contain path-traversal entries (zip slip), absolute paths, or malformed member names. Bundled wheels are extracted into an isolated location and their metadata is filtered before installation.
File type. Only .kcl packages are accepted. A raw .whl is rejected with a pointer to the builder's .kcl export, as is any other file type.
Duplicate versions. Uploading a version of a library that already exists is rejected. Increment the version number and package again.

Library Detail

The library detail page has up to five tabs. Documentation appears only when the library includes a README.

Overview

Shows all uploaded versions of this library, sorted by version number (newest first). Each version row shows:

Version: semantic version (e.g., 1.2.0)
Status: Active, Inactive, or Invalid
Created: upload date
Instances: how many component instances use this version
Actions: Activate, View, or Delete

Components

Lists all component types defined in this library. Click a component to view its full specification:

Inputs: fields that receive data (name, type, description, default value)
Outputs: fields that produce data
Configuration: static settings that don't change at runtime (with constraints like min/max values and dropdown choices)

Dependencies

Shows the library's package dependencies:

Bundled Packages: third-party packages that are included in the .kcl file and installed when the library is activated
Platform Packages: packages that are already pre-installed in the Koios container and do not need to be bundled. If a dependency is satisfied by a platform package, it is listed here with the installed version.

Documentation

If the library includes documentation (a README), it is rendered here.

Danger Zone

Permanently delete all versions of this library. You must type the library name to confirm. If any instances exist, they will also be deleted.

Activating a Version

Only one version of a library can be active at a time. The active version determines which component types are available on the canvas.

To activate a different version:

Open the library detail page
On the Overview tab, click Activate next to the version you want
A migration preview appears showing:
- Component changes: which component types were added, removed, or modified
- Affected instances: which existing instances will be migrated or deleted
- Wires to remove: any wires that connect to fields that no longer exist
- Security findings: the audit built into the package, when it carries one
Review the changes and click Activate (or Upgrade / Downgrade depending on the version direction)

Removed components

If a component type was removed in the new version, all instances of that type will be permanently deleted along with their wires. The migration preview shows exactly what will be affected before you confirm.

Koios automatically detects whether the activation is an upgrade, downgrade, or lateral move based on semantic versioning.

Security Findings

The preview reports what the package's own security audit found. A library built before audits existed simply notes that none is included, which is a normal state and blocks nothing.

Two cases require you to acknowledge them before the Activate button becomes available:

The audit reports high-risk findings
The audit is present but could not be read, so its findings are unknown

Tick the acknowledgement box under the preview to proceed.

Versioning

Libraries use semantic versioning (major.minor.patch) with optional pre-release tags (e.g., 1.0.0-beta.1).

When you upload a new version of an existing library:

The new version appears as Inactive in the version list
The previously active version remains active until you explicitly activate the new one
You can have multiple inactive versions uploaded at the same time
Activating a version migrates all existing instances to the new component definitions

What's Next

Component Environments: create an execution context for your components
Component Canvas: add instances of library components to an environment
Building Components: create your own component libraries

Components Component Environments