> ## 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.
# Pulse: Running and Validating Compiled Kairo Applications
> Use the Pulse runtime to validate and run compiled Kairo applications, and understand entrypoint signatures, exit codes, and startup validation.
Pulse is the official Kairo runtime. It takes the compiled artifacts that Forge produces and executes them. Pulse handles everything that happens after the build: loading artifacts, validating runtime metadata, resolving the declared entrypoint, creating the root execution boundary, running the application's async scheduler, and mapping the application's outcome to a process exit code. Pulse does not compile source code and does not resolve packages — those responsibilities belong to Forge.
## What Pulse does
When you invoke `pulse run`, Pulse performs the following steps in order:
Pulse reads the Forge-built artifacts from the package's `build/` directory.
Pulse checks that all required metadata is present, that artifact versions
are consistent, and that the declared runtime contract is compatible with
this version of Pulse.
Pulse locates the function named by the `entry` field in `[application]`
within the loaded artifact.
Pulse establishes the root boundary that scopes the lifetime of the
running application.
Pulse calls the entrypoint function to start the application.
Pulse drives the async scheduler for the lifetime of the application,
dispatching tasks as they become ready.
Pulse exposes `Pulse.Console.out` and `Pulse.Console.error` for standard
output and error output. Root faults (unhandled errors at the boundary)
propagate to process termination.
When the entrypoint returns (or a root fault occurs), Pulse maps the
outcome to an exit code and performs a clean runtime shutdown.
## Commands
### `pulse validate`
```bash theme={null}
pulse validate [package-root]
```
Validates the Forge artifacts in the given package root — or in the current directory if no path is provided — without executing the application. Pulse checks that all required artifact files are present, that metadata versions are internally consistent, and that the runtime contract declared in `kairo.toml` is compatible. Use this to confirm a build is runnable before deploying it.
```bash theme={null}
# Validate artifacts in the current directory
pulse validate
# Validate artifacts in a specific package directory
pulse validate ./packages/Astra.Sales
```
Run `pulse validate` in your CI pipeline after `forge build` to catch
contract mismatches and missing artifacts before they reach a deployment
environment.
### `pulse run`
```bash theme={null}
pulse run
```
Loads and runs the application from the Forge-built artifacts in the current directory. Pulse validates the artifacts (same checks as `pulse validate`) before executing. If validation fails, Pulse exits with code `3` and reports the problem without starting the application.
```bash theme={null}
# Build first, then run
forge build
pulse run
```
Pulse must be invoked from the package root (the directory containing
`kairo.toml` and `build/`). It reads the manifest to locate the `entry`
field and the `build/` directory for artifacts.
## Entrypoint signatures
The function named by the `[application].entry` field in your manifest must match one of the following signatures. Pulse accepts all of them:
| Signature | Description |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `public func main()` | Synchronous void entrypoint. Success maps to exit `0`. |
| `public func main(): Int32` | Synchronous integer entrypoint. The return value becomes the exit code. |
| `public func main(): Result` | Synchronous result entrypoint. `Result.success(n)` → exit `n`; `Result.failure(...)` → Pulse-generated non-zero exit. |
| `public async func main()` | Async void entrypoint. Completion maps to exit `0`. |
| `public async func main(): Int32` | Async integer entrypoint. The resolved value becomes the exit code. |
| `public async func main(): Result` | Async result entrypoint. `Result.success(n)` → exit `n`; `Result.failure(...)` → Pulse-generated non-zero exit. |
```kairo theme={null}
// Simplest valid entrypoint
public func main() {
Pulse.Console.out.writeLine("Hello, world!")
}
// Exit code control
public func main(): Int32 {
let result = runApp()
return result
}
// Full async result entrypoint
public async func main(): Result {
let outcome = await bootstrap()
return outcome
}
```
## Exit codes
Pulse maps every possible application outcome to a well-defined process exit code:
| Exit code | Cause |
| --------- | -------------------------------------------------------------------------------------------- |
| `0` | Successful completion of a void entrypoint, or `Result.success(0)` return. |
| *n* | `Int32` return value *n* from an integer entrypoint. |
| Non-zero | `Result.failure(...)` returned from a result entrypoint — Pulse generates the specific code. |
| `2` | An unhandled root fault propagated to the execution boundary. |
| `3` | Startup or artifact failure (missing artifacts, contract mismatch, invalid metadata). |
Exit code `3` means Pulse could not start the application at all — the
problem is in the artifact or runtime configuration, not in your application
logic. Run `pulse validate` to diagnose artifact issues without attempting
execution.
## What Pulse does not do
Pulse is a **runtime only**. It has a narrow, well-defined scope:
* **Pulse does not compile source code.** Run `forge build` to produce artifacts first.
* **Pulse does not resolve or restore packages.** Run `forge restore` to update `forge.lock`.
* **Pulse does not accept source `.ak` files directly.** It only loads Forge-built artifacts from `build/`.
* **Pulse rejects incomplete or incompatible artifacts.** If metadata is missing or the runtime contract version does not match, Pulse exits with code `3` and reports a `PLS`-prefixed diagnostic.
## Diagnostic codes
Pulse emits diagnostics with the `PLS` prefix when it encounters problems with artifacts or runtime configuration:
| Prefix | Subsystem |
| ------ | ---------------------------------------------------------------------------------- |
| `PLS` | Pulse runtime (artifact validation, contract compatibility, entrypoint resolution) |
```
[PLS-0003] Runtime contract mismatch: artifact declares contract "0.1",
but this Pulse version supports "0.2" and above.
Rebuild with a compatible version of Forge.
```
## Next steps
Build your application artifacts with Forge before running them with Pulse.
Configure your entrypoint and runtime contract in `kairo.toml`.