Ubuntu Zombie adds a private, root-capable AI Systems Administrator account to supported Ubuntu Desktop LTS machines so an owner can ask the machine to diagnose, explain, configure, repair, and operate itself.
It is a normal Ubuntu PC with an administrator inside it. Any local user can open a private chat, ask the machine to do something, see exactly what is proposed, approve it, and watch it happen. Everything the AI does is audit-logged. SSH is key-only and root-disabled; optionally restrict inbound access to a private Tailscale tailnet by opting in at install time. The operator owns the machine, the SSH key, the API key, and the kill switch.
git clone https://github.com/japer-technology/ubuntu-zombie.git
cd ubuntu-zombie
chmod +x scripts/install.sh
sudo ./scripts/install.sh install --dry-run # preview the plan (no changes)
sudo ./scripts/install.sh install
sudo reboot
# after reboot:
/opt/ai-zombie/bin/verify
sudo /opt/ai-zombie/bin/secrets-edit # add an LLM API key
sudo systemctl restart ubuntu-zombie-chat.service
# open http://127.0.0.1:7878/ locally, or tunnel over SSH:
ssh -L 7878:127.0.0.1:7878 zombie@<host-name-or-ip>The installer needs only two inputs from you to proceed: an
SSH_PUBLIC_KEY and a VNC_PASSWORD. It prompts for both
interactively, or reads them from the environment in non-interactive
mode (ZOMBIE_NONINTERACTIVE=1). An LLM API key is added after
install. Tailscale is off by default; opt in with
ZOMBIE_SKIP_TAILSCALE=0 to restrict inbound SSH to your tailnet. The
full list of inputs and their defaults is in
docs/QUICKSTART.md.
If you do not already have an SSH key on the workstation you will use
to control this PC, create one there (not on the Ubuntu Zombie box)
with ssh-keygen -t ed25519, then pass the public half
(~/.ssh/id_ed25519.pub, the line starting ssh-ed25519 …) as
SSH_PUBLIC_KEY. Full steps — including copying the key from GitHub —
are in docs/QUICKSTART.md.
During an interactive install the script can also auto-detect a
local LLM: it scans your LAN for an OpenAI-compatible server (LM
Studio, Ollama, llama.cpp) and offers any models it finds as the
starting model, wiring it up as the lmstudio provider so you can run
fully offline with no cloud API key. Skip it with
ZOMBIE_SKIP_LLM_SCAN=1. See
docs/QUICKSTART.md
and docs/CONFIGURATION.md.
Prefer a .deb? Each GitHub Release
ships ubuntu-zombie_<version>_all.deb plus a SHA-256 checksum file and
keyless cosign signatures. After sudo apt install ./ubuntu-zombie_<ver>_all.deb,
the ubuntu-zombie wrapper accepts the same subcommands as
scripts/install.sh. See docs/UPGRADING.md and
docs/FAQ.md for verification commands.
Full walkthrough with expected output and failure branches:
docs/QUICKSTART.md.
sudo ./scripts/install.sh install # full install or upgrade, idempotent
sudo ./scripts/install.sh verify # read-only state check
sudo ./scripts/install.sh doctor # explain failures
sudo ./scripts/install.sh repair # fix known-safe drift
sudo ./scripts/install.sh uninstall # reverse the install
To upgrade an existing host (or refresh after fixing a bug upstream),
pull the latest source and re-run install:
cd ubuntu-zombie
git pull
sudo ./scripts/install.sh install
sudo systemctl restart ubuntu-zombie-chat.serviceSee docs/QUICKSTART.md
for the non-interactive variant and when a reboot is required.
Non-interactive variants and every environment variable: see
docs/CONFIGURATION.md and --help.
| Document | When to read it |
|---|---|
docs/VISION.md |
What this project promises (and does not) |
docs/QUICKSTART.md |
First successful install in ten steps |
docs/PLATFORMS.md |
Supported Ubuntu versions and architectures |
docs/CONFIGURATION.md |
Provider keys, Tailscale, VNC, chat, policy |
docs/VNC.md |
Why/how the VNC password is used, and if required |
docs/TROUBLESHOOTING.md |
Common failures and their fixes |
docs/FAQ.md |
Quick answers distilled from the above |
docs/UPGRADING.md |
Version-by-version upgrade notes |
SECURITY.md |
Trust model, what the provider sees, disclosure |
SUPPORT.md |
Where to ask questions, file bugs, get help |
docs/ARCHITECTURE.md |
Components, action classes, trust boundaries |
CONTRIBUTING.md |
How to test and change the installer |
RELEASE.md |
How maintainers cut a release |
CODE_OF_CONDUCT.md |
Community expectations |
LICENSE |
MIT license terms |
CHANGELOG.md |
Versioned release history |
docs/research/ |
Background notes on alternatives we evaluated |
The local zombie Linux user (renameable at install time with
ZOMBIE_USER=<name>) is the operating identity of the AI
Systems Administrator and holds passwordless sudo. The configured
cloud LLM provider authenticates the administrator. The operator owns
the machine, the SSH private key, the API key, and (if Tailscale is
enabled) the Tailscale account, and can rotate, revoke, or uninstall
any of them at any time. Privileged actions go through a local policy
gate before sudo. Every action is audit-logged. The chat and VNC
services bind to 127.0.0.1 only. Tailscale is off by default; opt in
with ZOMBIE_SKIP_TAILSCALE=0 to confine inbound SSH to your tailnet.
Read SECURITY.md before running the installer.
Ubuntu Zombie is released under the MIT License. By contributing you agree your contributions are released under the same license.