KernDocs
KernGitHub ↗

Operate

Manage a self-hosted host

Start, stop, update and recover Kern using its existing Python commands.

Before changing a host

Run commands from your Kern checkout, using the original host name. AWS also needs the original account and region, using either browser sign-in with exported credentials or the scoped deployment credentials. Keep your admin password, SSH key and recovery information outside the VM. For a quick-start host, back up the SSH key pair and connection state under ~/.local/share/kern/hosts/ in private operator-controlled storage. Save the password in your password manager and delete only initial-password.txt. Kern Cloud users should use its managed lifecycle controls.

A local host works only while its computer is on and awake. An AWS host runs until stopped or removed. Closing a browser or SSH tunnel does not stop the VM.

Start, stop and reopen

bash
python3 -m host.cli.stop --provider lima --agent-name my-kern
python3 -m host.cli.start --provider lima --agent-name my-kern
python3 quickstart.py

The last command reopens a quick-start host. For AWS, use --provider aws and reconnect through the configured SSH or HTTPS endpoint.

Update source, then upgrade the host

Review and save any local checkout changes before pulling. A Home notification can report a newer public version; it does not install it.

bash
git pull --ff-only
python3 -m host.cli.upgrade --provider lima --agent-name my-kern

Use --provider aws for AWS. Upgrade interrupts active work and preserves durable data. AWS keeps its instance and swaps the root volume; Lima replaces the VM. See Storage and upgrades.

Choose recovery or reconfiguration

SituationNext step
Compute is missing or unusable; durable data remainsUse recover with the original host name. Add --allow-upgrade only when intentionally advancing older stored data.
Change password or operator endpointsUse reconfigure with the full endpoint list, including the SSH key you want to retain.
Lost public sign-in passkeyFollow passkey recovery in Troubleshooting; use reconfigure --reset-admin-passkeys with the full endpoint list.
Remove a local host and its dataFollow the local removal steps below and identify the exact VM and durable disks before deleting them.

See passkey recovery and CLI arguments. Preserve data and inspect the original error before choosing a recovery command.

Remove a local host and its data

This permanently deletes the VM and its saved work. Find the exact VM name with limactl list and replace the example below. Keep the same LIMA_HOME used for deployment. If resuming cleanup, skip resources that are already absent.

bash
KERN_INSTANCE='kern-my-kern-<hash>'
limactl stop "$KERN_INSTANCE"
limactl delete --force "$KERN_INSTANCE"
limactl disk list

Wait until both data disks show no attached instance, then delete them:

bash
limactl disk delete "${KERN_INSTANCE}-admin"
limactl disk delete "${KERN_INSTANCE}-agent"

Only after both disks are gone, remove the saved credentials and Kern configuration:

bash
rm -rf "$HOME/.local/share/kern/hosts/${KERN_INSTANCE#kern-}"
rm -f "${LIMA_HOME:-$HOME/.lima}/.kern-config/${KERN_INSTANCE#kern-}.json"

Delete the ~/kern source checkout separately if you no longer need it.