Runtime overview

A runtime is the long-running process on each tenant's VPS that takes a chat turn, calls the LLM, runs Skills, and reports usage back to the control plane. HydraCore is multi-runtime by design: every runtime implements the AgentRuntime Protocol so the chat proxy, restart endpoints, health checks, and telemetry ingestion treat them uniformly.

How runtime selection flows

1. Each Recipe references a manifest_id (e.g. openclaw-basic).
2. Each Manifest declares its runtime_type (e.g. expressclaw, hermes, goose).
3. The provisioning worker dispatches to _RUNTIME_TYPE_DIRS[runtime_type] for the runtime-specific bundle source.
4. Cloud-init's artifact-pull fragment branches on runtime_type to extract the bundle to the right path and start the right systemd service.

Tenants pick a runtime via the wizard's runtime-picker step (gated behind the experimental flag for non-default runtimes) or by setting manifest_id directly on POST /v1/instances or POST /v1/recipes/deploy.

Adding a new runtime

The Hermes (commit 2dfb8b5) and goose (commit f225a37) tracks established the pattern:

1. Add the runtime to the RuntimeType Literal, ORM CheckConstraint, and frontend RuntimeType union (one alembic migration per addition).
2. Drop a templates/fragments/<runtime>.yaml.j2 cloud-init fragment.
3. Drop a templates/runtimes/<runtime>/ shim (install.sh, http-adapter.py, hydracore-emitter.py, README, pyproject.toml).
4. Author a templates/manifests/<runtime>-basic.yaml + .lock with experimental: true until the inner LLM hookup lands.
5. Implement src/runtimes/<runtime>.py against the AgentRuntime Protocol; register in src/runtimes/__init__.py.
6. Add the runtime to _RUNTIME_TYPE_DIRS in src/provisioning/bundle.py.
7. Branch templates/fragments/artifact-pull.yaml.j2 for the new runtime in three places (secrets-409 recovery, Phase 5 extract + install, Phase 6 service start).

The catalog below is regenerated from the live templates/manifests/ tree on every docs build.

Catalog

See Catalog for the auto-generated runtime list (every manifest with its runtime, footprint, experimental status, and source files).