Updated8 hours ago

LanguageGo

Setup difficultyModerate

MobileResponsive

Stars: 186
Port: 12345 (Web UI and OpenAI-compatible HTTP API)

Docker

ghcr.io/coddy-project/coddy-agent

Install with Docker

Coddy web UI start screen on desktop (1920x1080)

Coddy web UI start screen on mobile (390x844)

Coddy console TUI showing a turn with a tool call

What is Coddy Agent?

Coddy Agent is a self-hosted, open-source AI agent harness distributed as a single static Go binary. It executes a reasoning engine with filesystem and shell tools, and adds support for Model Context Protocol servers, project rules, skills, subagents, hooks, background tasks, long-term memory, and context compaction. The same agent core is accessible through multiple interfaces: a terminal console (TUI), an embedded web UI with an OpenAI-compatible HTTP API, the Agent Client Protocol (ACP) for editors like Zed and VS Code, a Telegram gateway, a Pachca gateway, a cron scheduler, and a swarm relay for multi-node fleets. All interfaces share sessions stored under ~/.coddy. It runs in distroless/scratch containers with a read-only root filesystem, needs no external database or Redis, and works with any OpenAI-compatible provider (OpenAI, Anthropic, Ollama, llama.cpp, vLLM, NeuralDeep) plus ChatGPT via Codex and Devin accounts. Configuration uses YAML with JSON Schema validation and hot-reload. The project is MIT-licensed and actively maintained with regular releases.

Should you self-host Coddy Agent?

Coddy Agent scores 50/100 on selfhost.directory (how scoring works) and ranks #40 of 120 in AI Assistant. It has 186 GitHub stars.

It shipped 10 stable releases in the past year. The latest, 1.3.60, came out on 27 October 2026.

Setup is moderate: expect some configuration beyond a single command. An official Docker image is available. It is MIT-licensed and written mostly in Go.

Its closest alternative on selfhost.directory is bbarit-oss (45/100, 149 stars). Coddy Agent scores higher overall. See Coddy Agent vs bbarit-oss side by side.

Features

Agent Client Protocol (ACP) Server
Background tasks
Context Compaction
Cron Scheduler
Embedded Web UI
Hooks
OpenAI-compatible HTTP API
Pachca Gateway
Prometheus metrics exporter
ReAct Loop with Tools
Remote Mode
Subagents
Swarm Relay
Telegram gateway
Terminal Console (TUI)

How to install Coddy Agent

Install Coddy Agent with Docker

Environment variables

OPENAI_API_KEY, CODDY_CONFIG, CODDY_HOME, CODDY_CWD

docker run -d --name coddy
-p 12345:12345
-e OPENAI_API_KEY
-e CODDY_CONFIG=/home/user/.coddy/config.yaml
-v "$PWD/workspace:/workspace"
-v "$PWD/coddy_home:/home/user/.coddy"
ghcr.io/coddy-project/coddy-agent:latest

Multi-arch (amd64, arm64) image from GitHub Container Registry; no login needed to pull.

Install Coddy Agent with Docker Compose

Environment variables

OPENAI_API_KEY, ANTHROPIC_API_KEY, DEEPSEEK_API_KEY, TELEGRAM_BOT_TOKEN, CODDY_HOME, CODDY_CWD, CODDY_CONFIG, CODDY_UID, CODDY_GID, CODDY_HTTP_PORT, CODDY_COMMAND

services: coddy: image: ghcr.io/coddy-project/coddy-agent:latest command: serve -H 0.0.0.0 -P 12345 ports: - "12345:12345" working_dir: /workspace environment: CODDY_HOME: /home/user/.coddy CODDY_CWD: /workspace CODDY_CONFIG: /home/user/.coddy/config.yaml OPENAI_API_KEY: ${OPENAI_API_KEY-} volumes: - ./workspace:/workspace - ./coddy_home:/home/user/.coddy healthcheck: test: ["CMD", "/bin/coddy", "--version"] interval: 5s timeout: 3s retries: 20

Recommended way to run published GHCR image; single service, no database/Redis sidecar.

Install Coddy Agent with Linux

Fedora, RHEL, openSUSE, or derivatives

curl -fsSLO https://github.com/coddy-project/coddy-agent/releases/latest/download/coddy_X.Y.Z_linux_amd64.rpm sudo dnf install ./coddy_X.Y.Z_linux_amd64.rpm

Packages published with every release for x86_64 and arm64; tracked by package database; coddy update defers to package manager.

Install Coddy Agent with Windows

Linux, macOS, or Windows

Environment variables

OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.

curl -fsSL https://coddy.dev/install.sh | bash

Windows PowerShell

irm https://coddy.dev/install.ps1 | iex

Install script downloads latest release binary, puts it on PATH, creates ~/.coddy/config.yaml from example, installs man page and shell completions on Linux/macOS.

Install Coddy Agent with Android

Android with Termux

curl -fsSL https://coddy.dev/install.sh | bash

Same install script fetches Android build; runs in Termux; can join swarm relay from laptop with one swarm.join entry and no open port on phone.

Install Coddy Agent with Debian

Debian, Ubuntu, or derivatives

curl -fsSLO https://github.com/coddy-project/coddy-agent/releases/latest/download/coddy_X.Y.Z_linux_amd64.deb sudo apt-get install ./coddy_X.Y.Z_linux_amd64.deb

Packages published with every release for x86_64 and arm64; tracked by package database; coddy update defers to package manager.

Install Coddy Agent with Homebrew

macOS with Homebrew

brew install coddy-project/coddy-agent/coddy

Cask lives in Coddy's own tap; every release updates it; adds man page and shell completions; clears quarantine flag; coddy update hands over to brew upgrade --cask coddy.

Install Coddy Agent with Build from Source

git clone https://github.com/coddy-project/coddy-agent make build TAGS="http ui scheduler memory cli gateway swarm metrics"

Build tags control which surfaces are included; see docs/contributing/build.md for details.

FAQ

How do I run Coddy on more than one machine?

Run coddy serve on each machine and enable the swarm relay on one of them to list every node's sessions in one place, route across rings, and pull in machines that can only dial out. The console and coddy acp can also drive a single remote server with --remote.

Which editors and clients can host Coddy?

coddy acp speaks the Agent Client Protocol over stdio, so Zed, Obsidian, VS Code, or your own script get sessions, modes, permissions, streaming updates, and skills as slash commands.

Can Coddy run on-premises with local models?

Yes. Point a model entry at a local OpenAI-compatible server such as Ollama, llama.cpp, or vLLM and no prompt leaves your network. The binary is static and runs in distroless or from-scratch containers with a read-only root filesystem.

Which LLM providers and models does Coddy work with?

Any OpenAI-compatible API plus Anthropic: OpenAI, Anthropic, Ollama, llama.cpp, vLLM, NeuralDeep, or your own gateway with your own keys and endpoints. ChatGPT sign-in works through the Codex backend, and a Devin account signs in through the browser.

What is Coddy Agent?

Coddy Agent is an open-source, general-purpose AI agent that ships as one static Go binary under the MIT license. It runs a ReAct loop with filesystem and shell tools, MCP servers, project rules, skills, subagents, hooks, background tasks, a cron scheduler, and long-term memory, available from a terminal, browser, editor over ACP, or Telegram.