Working with Hosts

A host represents a machine managed by Kheeper — a cloud instance, a bare metal server, or any system running a bootc image. Hosts pull releases from the registry and apply configuration locally.

How hosts are created

Hosts can be created in two ways:

Auto-registration

When you boot a machine using a Kheeper-provided image (on GCP or bare metal), the machine automatically registers itself as a host. The host name is derived from the instance name and the host is associated with your org.

Manual creation

You can also create hosts manually:

kheeper hosts create myorg/my-host --public-key-file pub.pem

The --public-key-file must be a PEM-encoded ECDSA P-256 public key. This key is used to encrypt configuration for the host. Only the host's private key can decrypt it.

Listing hosts

# List all hosts
kheeper hosts list

# List hosts in a specific org
kheeper hosts list --org myorg

Inspecting a host

kheeper hosts get myorg/my-host

This shows the host's metadata including its org, name, active tag, and creation time.

Deploying to a host

Deploying to a host is a two-step process: create a release, then activate it.

1. Create a release

A release pairs a configurable image with host-specific configuration:

kheeper releases create myorg/my-host:v1 \
  --image kheeper.com/myorg/webapp:v1 \
  --config-file config.json

2. Activate the release

kheeper hosts activate myorg/my-host:v1

This sets the host's active tag. The host picks up the change on its next poll and applies the new release.

Listing releases

kheeper releases list myorg/my-host

Rolling back

To roll back, activate a previous release tag:

kheeper hosts activate myorg/my-host:v1

Deleting a host

kheeper hosts delete myorg/my-host

This removes the host record from the registry. It does not affect the running machine.

Host repositories

Each host has an associated repository at <org>/hosts/<host-name> in the registry. This repo stores the host's releases. Org owners have full access to all host repos. The host itself has read access to pull its own releases.