Daemon

rensei host is the command group for everything that belongs to this machine: the daemon process, the local capacity envelope, workarea pool, installed providers, and kits. This page covers daemon lifecycle - install, run, status, logs, health checks, graceful drain, and update - including multi-project and multi-org daemon configuration.

Architecture

The Rensei daemon (rensei host run) is a long-running process that:

1. Registers this machine with the Rensei platform as a worker host using an org-scoped install token.
2. Polls the platform for dispatched agent sessions and spawns them locally.
3. Exposes a local HTTP control API on 127.0.0.1:7734 used by all other rensei host commands.
4. Manages the local workarea pool, credential socket, and capacity envelope.

Install

Register the daemon as a system service so it starts automatically at login and survives reboots. The install command mints an org-scoped worker registration token from the platform API and writes it to ~/.rensei/daemon.yaml.

rensei host install
# With an explicit binary path
rensei host install --bin-path /usr/local/bin/rensei
# For a multi-project org, pin one or more projects
rensei host install --project my-project-slug
rensei host install --project alpha --project beta

rensei host install --user

sudo rensei host install --system

Flags

Repeatable installs

rensei host install is repeatable and idempotent at the OS service level. Re-running it with the same or different --project flags updates the daemon config and re-registers the service. There is no need to uninstall first - the daemon is stopped, the plist/unit file is rewritten, and the service is reloaded atomically.

Multi-project daemon

A single rensei daemon serves multiple projects at once. One daemon process handles session dispatch for all registered projects on the machine.

Adding a project

# Register additional projects - daemon serves alpha AND beta
rensei host install --project alpha --project beta

Pass --project multiple times (or comma-separated: --project alpha,beta). The CLI resolves each slug to its platform UUID, mints a shared registration token, and seeds the daemon's project allowlist with the repository URL for each project.

# After initial install, add one more project without re-installing the service
rensei host install --project gamma

--project defaults to the union of the previously-saved project list (stored in ~/.config/rensei/config.json) plus any new slugs you pass. To replace the list entirely, pass only the new set.

Context defaults vs explicit flags

--org and --project on host install set the default context - the project used when none is specified. Commands that dispatch sessions (and host install itself) accept explicit --org/--project flags that override this default per-invocation. rensei setup, rensei auth activate, and rensei activate set the default without changing anything else.

# Per-command context override - does not change the active project
rensei --org acme --project gamma host status

Viewing registered projects

rensei host status --json | jq .projectsAllowed

The projectsAllowed field counts the projects in the daemon's allowlist.

Multi-org daemon

One daemon process serves sessions for multiple Rensei orgs. Each org is configured as an independent satellite: its own daemon config file and JWT, but sharing the same OS service process.

Adding a satellite org

First, authenticate against the satellite org:

rensei auth add --org partner-co --user   # browser login for partner-co

Then install the satellite org's daemon config (no service re-registration):

rensei host install --org partner-co --project partner-proj

This writes ~/.rensei/daemon-partner-co.yaml and mints a registration token for partner-co. The daemon process picks it up after a restart. Session credentials are isolated per org - credentials from main-org are never visible to partner-co sessions and vice versa.

# Restart the service to activate the new org config
rensei host restart

Removing a satellite org

rensei host uninstall --org partner-co
rensei host restart

This removes ~/.rensei/daemon-partner-co.yaml and ~/.rensei/daemon-partner-co.jwt without touching the primary service registration.

Uninstall

Remove the launchd/systemd service registration. Also wipes ~/.rensei/daemon.jwt.

rensei host uninstall            # macOS, or Linux user scope
rensei host uninstall --user     # Linux user scope
rensei host uninstall --system   # Linux system scope (requires sudo)

Foreground Run

Run the daemon interactively without registering a system service. Useful for debugging or CI environments.

rensei host run
rensei host run --config /path/to/daemon.yaml
rensei host run --port 7734 --skip-wizard

Flags

SIGTERM and SIGINT trigger a graceful drain (60 s timeout).

Status

Check whether the daemon is running and healthy.

rensei host status
rensei host status --json

Sample output:

  Daemon:    ready
  Machine:   wkr_01hq...
  Version:   0.11.2
  PID:       12345
  Uptime:    4h23m
  Sessions:  2 / 8
  Projects:  1 allowed
  Timestamp: 2026-06-02T14:00:00Z

