Quick Start

This page walks you from a fresh rensei install to a fully configured local environment in under ten minutes - authenticated, project selected, daemon installed, and GitHub/Linear connected.

If you haven't installed the CLI yet, start at Install first.

Step 1 - Authenticate

Open a browser-based login session with your Rensei account:

rensei auth add --user

Your browser opens the Rensei login page. After completing the WorkOS device flow, the CLI stores your token in the system's native secret backend (Keychain on macOS, an AES-encrypted file on headless Linux) and activates the new context.

Confirm authentication

rensei config show

Expected output:

Context:   mark (user)
Org:       acme-corp
Project:   (none - run 'rensei setup' to select)
URL:       https://app.rensei.ai

Step 2 - Select a project

Run the interactive setup wizard:

rensei setup

The wizard uses Bubble Tea (TUI) when stdin is a terminal. Use the arrow keys to select your org and then your project, then press Enter to confirm.

To skip the TUI or use this in automation:

rensei setup --project api-backend

The selected project is written to ~/.config/rensei/config.json as the default for all subsequent commands.

Step 3 - Install the local daemon

rensei host install

host install mints a short-lived rsp_live_... registration token, writes it to ~/.rensei/daemon.yaml, installs the launchd (macOS) or systemd (Linux) service, and starts the daemon. The daemon listens on 127.0.0.1:7734.

For multi-project orgs, pin the host to a specific project:

rensei host install --project api-backend

Verify the daemon is running:

rensei host status

Step 4 - Connect GitHub

Connect your GitHub account so agents can clone repositories and open pull requests:

Navigate to Settings → Integrations → GitHub in the Rensei web app and complete the GitHub OAuth flow. This grants Rensei permission to act as your GitHub identity.

In the CLI, add the target repository to your project:

rensei project repo add https://github.com/acme-corp/api-backend

Confirm the repo is registered:

rensei project repo list

Step 5 - Connect Linear

Connect Linear to enable the SDLC default template, which triggers agent sessions from Linear issues.

Run the OAuth flow from the CLI:

rensei project trackers connect linear

Your browser opens the Linear OAuth consent screen. After authorizing, Rensei stores the OAuth tokens (including the required app:assignable and app:mentionable scopes) and creates a webhook subscription for your Linear team.

Confirm the tracker is connected:

rensei project trackers list

Expected output:

ID           TYPE      STATUS    TEAM
lnr_abc123   linear    active    Engineering

If you connect Linear using a personal API key rather than OAuth, the key must include the app:assignable and app:mentionable scopes in addition to the standard read/write/issues:create/comments:create set. Missing scopes cause agent activity to silently fail to appear in the Linear UI.

Step 6 - Verify end-to-end

Run the unified health check:

rensei status

A healthy setup reports something like:

Auth          ✓  mark@acme.com (user context)
Daemon        ✓  127.0.0.1:7734 (idle, 2 slots free)
Platform      ✓  host visible to platform (pool: local-acme-corp)
Capacity      ✓  org: 4 hosts, 12 total slots

If any check fails, the output includes suggested next steps.

What's next

Assign a Linear issue to the Rensei agent to fire your first SDLC session. See Default SDLC template.
View running sessions in the Rensei web app or with rensei agent list.
Explore the full command reference for host, fleet, and project management.

Non-interactive / CI setup

For headless environments:

# 1. Add an org-scoped API key
printf '%s' "$RENSEI_TOKEN" | rensei auth add --name ci --kind org_token --token-stdin --secret-store encrypted-file

# 2. Select a project without TUI
rensei --auth ci setup --project api-backend

# 3. Add a repo
rensei --auth ci project repo add https://github.com/acme-corp/api-backend

Set RENSEI_SECRET_PASSPHRASE in your CI environment to unlock the encrypted-file backend automatically on subsequent runs. See Environment variables for the full reference.

On this page