Docs Blog Apps Pricing

Getting Started

1. Install the CLI 2. Login 3. Build and Push 4. Boot on GCP 5. Boot on Bare Metal

Guides

Authentication Pushing and Pulling Images Configuring Images Working with Hosts Working with GCP Working with Bare Metal latitude.sh OVHcloud Working with AWS Backups Tips and Tricks

CLI Reference

kheeper auth kheeper authorizations kheeper bots kheeper clouds kheeper contexts kheeper hosts kheeper images kheeper orgs kheeper push kheeper releases kheeper status

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 us.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.