Daemon

Ratel Local runs one daemon per user. Agent plugins start a lightweight connect bridge; the daemon owns upstream connections, project-scoped gateways, the browser UI, and control-plane writes.

Sessions in the same canonical project can reuse upstream connections. User, project, and local configurations stay isolated, and an existing session keeps its acquired gateway generation while a newly connected session receives the latest revision.

Recommended setup

ratel-local setup

Setup installs a macOS launchd or Linux user-systemd service, starts it, replaces an incompatible version, and offers agent onboarding. Re-running setup is safe.

Use daemon-only mode when agent configuration is managed elsewhere:

ratel-local setup --daemon-only --yes

The default port is 5731. Choose another port only on first installation:

ratel-local setup --daemon-only --yes --port 7331

Lifecycle commands

ratel-local daemon status
ratel-local daemon start
ratel-local daemon stop
ratel-local daemon restart
ratel-local daemon open

status probes the configured loopback endpoint. A running response includes its pid, upstream count, active MCP-client count, and MCP endpoint.

open creates a fresh authenticated browser session. The daemon listens on loopback; do not share the bearer-bearing session URL.

Lower-level service commands are available for repair:

ratel-local daemon install
ratel-local daemon uninstall

uninstall stops and removes the login service. It does not delete Ratel configuration, OAuth state, backups, or saved Cloud settings.

Foreground mode

Run the daemon in the current terminal when a login service is unavailable:

ratel-local daemon run --no-open --auto-config

Stop it with Control-C. --port 0 is valid only for a foreground run; an installed service needs a stable port.

Projects and reconnects

The connector resolves a project from --project-root, RATEL_PROJECT_ROOT, CLAUDE_PROJECT_DIR, then its working directory. Inspect registered roots with:

ratel-local project list
ratel-local project add /path/to/project
ratel-local project remove /path/to/project

project remove forgets the registry entry without deleting project files.

Reconnect the affected agent after MCP, skill, retrieval, or OAuth changes. New sessions acquire the new immutable gateway generation; existing sessions drain on the old one.

Upgrade or reconfigure

Upgrade the global CLI, then run setup once:

npm install --global @ratel-ai/ratel-local
ratel-local setup
ratel-local daemon status

Setup replaces an older daemon and reconciles the selected Claude Code or Codex plugin. Configuration remains in place.

To change the installed port, recreate the service explicitly:

ratel-local daemon uninstall
ratel-local daemon install --port 7331

Re-run ratel-local setup --agent <agent> when you need to repair or add an agent link.

Remove Ratel Local

1. Remove or disable the Ratel Local plugin or explicit MCP entry in each host.
2. Run ratel-local statusline uninstall if you installed the Claude Code statusline.
3. Remove scoped skills you no longer want Ratel to manage.
4. Run ratel-local daemon uninstall.
5. Run npm uninstall --global @ratel-ai/ratel-local.

Your ~/.ratel and project .ratel data remain for recovery. Back them up and remove them separately only when you no longer need configuration, OAuth state, or snapshots.

Next steps