Service Management

Run remi as a background hub, or as a persistent service that starts automatically on login. See Hub Mode for the concepts behind these commands.

remi serve

Run the session-less hub in the foreground.

remi serve

The hub binds a port (18765 preferred, falling back across a 20-port range), serves the machine's session list, and spawns child session daemons on request. It never spawns Claude Code itself; sessions come from the app or remi new. This is the command a LaunchAgent/systemd unit runs.

Options

Option	Description	Default
--port PORT	WebSocket port	auto (18765-18784)
--bind HOST	Bind address	0.0.0.0
--auth / --no-auth	Force authentication on/off	auto
--no-relay	Disable signaling relay	off
--no-mdns	Disable mDNS advertising	off

remi start

Start the hub detached, in the background. This is the daily-use equivalent of remi serve.

remi start

Hub started (PID 4213, port 18765).
Sessions: create from the app or `remi new`.
Logs: ~/.remi/daemon.log

The hub self-writes ~/.remi/daemon.pid at boot, which also makes a LaunchAgent-launched hub visible to remi stop/remi status.

Options

Option	Description	Default
--port PORT	Use a specific WebSocket port instead of auto-selecting	auto (18765-18784)
--orphan-timeout SECS	How long a session with no connected client stays alive before cleanup. 0 disables cleanup. Irrelevant when persist_sessions is on (the default).	300 (5 minutes)

remi stop

Stop the running hub.

remi stop

Stops only the hub; any session daemons it or remi new spawned keep serving, and remi stop names them so you know they are still there.

remi stop --all

Also stops every session daemon it can find, via the same live-sessions registry remi ls reads. A session daemon wedged badly enough to ignore its WebSocket is signalled directly (SIGTERM, then SIGKILL if it does not exit), which is the one case remi kill cannot reach on its own.

remi status

Show daemon status: PID, WebSocket port, connected clients, active adapters (relay, mDNS, Telegram if configured), and the running daemon's version. When session daemons are running, they are listed by pid, port, and name, whether or not a hub is currently up.

remi status

Daemon running (PID 4213)
  Mode: hub
  Port: 18765
  Connections: 2
  Status: idle
  Adapters: relay, mdns
  Version: 0.7.3
  Logs: ~/.remi/daemon.log

2 session daemon(s) running:
  PID 4310  port 18766  remi
  PID 4402  port 18767  eventformer

remi logs

Show recent daemon logs.

remi logs

Tails ~/.remi/daemon.log. The hub and every daemon-mode session it spawns share this file (each is launched with REMI_SPAWNED_CHILD=1 and writes to the same log). Wrapper-mode sessions (remi / remi new run directly in a terminal) write to ~/.remi/remi.log instead; tail that directly.

remi config

Show, initialize, or inspect the configuration file (~/.remi/config.toml).

# Show effective configuration
remi config

# Create default config file
remi config init

# Show config file path
remi config path

The config file is optional. When present, it provides default values that CLI flags and environment variables can override. Priority: CLI flags > env vars > config file > built-in defaults.

Config sections

[daemon]
base_port = 18765        # Starting port for auto-selection
port_range = 20          # Number of ports to scan (18765-18784)
bind = "0.0.0.0"         # Bind address
orphan_timeout = 300     # Orphan session timeout in seconds
persist_sessions = true  # Keep a session alive after the last client disconnects

[network]
mdns = true              # mDNS advertising for LAN discovery
relay = true              # Relay/signaling for remote access
signaling_url = "wss://remi-signaling.yooz.workers.dev/connect"

[auth]
enabled = "auto"         # "auto" (based on bind), true, or false

[display]
max_bullet_length = 500  # Bullet truncation (0 = disabled)

[telegram]
enabled = false
bot_token = ""
authorized_chat_ids = []
authorized_user_ids = []

[auto_approve]
enabled = false                                # Opt-in
provider = "yooz"                              # Platform-detected: "yooz" (Apple Silicon) or "llamacpp" (Linux)
model = "YoozLabs/Qwen3.5-4B-qat-lean-4bit-mlx"
api_key = ""                                   # Required for OpenRouter
base_url = "http://127.0.0.1:19924"            # remi's reserved engine port
timeout = 30                                   # Seconds; escalates on timeout
log_decisions = true

allow = ["Read", "Glob", "Grep"]               # Substring/tool-name patterns; skip LLM, approve
deny = []                                      # Checked first; always wins
approve_groups = ["read-only", "vcs-read", "build-test"]  # Built-in fast-path groups
deny_groups = []
instructions = ""                              # Natural-language guidance for LLM

See the Auto-Approve guide for the full config reference, semantics, and pattern rules.

remi reload

Validate config and signal running daemons to re-read configuration.

remi reload

Sends SIGUSR1 to all running daemons. Currently validates the config file; changes take effect on daemon restart.

remi --install

Install remi as an autostart service. The installed service runs remi serve.

remi --install

macOS

Creates a LaunchAgent at ~/Library/LaunchAgents/com.yooz.remi.plist, resolved through your PATH (so it survives a Homebrew upgrade), and loads it immediately. The hub restarts automatically on crash; a clean remi stop is not resurrected.

Installed LaunchAgent: ~/Library/LaunchAgents/com.yooz.remi.plist
Remi will start automatically on login.

Logs go to ~/.remi/remi-stdout.log and ~/.remi/remi-stderr.log.

Linux

Creates a systemd user service at ~/.config/systemd/user/remi.service, reloads the daemon, and enables the service:

Installed systemd user service: ~/.config/systemd/user/remi.service
Remi will start automatically on login.

The service restarts on failure with a 5-second delay.

remi --uninstall

Remove the autostart service.

remi --uninstall

macOS

Unloads and removes the LaunchAgent:

Removed LaunchAgent: ~/Library/LaunchAgents/com.yooz.remi.plist

Linux

Disables the systemd service and removes the unit file:

Removed systemd user service: ~/.config/systemd/user/remi.service

Other Platforms

Windows and other platforms are not currently supported. On unsupported platforms, --install exits with an error:

Autostart not supported on win32. Run remi --daemon manually.

Service Configuration

The preferred way to customize settings is via ~/.remi/config.toml (see remi config init). You can also edit the service file directly for options not in the config:

• macOS: ~/Library/LaunchAgents/com.yooz.remi.plist — add arguments to the ProgramArguments array
• Linux: ~/.config/systemd/user/remi.service — modify the ExecStart line

After editing, reload:

# macOS
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.yooz.remi.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.yooz.remi.plist

# Linux
systemctl --user daemon-reload
systemctl --user restart remi.service