Install

macOS and Linux on x64 and arm64. Node 18+ runs the npm command; the background proxy is a standalone binary.

npm install -g ai-garcon@latest
garcon setup

Setup installs a service for your user, verifies the running version, and prints the dashboard link. Open Settings → Connect a harness, choose your tool and account label, and copy its configuration. Restart the tool and send one short request. The new row in Logs completes setup. Supabase is optional.

Setup is safe to rerun and preserves usage and sync settings. Run it as your normal user, without sudo.

Try it first or run without a service

npx ai-garcon@latest   # foreground; Ctrl-C to stop

For an installed command, run garcon in one terminal and garcon setup --no-service in another. This also works in containers or Linux sessions without systemd. For a custom port, start garcon -listen 127.0.0.1:4242, then use garcon setup --no-service --url http://127.0.0.1:4242.

Update

garcon update

Updates the owning global npm installation, refreshes an installed service and waits for the new version. If no service is installed, the command explains how to start one or restart your foreground process. Usage, settings and device identity stay in place. Finish active agent requests first: restarting briefly interrupts the proxy.

For older versions without the update command:

npm install -g ai-garcon@latest
garcon service restart
garcon doctor --wait 10s

For npx setup, use npx ai-garcon@latest setup again. For a project-local dependency, run npm install ai-garcon@latest, then npx garcon setup. Source checkouts use scripts/install.sh --update.

The service runs ~/.local/share/garcon/bin/garcon, a private copy refreshed by setup and service restart. Clearing an npm cache or changing Node versions cannot delete it. After switching Node versions, reinstall the npm command and run setup.

Another machine

Repeat installation and setup. Configure the harness on that machine too. To combine dashboards, open Settings → Sync, choose a different device name, and paste your existing project's URL and key. Do not copy sync.json or the data directory between machines. See joining an existing project.

Troubleshooting

garcon doctor
garcon service status

Doctor checks the local server, installed/running versions, first-request progress and sync errors. It makes no direct Supabase calls. If the port belongs to another app, stop that app or use a custom foreground port. If Garcon is already running in a terminal, use setup --no-service or stop it before installing a service.

Command not found: put $(npm prefix -g)/bin on PATH and restart the shell. Use type -a garcon to find duplicate installs. For EACCES, use a Node version manager or a user-owned npm prefix: npm's permissions guide.

Linux logs: journalctl --user -u garcon. macOS logs: ~/Library/Logs/garcon.log.

Uninstall

Restore your harnesses' original base URLs/providers first. Then stop the service before removing npm's command. Usage and settings remain for a later reinstall.

garcon service uninstall
npm uninstall -g ai-garcon

From source

Needs Go 1.27+ and Node 22+ (mise install provides both).

git clone https://github.com/asieke/garcon && cd garcon
scripts/install.sh --service
scripts/install.sh --update   # later: pull and rebuild

scripts/install.sh --uninstall removes the service, source-installed binary and settings file, keeping usage history. Foreground flags: garcon [-listen ADDR] [-data FILE] [-config FILE].