KernDocs
KernGitHub ↗

Self-hosted

Set up an always-on computer

Deploy Kern on your Mac or Linux computer, then add a secure browser address for your phone.

Choose the computer that will run Kern

Use a Mac or Linux computer you can leave powered on, connected to the internet and awake. Run all setup commands on that computer using your normal user account. You manage its updates and running costs.

If Kern already runs on this computer, keep the same checkout, host name and LIMA_HOME and continue with Cloudflare setup. Installing on a different computer creates a separate host; it does not move your existing agents or data.

Before you start

Use your normal user account on a Mac or Linux computer with hardware virtualization. Keep it powered on and awake while agents work.

  • Python 3.11+, Git, curl and OpenSSH (ssh, scp, ssh-keygen).
  • Lima 2.2 or newer, below 3 ↗. Linux also needs QEMU for your architecture and qemu-img.
  • Allow at least 2 CPUs, 2 GiB RAM and three 16 GiB disks for the VM. Downloads and your work need additional free space.

Quick-start checks these dependencies, shows supported Homebrew or apt installation commands, and asks before installing. The default answer is no. Unsupported systems receive manual instructions.

Kern is licensed under the MIT License ↗. Hosting, AI subscriptions and connected services have separate terms and costs.

Deploy Kern

bash
curl -fsSL https://kernai.cloud/quickstart | bash

The script checks dependencies and asks before installing any. It creates or reuses the source checkout in ~/kern, deploys the my-kern Lima VM, prepares its password and SSH keys, and opens your browser through SSH. Allow time for the first VM and runtime downloads.

Open the local address printed by setup and sign in with the generated password. Its browser port is chosen dynamically. If you changed the checkout directory, use that path in the commands below.

Save your password and keep your SSH keys

Quick-start prints the exact credential paths under ~/.local/share/kern/hosts/my-kern-<hash>/. Save the initial admin password in your password manager, then delete only initial-password.txt. Later password changes are not written to that file.

It creates a dedicated Ed25519 SSH key pair without a passphrase: operator_ed25519 and operator_ed25519.pub. The private key stays on your computer; deployment installs the public key in the VM. Quick-start reuses this pair to connect your browser through SSH. Keep both key files and back them up securely; do not delete them with the password file.

Prepare the Cloudflare endpoint

  1. 1
    Prepare your domain

    Use a domain with active DNS on Cloudflare and complete the required Zero Trust account setup.

  2. 2
    Create a remotely managed cloudflared tunnel

    Copy only its token, which starts with eyJ, from the suggested install command. Kern installs the connector; do not run that command on your laptop. The tunnel can show Inactive or Down until Kern connects.

  3. 3
    Publish an application route

    Choose a hostname such as kern.example.com and point its service URL to http://localhost:7443. Use this exact hostname when reconfiguring Kern. Cloudflare creates the DNS record; do not create a separate one. No Cloudflare Access application is needed because Kern protects the UI with its own sign-in.

Follow Cloudflare's current tunnel setup guide ↗ for dashboard controls. Keep the token private.

Reconfigure a quick-start host

Run these Bash blocks on the computer that owns the Lima VM, one block at a time. Replace kern.example.com with your published hostname. If you chose another checkout directory, substitute it too. This retains the generated SSH key.

bash
cd ~/kern
KERN_LOCAL_STATE=$(python3 -c 'import quickstart; print(quickstart.state_dir("my-kern"))')
read -r -s -p 'Cloudflare tunnel token: ' KERN_CLOUDFLARE_TUNNEL_TOKEN; printf '\n'
bash
KERN_ADMIN_HASH=$(python3 -c 'import getpass, hashlib; print(hashlib.sha256(getpass.getpass("Admin password to set: ").encode()).hexdigest())')
bash
export KERN_CLOUDFLARE_TUNNEL_TOKEN
python3 -m host.cli.reconfigure \
  --provider lima --agent-name my-kern \
  --admin-password-sha256 "$KERN_ADMIN_HASH" \
  --operator-ssh-public-key "$(cat "$KERN_LOCAL_STATE/operator_ed25519.pub")" \
  --operator-cloudflare-hostname kern.example.com
unset KERN_CLOUDFLARE_TUNNEL_TOKEN KERN_ADMIN_HASH
python3 quickstart.py

Enter your current admin password to retain it, or a new one to change it. Reconfiguration interrupts active work and preserves durable data.

Verify access

  1. 1
    Check local recovery access

    Confirm the retained SSH connection and local sign-in still work.

  2. 2
    Open the HTTPS hostname

    Sign in from your phone. The first public sign-in uses your admin password and offers passkey setup. Once enrolled, public sign-in requires both the password and passkey. SSH-forwarded sign-in continues to use the password only.

  3. 3
    Keep the host available

    Leave a local host awake, or run it on AWS or Kern Cloud. Closing your phone browser does not stop the host.

Keep your agents running

Turn off automatic sleep in the computer's power settings and keep it connected to power and the internet. Sleep or shutdown interrupts agent work. After restarting the computer, run the following to start Kern and restore local access:

bash
cd ~/kern
python3 quickstart.py

Once the VM and its tunnel are running, use your HTTPS address from any browser. Closing the browser or local SSH forward does not stop the VM or its Cloudflare connector. Connect your AI accounts and tools to start working.

Stop, start and upgrade

Run these commands from the checkout. Quick-start uses the host name my-kern.

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

To update, review and pull the source changes, then explicitly upgrade the VM. Pulling source alone does not update a running host. Save your own checkout changes before pulling.

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

Upgrade interrupts active work and preserves the durable data disks. For a custom host name or initial VM size, use python3 -m host.cli.deploy --help and the CLI reference. For recovery, reconfiguration and removal, see Manage your host.