Install scripts and the landing page: https://coddy.dev/
Linux / macOS
curl -fsSL https://coddy.dev/install.sh | bashWindows (PowerShell)
irm https://coddy.dev/install.ps1 | iexAndroid (Termux): the same install.sh fetches the Android build; see
Android (Termux).
Creates ~/.coddy/config.yaml from the release config.example.yaml when missing.
On Linux and macOS the script installs more than the binary. The release archive carries the man
page and the bash and zsh completions beside coddy, so they land in the share directory
of the same prefix (~/.local/bin -> ~/.local/share), and a user-level install then writes
one guarded block to the rc file of your login shell:
| What the block does | Why |
|---|---|
adds the install directory to PATH |
a new shell has never heard of ~/.local/bin |
adds the data directory to MANPATH |
so man coddy finds the page |
prepends the completions directory to zsh's fpath and registers _coddy |
zsh searches system directories only |
| sources the bash completion file | bash-completion may not be installed |
coddy update refreshes those files along with the binary, so man coddy and Tab completion
never fall behind the release that is running (see update.md).
The block is rewritten between its markers on every run rather than appended to, so re-running the
installer never duplicates it. Skip it with --no-shell-setup. A system prefix
(--install-dir /usr/local/bin) gets no block at all: those directories are already on
PATH, in the man search path and in zsh's default fpath.
source ~/.zshrc # or open a new terminal
coddy -vThe script installs no systemd unit. On Linux, to keep coddy serve running as a service of
your account, run coddy serve install once the configuration has a provider key: it writes
~/.config/systemd/user/coddy.service for the binary the script installed, enables it and
starts it in ~/Coddy. The script ends by saying so. See
the service guide.
Every release publishes a .deb and an .rpm for x86_64 and arm64 beside the
archives, so Coddy can be installed the way the rest of the system is - and removed the same way.
Prefer this over the install script on a machine you administer: the files are tracked by the
package database, the man page and shell completions are wired up for you, and coddy update
knows not to fight your package manager.
Debian, Ubuntu and derivatives
curl -fsSLO https://github.com/coddy-project/coddy-agent/releases/latest/download/coddy_1.0.10_linux_amd64.deb
sudo apt-get install ./coddy_1.0.10_linux_amd64.debFedora, RHEL, openSUSE and derivatives
curl -fsSLO https://github.com/coddy-project/coddy-agent/releases/latest/download/coddy_1.0.10_linux_amd64.rpm
sudo dnf install ./coddy_1.0.10_linux_amd64.rpmReplace 1.0.10 with the release you want and amd64 with arm64 on 64-bit ARM. The
releases page lists what each tag
published, and SHA256SUMS beside them covers the packages too:
sha256sum -c --ignore-missing SHA256SUMSThe packages suggest tmux and do not install it. Coddy runs without it, and its console runs
well inside it: a session there outlives a closed terminal or a dropped SSH connection. apt
lists it under Suggested packages; add it with sudo apt-get install tmux or
sudo dnf install tmux.
| Path | What |
|---|---|
/usr/bin/coddy |
The full binary (http, ui, scheduler, memory, cli, gateway, swarm, metrics) |
/usr/share/man/man1/coddy.1.gz |
man coddy |
/usr/share/bash-completion/completions/coddy |
bash completion |
/usr/share/zsh/site-functions/_coddy |
zsh completion |
/usr/lib/systemd/user/coddy.service |
systemd user unit for coddy serve, installed and not enabled |
/usr/share/doc/coddy/config.example.yaml |
starting point for ~/.coddy/config.yaml |
/usr/share/doc/coddy/LICENSE, copyright |
licence |
The package enables the unit for nobody, and there is no system service, no system account and
nothing under /etc. Configuration, sessions, skills and credentials stay in the invoking
user's ~/.coddy, so one installed package serves every user on the machine, each with their
own state, and what to run - the console, the HTTP gateway, an editor over ACP, a service - stays
each user's decision. The message printed at installation says the unit is there and not enabled;
coddy serve install, run as the user the service is for, enables and starts it (see
the service guide).
mkdir -p ~/.coddy
cp /usr/share/doc/coddy/config.example.yaml ~/.coddy/config.yaml
# set a provider key in ~/.coddy/config.yaml
coddyOr skip the copy: run coddy and type /login, which signs in to NeuralDeep (or
/login codex, devin, opencode) and writes the provider and its models into
~/.coddy/config.yaml (Console).
Upgrade through the package manager, or let Coddy fetch the release package for you as root - both
end in the same place, and coddy update as an ordinary user will say so rather than silently
replacing a packaged file (see update.md):
sudo apt-get install ./coddy_<newer>_linux_amd64.deb # or dnf install ./...rpm
sudo coddy update -y # downloads and installs the package
coddy serve install # if you run the service: restart it on the new binaryA running service keeps the binary it started with until it restarts, which is what the last line does; the upgrade prints the same reminder.
coddy serve uninstall # first, as each user that enabled the service
sudo apt-get remove coddy # or: sudo dnf remove coddy
rm -rf ~/.coddy ~/Coddy # only if you also want the sessions, config and workspace goneThe package removal cannot reach into each account's ~/.config, so it leaves an enabled
service enabled and prints the commands that clear it
(Removing the service).
There is no apt or dnf repository to subscribe to: the packages are release assets, so a new version
arrives when you install the newer file or run sudo coddy update, not from a background
apt upgrade.
make deb
make rpmSee build.md.
brew install coddy-project/coddy-agent/coddyThe cask lives in Coddy's own tap, coddy-project/homebrew-coddy-agent,
and every release updates it. The command adds the tap, trusts this one cask and installs the
coddy binary from the macOS archive of the latest release, plus man coddy and the bash and zsh
completions. It needs macOS 12 or later. It does not install tmux: its caveats, printed after
the install and by brew info --cask coddy, recommend brew install tmux for a console
session that outlives the terminal. They also give the two lines for ~/.zshrc that make zsh load
the completion: the zsh macOS ships runs no compinit, and without it Tab does not complete
coddy (Homebrew).
Upgrades follow the releases:
brew upgrade --cask coddyHomebrew 7 loads nothing from a third-party tap until it is trusted. Installing by the full name makes
Homebrew trust that cask, which is why the later commands accept the short name coddy. To trust the
whole tap, run brew trust coddy-project/coddy-agent once; brew install --cask coddy then works
by name too. Removal goes through Homebrew:
brew uninstall --cask coddy # brew zap --cask coddy also removes ~/.coddyHomebrew sets the quarantine attribute on every cask download, and the Coddy binary is not
notarised, so the cask removes that attribute from coddy after the install and macOS lets
the first run through. If macOS stops the first run all the same, remove it yourself:
xattr -d com.apple.quarantine "$(which coddy)".
The command this page used to give, brew install --cask https://github.com/coddy-project/coddy-agent/releases/latest/download/coddy.rb,
no longer works: current Homebrew refuses a cask given by its URL or by a file path and answers
No Cask with this name exists. Troubleshooting
moves a Coddy installed that way to the tap.
On a Mac that has never added the tap, brew install coddy needs Coddy in one of Homebrew's
own repositories, and that is still open. Homebrew routes open-source command-line software to
homebrew/core as a formula built from source, so the tap is our own distribution channel rather
than a submission - the whole path, including what currently blocks it, is in homebrew.md.
coddy update recognises a Homebrew install and points back at brew upgrade rather than
replacing a file Homebrew tracks: brew upgrade --cask coddy for this cask, and
brew upgrade coddy for a formula. Homebrew refuses to run under sudo, so there is no
privileged shortcut there.
pkg install curl
curl -fsSL https://coddy.dev/install.sh | bashIn Termux the script fetches the build for Android, coddy_X.Y.Z_android_arm64.tar.gz on a
64-bit ARM device and coddy_X.Y.Z_android_amd64.tar.gz on x86_64. The Linux archive does not
start there: a Termux that targets Android 10 or later runs every
program through Android's linker, which turns a static executable away with
has unexpected e_type: 2. The rest of the install is the Linux one: ~/.local/bin, the
man page and the completions in ~/.local/share, and the block in ~/.bashrc. What differs
on the device (the programs Coddy starts, certificates, running coddy serve in the background)
is on its own page: Android (Termux).
export PATH="$HOME/.local/bin:$PATH"
coddy -v
# edit ~/.coddy/config.yaml, or run coddy and type /login
coddy serve # in this terminal
coddy serve --daemon # in the background, restarted if it dies
coddy serve install # Linux: as a systemd user serviceOn Linux with systemd, coddy serve install runs it as a user service of your account instead:
it enables the unit a package installed, or writes one for a binary the install script put in
place, and starts it working in ~/Coddy. coddy serve uninstall takes it away again. See
the service guide for the log, keeping it
running after logout and removing it. coddy serve --daemon is the route where there is no
systemd.
| What | Path |
|---|---|
| Binary | %LOCALAPPDATA%\Programs\coddy\coddy.exe |
| Config | %USERPROFILE%\.coddy\config.yaml |
| Sessions / memory | %USERPROFILE%\.coddy\sessions\ |
The user directory is $env:USERPROFILE (%USERPROFILE%), not $HOME — $HOME is unreliable across Windows PowerShell and Git Bash setups (Git Bash $HOME may differ from %USERPROFILE%).
install.ps1 adds the binary directory to the user PATH. New terminals pick it up automatically; the terminal you installed from does not. Either open a new terminal, or refresh in place:
$env:Path = [Environment]::GetEnvironmentVariable("Path","User") + ";" + [Environment]::GetEnvironmentVariable("Path","Machine")(refreshenv also works if you have Chocolatey.)
Some harnesses spawn coddy acp via cmd /c or sh -c and do not inherit the user PATH. To avoid "command not found" wiring bugs, configure clients with the absolute path:
%LOCALAPPDATA%\Programs\coddy\coddy.exe
Scoop / winget manifests are not published yet — tracked in issue #42. Until then use install.ps1 above and upgrade with coddy update -y.
docker compose pull && docker compose up -dSee Docker.
coddy update -ySee update.md.
See build.md and the README section Other installation methods.