Lilac Flow is the default. Choose from 50 icon styles in Settings → Appearance; light/dark mode and semantic status colors stay consistent.
Cowboy keeps long-running coding agents close to the work. Self-host one Hub,
enroll Linux and macOS Machines, and direct Codex, Claude Code, Gemini, Grok,
DeepSeek, or your own Plugin from a keyboard-first desktop or touch-first mobile
workspace. Reconnect later without moving the worktree, credentials, or agent
process away from the Machine where it started.
[!IMPORTANT]
Cowboy is active, pre-1.0, and source-first. There is no stable binary release
yet; build from source and expect interfaces to evolve.
Why Cowboy
- One Hub, many Machines. Place sessions on any enrolled host and switch
between them without changing IDEs or juggling SSH tabs.
- Workers outlive clients. Closing a browser or restarting a Controller does
not stop the detached, Machine-owned ACP worker.
- Agent work stays legible. Plans, tool calls, permissions, code, diffs,
queues, and runtime state remain visible instead of collapsing into chat.
- Each surface fits its input model. Desktop is dense and keyboard/Vim-first;
Mobile is touch-first and progressively disclosed.
- Plugins are releases, not scripts. Signed, immutable, Machine-scoped
generations stage, probe, activate, drain, and roll back explicitly.
- The control plane is yours. Run the Hub, database, Machines, credentials,
and release policy on infrastructure you control—there is no shared Cowboy
cloud.
Quick start
The official icon is Neon (103). Settings → Appearance → Icon & theme offers
20 curated styles, each with matching light and dark interface colors. See app icons and platform behavior
for Home Screen installation and native switching.
Prerequisites
- Nix with flakes enabled
- Linux or macOS
- Git
Clone Cowboy, enter its pinned environment, install checkout-local frontend
dependencies, and build a release:
git clone https://github.com/dravengarden/cowboy.git
cd cowboy
nix develop
just install
just build
Start a local Hub with SQLite persistence:
COWBOY_PUBLIC_ORIGIN=https://cowboy.example ./target/release/cowboy-controller serve \
--database-url sqlite:///tmp/cowboy.sqlite3
Put a same-host TLS reverse proxy in front of 127.0.0.1:3333, then open your
configured HTTPS origin. Product login and device proofs are mandatory.
See transport security for proxy setup and
device enrollment. SQLite is the zero-operations store; PostgreSQL implements
the same Store API for larger deployments.
The Controller requires a database for durable device bindings. Use
cowboy store-copy --source postgresql://… --destination sqlite:///… for a
fail-closed production migration into a new SQLite file.
To add another Linux or macOS host, build the target-platform bootstrap with
just build-machine-bootstrap. Create a one-time enrollment code in
Cowboy, then run the generated command on that Machine:
cowboy register https://cowboy.example --background
The token is entered through a masked prompt and never needs to appear in shell
history. See Machine operations for installation,
identity verification, background services, and multi-Service isolation.
Architecture
| Boundary | Owns | Does not own |
|---|
| Desktop / Mobile | Input, navigation, rendering, and reconnect | Worker lifetime or authoritative session state |
| Self-hosted Hub | Sequence, persistence, routing, permissions, snapshots, and fan-out | Worktrees, Provider processes, or Machine secrets |
| Enrolled Machine | Identity, worktrees, detached ACP workers, and installed generations | Global ordering or cross-client presentation |
| Plugin generation | Exact Provider runtime, typed UI, components, and capability contract | Ambient browser or host capabilities |
Remote Machines initiate authenticated outbound WebSocket connections, so a
development host needs no public inbound listener. A local Machine can use UDS.
Every session records its Machine and exact Provider generation; fencing,
snapshots, replay, and idempotent commands make reconnect and rolling updates
explicit rather than silently moving or replacing active work.
Read the architecture overview for the
component map and end-to-end request flow.
Local and remote execution
Choose a Project, grouped by Machine and directory, then an installed AI
such as Codex · Machine 01 or Claude Code · Machine 01. Cowboy determines
Local or Remote from the AI runtime and project locations.
Codex and Claude Code each use one Provider Plugin for both modes. In Local
mode, the AI runtime and project share a Machine. In Remote mode, the Agent
runtime, model connection, authentication, and private conversation state stay
on the runtime Machine; files, shell commands, and task processes run on the
project Machine. For example, an AI on Machine 01 can work on a repository on
Machine 02 without installing another AI Provider on Machine 02.
Cowboy owns the target binding, transport, reconnect, cancellation, and target
worktree. Each Provider Plugin adapts its native tools to that environment.
Code, Review, Git, and uploads follow the same bound target. If the target is
unavailable, the session never silently switches execution to the runtime
Machine. Other Providers require explicit remote-execution support.
See Native execution environments for the
ownership, compatibility, and recovery contracts.
Product surfaces
Desktop — keyboard first
Dense session navigation, split workspaces, visible tool output, and
keyboard/Vim control for sustained engineering work.
Mobile — touch first
Touch-first session control, Agent follow-up, and code review reconnect to the
same durable worker.
Both clients observe the same server-authoritative model without forcing a
desktop IDE into a stretched mobile layout—or a mobile workflow into desktop
chrome.
Plugin ecosystem
A Plugin is Cowboy's only discoverable, installable, upgradable, rollback,
and uninstall unit. Publishing makes an immutable release available; it never
silently installs or activates that release on a Machine.
source → signed .cowboy-plugin → Catalog → stage + probe → atomic activation → pinned sessions
| Kind | First-party Plugins |
|---|
| Agent Provider | Codex, Claude Code, Gemini, Grok, Codex + DeepSeek, Claude + DeepSeek |
| Code intelligence | Zed |
The extension boundary is deliberately narrow:
- package identity binds the manifest, payload, contract fingerprint, runtime
artifacts, and publisher signature;
- each Machine stages and probes a complete generation before activation;
- failure leaves the previous generation active, while old and new generations
can drain side by side;
- sessions stay pinned to their exact Provider and authentication generations;
- Provider UI is typed, data-only IR rendered by Cowboy—Plugins cannot inject
arbitrary JavaScript, HTML, CSS, or DOM access.
Start with Installable Plugin packages, then read
Plugins and shared components and the normative
core requirements.
Safety and ownership
| Invariant | Cowboy's contract |
|---|
| Self-hosted state | The Hub and SQLite/PostgreSQL data stay on infrastructure you control. |
| Outbound Machine transport | Remote Machines dial the Hub; development hosts do not expose a public listener. |
| Machine-bound identity | The Ed25519 private key remains mode 0600 on its Machine. |
| Bounded enrollment | Codes are single-use, expire after 15 minutes, and are stored only by digest. |
| Scoped credentials | Service credentials reach only compatible, installed Machine generations. |
| Fail-closed activation | Signature, digest, schema, package, and platform mismatches cannot replace active bytes. |
| Data-only Plugin UI | Plugin surfaces have no ambient DOM, filesystem, process, network, clock, or randomness access. |
The detailed contracts live in core requirements and
operations.
Development
Run project commands inside the pinned Nix shell:
nix develop
just install
just check
just check covers formatting, Clippy, dependency policy, Rust
tests, Web typechecking/lint/tests, Plugin conformance, site tests, and release
builds. For local HMR, run just dev and
just dev-web in separate terminals.
just test-postgres runs the ignored PostgreSQL contracts and is included in
just check. It uses the pinned Nix PostgreSQL executable, not an existing
database service, and gives each test a fresh database in a private temporary
cluster with only a Unix socket. Inherited PostgreSQL connection settings and
test URLs are ignored. The fixture is removed on success or failure after the
server stops; failed shutdown retains it and fails the gate. Run it as a
non-root user. Plain cargo test still skips this separate group.
| Path | Responsibility |
|---|
| src/ | Rust Hub, API, persistence, Machine routing, workers, and CLI |
| web/ | React Desktop, Mobile, Agent, Code, setup, and admin surfaces |
| plugins/ | First-party Agent Provider and code-intelligence Plugins |
| components/ | Versioned Plugin, Provider, state, UI, and code-intelligence contracts |
| apps/macos-installer/ | Native macOS menu-bar installer and Machine manager |
| site/ | Public product website and privacy-safe artwork |
| docs/ | Architecture, product contracts, deployment, and operations |
Keep deployed SQL baselines immutable; add a migration instead of editing one
that has shipped. Significant Provider or architecture changes must preserve
the contracts in docs/requirements.md.
Documentation
| Start here | Covers |
|---|
| Documentation index | Complete architecture and product documentation |
| Architecture overview | Hub, Machines, workers, storage, and clients |
| Machine operations | Enrollment, identity, services, and Provider installation |
| Plugin packages | Package, typed UI, runtime, authentication, and release contract |
| Code review | Worktree, Git, file, diff, and language-intelligence data plane |
| Build and deploy | Pinned builds and component-scoped releases |
Project status
Cowboy is built in public and remains pre-stable. The architecture and test
suite are substantial, but packaging, compatibility guarantees, and upgrade
policy are still converging toward 1.0. Use it from source today; pin the commit
you deploy and read the repository history before upgrading.
Contributing
Issues and pull requests are welcome. Read CONTRIBUTING.md
for environment setup, project contracts, verification expectations, and the
information to include with a change.
- Use GitHub Issues for
reproducible bugs and focused feature proposals.
- Run just check before requesting review.
- Include screenshots for visual changes and regression coverage for behavior
changes.
License
Cowboy is available under the MIT License.
