Your server
Install the keko command on a Linux server or another Mac, add it to your account, and pick it when you start a thread
A thread can run on a machine you own: a VPS, a home server or another Mac. Its commands, files and worktrees stay on that machine, and you pick it when you start the thread. Threads keep running when your Mac sleeps.
In the Mac app, Settings → Devices → Add a server shows the line to run and lists the server as soon as it connects. The same steps, by hand:
What you need
- Linux on x64 or arm64 with glibc (Debian, Ubuntu, Fedora and most others), or macOS. Alpine and other musl-based systems aren't supported. Windows comes later.
git, for threads' worktrees, andcurlorwgetfor the install.- An outbound internet connection. The machine connects out to Keko, so it needs no open ports or public address.
Install
Install it as the user that should run threads, since threads run commands with that user's permissions. On a shared server, create a dedicated user for it first.
curl -fsSL https://keko.run/install.sh | shThe script downloads the keko command for your system, checks its SHA-256 checksum against the release's list
over HTTPS, checks that it runs and installs it in ~/.keko/bin, with a link in a folder on your PATH when there is
one. If there isn't, it prints the line to add to your shell's profile. It refuses to run as root; to run it as
root anyway, add -s -- --allow-root after sh.
Add the machine to your account
keko loginUntil ~/.keko/bin is on your PATH, run it as ~/.keko/bin/keko login. It shows a link and a short code.
Open the link on any device, sign in, check the code and the machine it names, and approve. Back in the terminal,
confirm that the account and the device name are yours. Give it another name with --name; the default is the
machine's host name. Running it again adds the machine again and removes the old device; if the service is installed,
it restarts with the new sign-in.
Install what threads use
keko setupOn Debian, Ubuntu, Fedora, RHEL 8 or newer, Oracle Linux, Rocky Linux and AlmaLinux it installs what threads use on Keko Cloud, so they can do the same here:
--tools: git, the GitHub CLI, Node.js, Bun, Python and build tools.--desktop: a desktop threads can see and drive, Google Chrome on x64 or Chromium on arm64, ffmpeg for recordings, and the stream for the Desktop tab. See Proof of work.--previews: threads' web servers open as previews through Keko. No ports are opened.
With no options it does all three; --docker adds Docker Engine when it isn't there. It shows what it will install and
asks first, runs as you and uses sudo only to install packages and add the vendors' signed repositories (Google's for
Chrome, GitHub's, Docker's, EPEL). Bun is checked against its published SHA-256. It doesn't touch running containers,
SELinux or the firewall. Running it again installs only what's missing. Settings → Devices shows what each server
can do, with the line to run for what it can't.
The desktop is yours alone: it has its own display, which other accounts on the server can't connect to, since every connection needs the display's key and only your account has it. Its stream reaches the Desktop tab only through Keko. Every thread on the server shares that one desktop, where each Keko Cloud thread has a machine of its own, so the first time a thread asks to click or type there, the card says the other threads on the server share it.
Run threads on it
keko connectWhile it runs, the machine shows as online in the app's device menu and in Settings → Devices, and new threads can run on it. Ctrl-C stops it. To keep it running without a terminal, install it as a service:
keko service installOn Linux that's a systemd user service; it runs while you're logged in, and sudo loginctl enable-linger $USER keeps it
running after you log out and after a restart. Its logs are in journalctl --user -u keko -f. On macOS it's a
launchd agent that starts when you log in, with its logs in ~/Library/Logs/Keko/keko.log. Threads' commands get the PATH you had when you installed the service, so
install it again after you add tools. keko service status says whether it's running, and
keko service uninstall removes it.
On a shared server, cap the memory threads may use together, browsers and the desktop included:
keko service install --memory 6GThat needs Linux with systemd and its memory controller for user services (Debian 11, Ubuntu 20.10, RHEL 9, Oracle
Linux 9 or newer have it). The size needs its unit and at least 1G; it's kept for the next install, setup and update,
and --memory none removes it. When the server can't enforce it, it says so and installs nothing. How many threads may
run at once is Settings → Devices › the server › Threads at once.
When Keko Cloud is out of starts or hours
You can pick your server for any thread. Keko Cloud has a number of machine starts a day and your plan has its hours. In Settings → Devices › When Keko Cloud is out of starts or hours, choose what new Keko Cloud threads do then:
- Ask me, the default: the new-thread menu marks Keko Cloud unavailable and suggests your server.
- Use one of your servers: the thread starts there, clones the repository and says so in the thread.
- Wait: the thread is made and waits, says until when, and starts on Keko Cloud by itself. Until then, opening it offers Run on your server now and Stop waiting.
Threads that are already running stay where they are.
What servers don't do
A server is one machine you own, so some of what Keko Cloud does with its machines doesn't apply:
- No snapshots, forks or resizing. Those need a provider that can copy and resize machines.
- No stopping when idle and no clearing after 14 days. A server costs you the same when it's idle, and a thread's worktree stays on it until you archive the thread.
- Keko can't start a server that's off. A thread whose server is offline waits up to 24 hours for it to come back; after that, the step doesn't run and the thread says so.
GitHub projects
A thread on a server can work on a GitHub repository you pick, like one on Keko Cloud: Keko clones it into
~/.keko/projects/github/<owner>/<name> on the server, or fetches it when it's there already, and starts the
thread's worktree from it. Each repository has one copy there, shared by the threads that work on it.
Which GitHub sign-in it uses:
- The server's own, when
kekofinds one: a signed-in GitHub CLI (gh auth login) or a git credential helper for github.com. Clones, fetches and pushes run as that account, the way they would in your terminal there. - The GitHub App, when the server has no sign-in of its own, or when GitHub refuses the server's for a repository. Private repositories then need the app installed on them; when it isn't, the thread says so. A push that went through the app instead of the server's sign-in leaves a note in the thread.
Nothing waits for a password: a sign-in that would ask for one counts as refused.
Choose the folders threads may use
Threads work in your home folder until you name folders. Add and remove them while it's stopped, or restart it afterwards:
keko dirs add ~/src/api ~/src/web
keko dirs list
keko dirs remove ~/src/webkeko connect --dir ~/src/api uses other folders for one run without saving them.
Update
keko updateIt downloads the latest version, checks its checksum, replaces itself and restarts the service if it's installed. If
the service doesn't start with the new version, it puts the previous one back. It never goes back to an older version.
Running the install script again does the same. keko --version shows the version you have.
Check on it
keko status shows the account, the device, whether it's online, its folders and the service.
Remove it
keko service uninstall
keko logout
rm -rf ~/.kekologout removes the device from your account and signs this machine out. Deleting ~/.keko also removes the
threads' worktrees on it and the copies of repositories in ~/.keko/projects, so push anything you want to keep
first. Remove the link the installer made, too, if it made
one (~/.local/bin/keko, say).
Security
- Threads run commands as the user that runs
keko, with that user's files and permissions. Use a dedicated user on a shared server, and don't run it as root. - Keko keeps file operations and working folders inside the folders you allowed. That isn't a sandbox: a command can still reach anything the user can.
- Every request from Keko is signed, and the machine checks the signature before it runs anything, so someone between the machine and Keko, or with a copy of its pairing, can't make it run commands.
- The sign-in is saved in
~/.keko, readable only by its user. On macOS it's in the login keychain, or in that file when the keychain is locked (signing in over SSH). - Only approve a sign-in code you started yourself on that machine. Whoever has the code can add their machine to your account.
- A log of what threads ran and changed on the machine is in
~/.keko/dock/audit.log.
Every command and option is in the keko command.