working-with-runtime-system

Runtime registration in the kdn architecture works through a centralized Registry that manages discovery, with automatic registration setup handled via pkg/runtimesetup to expose available backends. The Registry manages the registration workflow and allows engineers to inspect available platform-specific packages.

The Runtime interface contract is defined in pkg/runtime/runtime.go and specifies the mandatory methods all runtimes must implement. It serves as the foundation that platform-specific implementations like podman and openshell build upon to integrate with the system.

To integrate a new runtime, you implement the Runtime interface contract and utilize centralized registration via pkg/runtimesetup for automatic discovery. The system supports platform-specific packages, allowing new backends to be registered and exposed through the Registry.

The runtime manager enforces safety constraints through state validation, ensuring valid WorkspaceState across all runtimes and mapping platform states. It enforces path containment rules to guarantee safe operation during runtime registration and execution workflows.

Yes, you can extend runtime behavior using optional interfaces and extensions such as StorageAware, AgentLister, FlagProvider, Terminal, HostResolver, ConfigTransformer, and Experimental. These optional interfaces allow runtimes to declare additional capabilities beyond the core Runtime contract.

If your runtime is not discovered during automatic registration, verify that centralized registration setup via pkg/runtimesetup is correctly configured. The Registry manages runtime discovery, so failures typically indicate the runtime implementation was not properly registered or the automatic registration setup was bypassed.