Service Management

Run Remi as a background daemon or a persistent service that starts automatically on login.

remi start

Start the Remi daemon in the background.

remi start

The daemon auto-selects a free port from the range 18765-18784 (20 ports), so it works even when wrapper sessions are already running on the default port. Use --port to override with a specific port.

The daemon creates one session on startup and logs to ~/.remi/daemon.log. Each daemon manages exactly one session (one session per port).

Options

Option	Description	Default
--port PORT	Use a specific WebSocket port instead of auto-selecting	auto (18765-18784)
--orphan-timeout SECS	How long orphaned sessions (no connected client) stay alive before cleanup. Set to 0 to disable.	300 (5 minutes)

remi stop

Stop the background daemon.

remi stop

remi status

Show daemon runtime state: PID, WebSocket port, hook server port, connected clients, and active adapters (relay, mDNS, Telegram if configured).

remi status

remi logs

Show recent daemon logs.

remi logs

Tails ~/.remi/daemon.log when running in daemon mode (remi start / --daemon / installed service). Wrapper-mode sessions (remi / remi new) write to ~/.remi/remi.log instead — tail that directly.

remi config

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

# Show effective configuration (merged from file + env + defaults)
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

[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 = "ollama"                            # "ollama" | "openrouter" | custom URL
model = "gemma4:e2b"                           # 4B+ parameter model recommended
api_key = ""                                   # Required for OpenRouter
base_url = "http://localhost:11434/v1"
timeout = 10                                   # Seconds; escalates on timeout
log_decisions = true

allow = ["git status", "gh issue", "gh pr"]    # Substring patterns; skip LLM, approve
deny = ["rm -rf /", "sudo ", "curl | sh"]      # Checked first; always wins
instructions = ""                              # Natural-language guidance for LLM

See the Auto-Approve guide for semantics, pattern rules, and supported providers.

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.

remi --install

macOS

Creates a LaunchAgent at ~/Library/LaunchAgents/com.yooz.remi.plist and loads it immediately. Remi runs in daemon mode and restarts automatically if it exits.

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 installed service runs remi --daemon. 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