With --json:

{
  "status": "ready",
  "machineId": "wkr_01hq...",
  "version": "0.11.2",
  "pid": 12345,
  "uptimeSeconds": 15780,
  "activeSessions": 2,
  "maxSessions": 8,
  "projectsAllowed": 1,
  "timestamp": "2026-06-02T14:00:00Z"
}

Logs

Stream or tail the daemon log file.

rensei host logs                  # last 50 lines, pretty-printed
rensei host logs --follow         # stream new lines (like tail -f)
rensei host logs -n 200           # last 200 lines
rensei host logs --file /path/to/daemon.log
rensei host logs --raw            # raw NDJSON without pretty-printing

Flags

NDJSON lines with time, level, and msg fields are formatted as 2026-06-02T14:00:00 [INFO] message. Other lines are printed as-is.

For daemon errors routed by launchd to stderr:

tail -f ~/Library/Logs/rensei/daemon-error.log   # macOS
journalctl --user -u dev.rensei.daemon -f         # Linux

Doctor

Run a health-check suite on the installed daemon setup. Exits 0 when healthy, non-zero when the service is not installed or misconfigured.

rensei host doctor
rensei host doctor --json
rensei host doctor --user    # inspect user-scoped systemd unit (Linux)
rensei host doctor --system  # inspect system-scoped unit (Linux)

Sample output:

OS:                darwin
Service path:      ~/Library/LaunchAgents/dev.rensei.daemon.plist
Service installed: true
Service active:    true
Host binary:       /usr/local/bin/rensei
Binary present:    true

Start and Restart

rensei host start and rensei host restart are available on the host surface (added in v0.7.17). They signal launchd/systemd to start or restart the registered service:

rensei host start    # start the registered service (no-op if already running)
rensei host restart  # stop and re-start the service

Pause and Resume

Temporarily stop accepting new sessions without stopping the daemon process. In-flight sessions continue until they complete.

rensei host pause    # stop accepting new sessions
rensei host resume   # re-enable accepting sessions

Drain

Gracefully drain in-flight work before stopping. Sends a stop-accepting signal, waits for all running sessions to complete, then shuts down.

rensei host drain                  # use daemon's configured drain timeout
rensei host drain --timeout 120    # cap drain at 120 seconds

Use drain before planned maintenance to avoid interrupting active agent sessions:

rensei host drain --timeout 300 && rensei host stop

Stop

Stop the daemon process immediately. In-flight sessions are interrupted.

rensei host stop

Update

For Homebrew-managed installs (the standard install path), rensei host update detects Homebrew and prints the correct two-step upgrade flow rather than attempting a self-download:

brew upgrade rensei       # 1. Install the new binary
rensei host install       # 2. Rewrite the plist with the new binary path and reload

Why two steps? The launchd plist stores the resolved Cellar path at install time (e.g. /opt/homebrew/Cellar/rensei/<version>/bin/rensei). After brew upgrade, that path is stale - the old binary is still running. rensei host install rewrites the plist to the new Cellar path and runs bootout+bootstrap+kickstart so the daemon immediately executes the upgraded binary. Running rensei host restart alone would re-exec the old binary from the unchanged plist.

# If you want to skip the brew detection and send the daemon's built-in update signal directly:
rensei host update --force

--force bypasses the Homebrew check and sends the daemon's built-in self-update signal. Not recommended for Homebrew installs.

Setup Wizard

Run the interactive first-run configuration wizard. Persists configuration to ~/.rensei/daemon.yaml. Automatically skipped when stdin is not a TTY.

rensei host setup

Config Files

Daemon HTTP API

The daemon listens on 127.0.0.1:7734 (configurable with --port). All rensei host subcommands use this address. You can also query it directly:

curl http://127.0.0.1:7734/api/daemon/status
curl http://127.0.0.1:7734/api/daemon/stats
curl -X POST http://127.0.0.1:7734/api/daemon/pause
curl -X POST http://127.0.0.1:7734/api/daemon/drain

Override the address for all subcommands with --host and --port flags.

Related Pages

• Host Capacity - Per-host session limits, pool disk quota, eviction
• Credential Socket - How the daemon delivers credentials to agent processes
• Fleet - View other machines in the org, configure project routing
• Org-level Capacity - Pools, providers, cost explorer