Environment and Defaults
Reference for all environment variables, file paths, and default configuration values.
Environment Variables
| Variable | Description | Default |
|---|---|---|
REMI_PORT | WebSocket server port | 18765 |
REMI_MAX_BULLET_LENGTH | Max characters per message bullet before truncation (0 to disable) | 500 |
REMI_PASSPHRASE | Passphrase to unlock the identity file (skips interactive prompt) | (none) |
REMI_PUSH_SECRET | APNS push auth secret (signing token for phone notifications) | (none) |
REMI_HOOK_DEBUG | Set to 1 to dump every raw hook POST to ~/.remi/hook-diag.jsonl. Diagnostic only. | (none) |
REMI_AUTO_APPROVE | true or false — toggle LLM auto-approve | config file |
REMI_AUTO_APPROVE_MODEL | LLM model name (e.g. gemma4:e2b, qwen3.5:4b) | gemma4:e2b |
REMI_AUTO_APPROVE_PROVIDER | ollama, openrouter, or a custom base URL | ollama |
REMI_AUTO_APPROVE_BASE_URL | Explicit OpenAI-compatible endpoint URL | http://localhost:11434/v1 |
REMI_AUTO_APPROVE_API_KEY | API key (required for OpenRouter and most hosted providers) | (none) |
REMI_AUTO_APPROVE_ALLOW | Comma- or newline-separated allow patterns (overrides config) | (none) |
REMI_AUTO_APPROVE_DENY | Comma- or newline-separated deny patterns (overrides config) | (none) |
REMI_AUTO_APPROVE_INSTRUCTIONS | Natural-language guidance appended to LLM system prompt | (none) |
TELEGRAM_BOT_TOKEN | Telegram bot token (enables Telegram adapter) | (none) |
TELEGRAM_ENABLED | Set to false to disable Telegram even if token is set | enabled when TELEGRAM_BOT_TOKEN is set |
TELEGRAM_AUTHORIZED_CHAT_IDS | Comma-separated list of authorized Telegram chat IDs | (none) |
TELEGRAM_AUTHORIZED_USER_IDS | Comma-separated list of authorized Telegram user IDs | (none) |
Remi also reads a .env file from the current working directory if present.
Configuration File
Remi supports an optional TOML configuration file at ~/.remi/config.toml. Settings in the config file provide defaults; CLI flags and environment variables always take precedence.
Priority order: CLI flags > environment variables > config file > built-in defaults
remi config # Show effective configuration
remi config init # Create default config file
remi config path # Show config file path
remi reload # Validate config (changes take effect on restart)
See remi config for details.
File Paths
All Remi data is stored under ~/.remi/:
| Path | Description |
|---|---|
~/.remi/ | Remi data directory |
~/.remi/config.toml | Configuration file (optional, created with remi config init) |
~/.remi/identity.json | Ed25519 identity (private key plaintext or encrypted, plus public key) |
~/.remi/authorized_keys.json | List of authorized client public keys |
~/.remi/connection-code | Persistent connection code (when using --permanent-code) |
~/.remi/sessions.json | Stored session history |
~/.remi/remi.log | Daemon log file (wrapper mode — remi / remi new) |
~/.remi/daemon.log | Daemon log file (daemon mode — remi start / --daemon / --install) |
~/.remi/hook-diag.jsonl | Raw hook POST dump (when REMI_HOOK_DEBUG=1 is set). Diagnostic only. |
~/.remi/live-sessions/ | Per-session metadata used for cross-daemon discovery (one JSON file per live session) |
~/.remi/daemon.pid | PID of the detached daemon (when running in daemon mode) |
~/.remi/status-<port>.json | Per-port daemon status (for status line integration; e.g., status-18765.json) |
~/.remi/daemon-status.json | Daemon-mode status file (when running with --daemon) |
~/.remi/statusline.sh | Status line script auto-installed for Claude Code |
~/.remi/remi-stdout.log | Service stdout log (when installed with --install) |
~/.remi/remi-stderr.log | Service stderr log (when installed with --install) |
Hook Configuration
Remi writes hook entries into the project's Claude Code settings:
| Path | Description |
|---|---|
<project>/.claude/settings.local.json | Hook configuration (auto-managed by Remi, cleaned up on exit) |
The hook entries configure Claude Code to POST events to Remi's local HTTP server. This file is project-scoped and gitignored by Claude Code.
Service Files
| Platform | Path |
|---|---|
| macOS | ~/Library/LaunchAgents/com.yooz.remi.plist |
| Linux | ~/.config/systemd/user/remi.service |
Default Values
| Setting | Default | Override |
|---|---|---|
| WebSocket port | 18765 | --port or REMI_PORT |
| Port range | 18765-18784 (20 ports) | config: daemon.port_range |
| Hook server port | OS-assigned (port 0) | (auto-selected) |
| WebSocket host | 0.0.0.0 | --bind or config: daemon.bind |
| WebSocket path | /ws | (fixed) |
| Hook server path | /hooks | (fixed) |
| Connection timeout | 10 seconds | (not configurable) |
| Ping interval | 30 seconds | (not configurable) |
| Max bullet length | 500 characters | --max-bullet-length, REMI_MAX_BULLET_LENGTH, or config: display.max_bullet_length |
| Max concurrent connections | 100 | (not configurable) |
| Orphan session timeout | 5 minutes | --orphan-timeout or config: daemon.orphan_timeout |
| Max replay history | 1000 messages | (not configurable) |
| Signaling server | wss://remi-signaling.yooz.workers.dev/connect | --signaling-url or config: network.signaling_url |
Status Line
Remi auto-installs a status line script at ~/.remi/statusline.sh and configures Claude Code to use it (via ~/.claude/settings.json). The status line shows:
remi :18765 my-project:main | 2 client(s) | working | [Opus 4.6] 45% context
The status line requires jq to be installed on the system.