Skip to content

Installation and first run

Jump to bottom
Valerio edited this page Nov 5, 2026 · 3 revisions

Installation and first run

Kelpy is one executable: kelpy on Linux and macOS, kelpy.exe on Windows. There is no installer and no service: the install command only downloads the executable, which installs itself on its first run.

Install command

On Linux (x86-64):

curl -fsSL https://kelpy.io/install.sh | sh

On Windows, in PowerShell (from cmd.exe, run powershell -c "irm https://kelpy.io/install.ps1 | iex"):

irm https://kelpy.io/install.ps1 | iex

The script downloads the executable for your platform from the latest GitHub release into a temporary folder, checks it against the release's SHA256SUMS, starts it, and deletes the folder when Kelpy stops. The first run does the rest. Without a terminal, for example in cloud-init or CI, Kelpy is started with --yes.

  • A given release: set KELPY_VERSION, as in curl -fsSL https://kelpy.io/install.sh | KELPY_VERSION=v0.1.0 sh, or run $env:KELPY_VERSION = 'v0.1.0' before the PowerShell command.

  • Options for Kelpy (Linux): after sh -s --, as in curl -fsSL https://kelpy.io/install.sh | sh -s -- --home /srv/kelpy.

  • Windows Server 2016: Windows PowerShell 5.1 may not offer TLS 1.2, which GitHub requires, and the command fails with "Could not create SSL/TLS secure channel". Run instead:

    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12; irm https://kelpy.io/install.ps1 | iex

Download by hand

Each release holds kelpy-linux-x86_64, kelpy-windows-x86_64.exe, SHA256SUMS with its signature SHA256SUMS.sig, and the two install scripts, install.sh and install.ps1, which the install command fetches. On Linux:

curl -fsSLo kelpy https://github.com/Ryadel/Kelpy/releases/latest/download/kelpy-linux-x86_64
chmod +x kelpy
./kelpy

On Windows, download kelpy-windows-x86_64.exe from the release and run it. To check a download, compare the output of sha256sum kelpy (Linux) or Get-FileHash kelpy-windows-x86_64.exe (PowerShell) with its line in SHA256SUMS.

To check that SHA256SUMS comes from Kelpy's releases, verify its signature with OpenSSL 3 and release-key.pem:

openssl pkeyutl -verify -pubin -inkey release-key.pem -rawin -in SHA256SUMS -sigfile SHA256SUMS.sig

First run

Run the executable. The first run asks where Kelpy should live:

Where should Kelpy live? It keeps its data, memory and workspace there.
  1) /root/Kelpy   (recommended)
  2) This folder: /root/downloads
  3) Another folder...

Kelpy then creates that folder, the Kelpy home, copies itself into it and asks whether to add the folder to your PATH. No administrator rights are needed:

  • On Windows the folder is added to your user PATH; new terminals find kelpy.
  • On Linux and macOS Kelpy links ~/.local/bin/kelpy; if ~/.local/bin is not on your PATH, Kelpy says so.
  • On removable media the PATH is left unchanged, because drive letters change between sessions.

Kelpy records the home in your user profile, so later runs find it from any folder. It also offers to delete the file you started it from, except when the install command started it. Without a terminal to ask in, or with --yes, every default is taken.

A folder that already holds files of another program with Kelpy's folder names is refused. A folder with other files is accepted after a confirmation; Kelpy adds its own folders next to them.

The Kelpy home

Kelpy/
  kelpy[.exe]     the executable
  config.toml     configuration, including the AI provider and model (never API keys)
  data/           database and runtime state, readable only by you
  memory/         what Kelpy knows about this server, as Markdown files
  workspace/      default folder for the agent's work
  logs/

To use a home without installing anything, for example a test home, run kelpy --home <PATH> or set KELPY_HOME. To remove Kelpy, run kelpy cleanup: see Command line.

Opening the Web UI

Every start prints the Web UI's address with a one-click sign-in link, the access code, the AI provider with whether answers can start, and the account Kelpy runs as:

Kelpy v0.2.0

Agent runtime started.
Web UI:   http://127.0.0.1:54321/#code=K7QM-4ZP2
Code:     K7QM-4ZP2  (to sign in from another browser)
Home:     /root/Kelpy
Provider: Ollama (qwen3.5:9b) - ready (no API key needed)
Account:  root

Press Ctrl+C to stop.

Without administrator rights the account line says so, as in jsmith (not root) or you (not elevated), followed by what fails and how to start Kelpy with them. A provider that cannot answer yet shows what is missing, as in not signed in: sign in from the Web UI or run kelpy provider.

At the end of the first run on a desktop, Kelpy opens the link in your browser; later, run kelpy open. The code is new at every start, so a link from an earlier start no longer signs in. Kelpy listens on 127.0.0.1 only, and reuses the port of its last start when it is free.

On first use the Web UI asks how Kelpy connects to AI: see Connecting to AI.

Through SSH

When Kelpy runs in an SSH session, it also prints the command to run on your own computer, for example:

ssh -N -L 54321:127.0.0.1:54321 root@203.0.113.10

Run it in a terminal on your computer and keep it open; the Web UI link then works in your browser unchanged. Nothing new is exposed on the server.

Updates

At start Kelpy checks for a new release and asks whether to install it; kelpy update does it on request. Updates are installed only with a valid signature. See Command line.

Stopping

Kelpy lives in the terminal that started it and stops on Ctrl+C, when that terminal session ends, with kelpy stop from another terminal, or with Stop Kelpy in the Web UI. Answers being written are stopped and saved as interrupted; open connections get at most 10 seconds to close.

To keep Kelpy available for a while without watching it, give it a limit:

kelpy --shutdown-idle 30m

Kelpy

Clone this wiki locally