> ## Documentation Index
> Fetch the complete documentation index at: https://docs.astrakairo.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# kairo.toml: Complete Kairo Package Manifest Reference
> Learn how to configure your Kairo package using kairo.toml, including package metadata, application entry points, and runtime configuration.
Every Kairo package is described by a `kairo.toml` file at the package root. This manifest tells Forge what the package is, what version it is at, which version of the Kairo language it targets, and — for applications — how to start it. `kairo.toml` uses the [TOML](https://toml.io) format and must begin with `manifest_version = 1`. Forge reads this file as the first step of every build pipeline operation.
## Full manifest example
The following example shows a complete `kairo.toml` for an application package. Annotated comments explain each field.
```toml theme={null}
# Required. Must be 1.
manifest_version = 1
[package]
# Dot-separated PascalCase identifier unique within the registry.
name = "Astra.Sales"
# Major.Minor.Build.Candidate version string.
version = "1.2.3.0"
# The Kairo language version this package targets.
language_version = "0.1"
# "application" or "library". Only libraries may be dependencies.
kind = "application"
[dependencies]
# Exact versions only — no ranges, no "latest".
Astra.Data = "1.0.0.0"
Astra.Http = "2.1.0.0"
[application]
# Fully qualified name of the entrypoint function.
entry = "Astra.Sales.Program.main"
[runtime]
# The runtime engine that will execute this application.
engine = "Pulse"
# The runtime contract version this application was built against.
contract = "0.1"
```
A library package omits the `[application]` and `[runtime]` sections entirely:
```toml theme={null}
manifest_version = 1
[package]
name = "Astra.Data"
version = "1.0.0.0"
language_version = "0.1"
kind = "library"
[dependencies]
Astra.Core = "3.0.0.0"
```
## `[package]` fields
The package's unique identifier in the registry. Must be written in
**dot-separated PascalCase** — each segment starts with an uppercase letter
and segments are joined with `.`. Examples: `Astra.Customers`,
`Astra.Platform.Logging`. Single-segment names (e.g., `Customers`) are
permitted but discouraged; use a namespace prefix to avoid collisions.
The package version in `Major.Minor.Build.Candidate` format. All four
components are non-negative integers. Example: `1.2.3.0`. See
[Version format](#version-format) below for the meaning of each component.
The Kairo language version this package is written for. Forge uses this to
select the correct language rules and standard library surface. Use `"0.1"`
for the current release.
Either `"application"` or `"library"`. Applications declare an entrypoint
and are executed by Pulse. Libraries expose a public API and may be listed as
dependencies. An `application` package cannot appear in another package's
`[dependencies]` section.
## Version format
Kairo versions follow a four-component scheme: `Major.Minor.Build.Candidate`.
| Component | Position | Meaning |
| ----------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| `Major` | 1st | Breaking change. Incrementing this signals that the public API is not backward-compatible with the previous major version. |
| `Minor` | 2nd | Additive change. New functionality added in a backward-compatible way. |
| `Build` | 3rd | Correction. Backward-compatible bug fixes and non-functional changes. |
| `Candidate` | 4th | Iteration within a release cycle (e.g., release candidates, internal builds). `0` in a shipped release. |
```toml theme={null}
version = "2.1.4.0"
# │ │ │ └─ Candidate: 0 (final release)
# │ │ └─── Build: 4 (fourth correction)
# │ └───── Minor: 1 (one additive update)
# └─────── Major: 2 (second major version)
```
Exact versions are required everywhere in Kairo manifests. Forge does not
support version ranges or the `latest` keyword. Once a version is published,
it is immutable — you cannot republish a different package under the same
name and version.
## Application-specific fields
When `kind = "application"`, add `[application]` and `[runtime]` sections to complete the manifest.
### `[application]`
The fully qualified name of the entrypoint function that Pulse will invoke
when the application starts. Must include the complete module path and
function name, separated by `.`. Example: `"Sales.Orders.Program.main"`.
See [Pulse](/toolchain/pulse) for the valid entrypoint function signatures.
### `[runtime]`
The runtime engine that executes this application. Use `"Pulse"` for the
standard Kairo runtime.
The runtime contract version the application was built and tested against.
Pulse checks this value at startup and rejects artifacts that declare an
incompatible contract. Use `"0.1"` for the current release.
If you omit the `[application]` or `[runtime]` sections from an application
package, Forge will report an error during the build pipeline. Library
packages must **not** include these sections.
## Multi-package repositories (workspaces)
When a repository contains more than one package, create a `workspace.toml` file at the repository root alongside — but separate from — any individual `kairo.toml` files. A workspace lists its member packages explicitly:
```toml theme={null}
# workspace.toml
workspace_version = 1
[workspace]
members = [
"packages/Astra.Core",
"packages/Astra.Data",
"packages/Astra.Sales",
]
```
Each member path points to a directory that contains its own `kairo.toml`. Forge and Studio both recognise `workspace.toml` as the root of a multi-package project and will operate on all members together unless you target a specific package.
Root your IDE at `workspace.toml` (not an individual `kairo.toml`) when
working in a multi-package repository. Studio will show all member packages
in a unified project view.
## Next steps
Learn how to declare, restore, and lock your package dependencies.
Run `forge build`, `forge check`, and the rest of the Forge command suite.