Your machine, from one file.
One oku.toml names the tools, dotfiles, secrets and OS settings of your account. A lock pins the sha256 of every download. oku sync builds that machine on Linux, macOS or Windows, and oku rollback puts the previous one back. oku needs no registry, no language to learn and no root.
| Linux | macOS | Windows | Status |
|---|---|---|---|
| Supported | Supported | Supported, no build sandbox | Alpha (Daily driving by myself) |
Manifest keys, CLI flags and behaviour may still change between releases. See the CHANGELOG.
Install · What it does · Publish a package · Compare · Docs
# oku.toml
[packages]
ripgrep = "github:BurntSushi/ripgrep" # a repo with no manifest at all
obsidian = { ref = "cask:obsidian", when = { os = "darwin" } } # a Homebrew cask, without brew
jq = "aqua:jqlang/jq" # the aqua registry, Scoop and winget too
prettier = { ref = "npm:prettier", version = "^3" } # npm, PyPI, Go and crates.io too
atuin = { ref = "github:y3owk1n/oku-config#atuin", service = true } # a daemon
[runtimes]
node = { ref = "github:y3owk1n/oku-config#node", version = "22" } # what npm tools run on
[vars]
font = "JetBrainsMono Nerd Font Propo"
[secrets]
github_token = { file = "./secrets/secrets.yaml", key = "github/token" }
[files]
"{{home}}/.config/nvim" = { link = "./files/nvim" }
"{{home}}/.config/ghostty/config" = { render = "./files/ghostty.tmpl" }
"{{home}}/.ssh/id_ed25519" = { secret = "./secrets/secrets.yaml", key = "ssh/id_ed25519" }
[defaults."com.apple.dock"]
autohide = true
[registry.'HKCU\Control Panel\Keyboard']
KeyboardDelay = "0"
[dconf."org/gnome/desktop/interface"]
color-scheme = "prefer-dark"git clone https://github.com/you/machines ~/.config/oku # a new machine
oku sync # install and apply everything the list and lock name
oku sync --dry-run # what would change, and nothing on the machine changes
oku rollback # the machine as it was before the last changeMore clips, one for each row of What it does, are in Demos.
Tools like Nix with home-manager and nix-darwin can describe a whole machine in a file and roll it back. They ask you to learn a language, take over /nix, and draw from one central package set. Dotfile managers cover the home directory and nothing else. oku keeps the store, the lock and rollback, and leaves out the language, the package set and root.
- One list, one lock, one rollback. Packages, home files, secrets and settings change together. Every change is a generation.
oku rollbackreverts all of it, with no download. - Same input, same machine.
oku.lockpins the commit, the manifest hash and every download's sha256. Two machines with the same two files get the same store paths. - One list for every OS.
includeand per-platformwhenlet one list describe a Mac laptop, a Linux server and a Windows desktop. oku skips the tables of another OS. - No registry. A package is a TOML manifest in the author's repo, a URL, a local file, a repo with no manifest at all, or a package of npm, PyPI, Go or crates.io. oku also reads the recipes of Homebrew casks, Scoop, winget and the aqua registry. It translates each into a manifest of its own, which downloads from the vendor and follows the vendor's versions. oku never runs brew, scoop, winget or aqua, and ships no package list of its own.
- Checked downloads. oku checks each download against a sha256 from the manifest, from upstream's checksum file, or from GitHub, npm or crates.io, and pins it in the lock with what it was checked against. A manifest can also ask for a minisign signature, or a Sigstore signature or GitHub attestation by the workflow that builds the releases.
- Stops when a source changes. oku checks each answer from a forge, a registry or a recipe for what it needs, and asks sources that version their format for one version. A source that changed makes
addandupdatefail with its name, andoku syncstill installs what the lock pins. - TOML, not a language. A manifest has a fixed set of keys and seven build step types.
oku manifest lintchecks all of it. - No root. Everything lives in a private store under your home.
oku self uninstallremoves every file oku wrote. - All or nothing.
add,remove,sync,updateandrollbackcheck everything before the first step and undo a change that fails partway. - Nothing runs unasked. oku unpacks
.deb,.rpm,.pkgand.msifiles and never runs their scripts. A build from source shows you its commands first, then runs them in a sandbox with no network and no access to your home directory.
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/y3owk1n/oku/main/install.sh | s
8000
h# Windows
irm https://raw.githubusercontent.com/y3owk1n/oku/main/install.ps1 | iexThe script puts one static binary in ~/.local/bin, or %LOCALAPPDATA%\oku\bin, after checking its sha256, and its minisign signature when minisign is installed. On macOS and Linux it has oku write its man pages to ~/.local/share/man, so man oku works. It edits none of your files and ends by printing the one line your shell needs. oku self update replaces the binary later, after checking its minisign signature.
From source
git clone https://github.com/y3owk1n/oku && cd oku
CGO_ENABLED=0 go build -o oku ./cmd/okuYou need Go 1.27.0 or newer.
Add the line the installer printed to your shell's startup file. For zsh:
echo '[ -x "$HOME/.local/bin/oku" ] && eval "$("$HOME/.local/bin/oku" hook zsh)"' >> ~/.zshrc && exec zsh
oku add github:sharkdp/fd # install something
fd --version
oku doctor # checks PATH, the shell line, the sandbox and the profilesGetting started walks through a first package, a version change and a rollback in about ten minutes.
| You want to | oku does it with | Guide |
|---|---|---|
| Install a tool from GitHub, GitLab, Codeberg, Gitea, a URL or a file | oku add github:BurntSushi/ripgrep |
Add packages |
Install from npm, PyPI, Go or crates.io without their toolchains on PATH |
oku add npm:prettier and [runtimes] |
Registry packages |
| Install an app from a Homebrew cask, a Scoop or winget manifest, or the aqua registry, without their tools | oku add cask:obsidian, scoop:, winget:, aqua: |
Add packages |
| Try an app or a tool once, without installing it | oku run cask:appcleaner |
Commands |
| Follow a vendor's own update feed, download page or redirect | from = "sparkle", "page" or "redirect" |
Manifest reference |
| Set up every machine from one repo | a git clone at ~/.config/oku and oku sync |
New machine |
| Place dotfiles and templates | [files] and [vars] |
Dotfiles |
| Keep SSH keys and tokens in the repo, encrypted | [secrets] with sops and age |
Secrets |
| Set macOS defaults, Windows registry values or GNOME settings | [defaults], [registry], [dconf] |
OS settings |
| Run a daemon at login, or a job on a schedule | service = true |
Services |
| Give a repo its own tools and environment variables, restored when you leave | an oku.toml with [env] in the repo and oku allow |
Projects |
| Use the same tools in CI | uses: y3owk1n/oku@main |
CI |
| Say what a machine needs that oku does not install, such as Xcode tools or a distro library | [host] |
New machine |
| Undo a change | oku rollback |
Undo and clean up |
Every change is a generation that covers packages, files and settings together. oku generations lists them, and oku rollback switches back without downloading anything.
The install instructions for your software become one line that you control: oku add github:you/tool. Nobody submits anything to any registry.
Many repos need no manifest. When release files follow the usual naming, the line above already works, and oku manifest init --from you/tool writes the manifest oku inferred to oku.pkg.toml, ready to commit. Otherwise a manifest is oku.pkg.toml next to your code:
[package]
name = "tool"
description = "Does one thing"
[version]
from = "github-releases"
repo = "you/tool"
[[artifact]]
match = { os = "linux", arch = "amd64" }
url = "https://github.com/you/tool/releases/download/{{tag}}/tool-{{version}}-linux-amd64.tar.gz"
sha256_url = "https://github.com/you/tool/releases/download/{{tag}}/checksums.txt"
bin = ["tool"]
[build] # used when no artifact fits the machine
needs = ["go"]
when = [{ os = "darwin" }, { os = "linux" }] # sh exists only there
[[build.step]]
run = "go build -o tool ."
shell = "sh"
[[build.step]]
install = { bin = ["tool"] }oku manifest lint # check it
oku manifest test # install it into a throwaway store
oku manifest bump # move it to the newest release, checksums included
oku manifest hash <url> # print the checksums of a downloadPublish a manifest · Manifest reference · Security · Build caches
oku covers what a package manager, a dotfile manager and a settings script do separately. The rows come from each tool's own documentation, checked in September 2026.
| Setup | Tools from | Home files | Secrets | OS settings | Lock with hashes | Rollback | Root | You write |
|---|---|---|---|---|---|---|---|---|
| oku | Any repo, URL or file, npm, PyPI, Go and crates.io packages, and Homebrew cask, Scoop, winget and aqua recipes, translated. No registry of its own | Links, text, templates | sops and age files | macOS defaults, Windows registry, dconf | Always, every download | Packages, files and settings, in one generation | Only to install for every user | TOML, or nothing |
| Nix + home-manager + nix-darwin | nixpkgs, plus flakes | Yes | Separate projects, sops-nix or agenix | macOS defaults, dconf | flake.lock pins inputs, nixpkgs pins each source |
Per tool, each with its own generations | To create /nix, and for every nix-darwin switch |
The Nix language |
| Homebrew + chezmoi | homebrew-core, plus taps | Files, links, templates | Password managers, age, gpg | Scripts you write | No. A Brewfile pins nothing | No. Revert the source in git and apply again | Homebrew, to install on macOS | Ruby, Go templates, shell |
| mise | A registry, backends such as github:owner/repo, and OS packages through apt, brew, winget and others |
Links, copies, templates, tracked files, line edits | Environment variables from fnox, sops or age. Templates can write them to files | macOS defaults | Optional, mise.lock. It pins checksums for downloads, only versions for some backends, and nothing for OS packages |
Files only, from a git history. Tools and packages stay as they are | For OS packages, system files and system services | TOML |
oku fits if you want a machine you can rebuild and roll back without learning Nix, or you ship software and do not want to maintain it in several registries. It does not fit if you need what nixpkgs or Homebrew's formulae build from source. oku translates Homebrew casks, Scoop, winget and the aqua registry, and refuses a recipe that runs an installer or a script to make its files. It covers the per-user part of what home-manager and nix-darwin do, and nothing that needs root. mise covers dotfiles, macOS defaults and OS packages too, and it has tasks, and env vars from scripts, that oku does not. oku differs from it in six ways. One generation covers the whole machine. A change that fails partway undoes itself. The lock pins every download, where mise's lock is optional. Per-user settings work on Windows and Linux too. oku unpacks installers and never runs them. Source builds run in a sandbox.
Getting started · Demos · How oku works · All guides · Commands · Troubleshooting · Coming from another tool
oku is written in Go and installs its own toolchain with oku sync && oku allow. See CONTRIBUTING.md for the build, the tests and releases. Report bugs through the issues.
One person builds oku in their spare time. If you use it, you can sponsor it.
MIT. See LICENSE.
Install and add your first package:
curl -fsSL https://raw.githubusercontent.com/y3owk1n/oku/main/install.sh | sh && ~/.local/bin/oku add github:sharkdp/fdMade by y3owk1n