> ## Documentation Index
> Fetch the complete documentation index at: https://evoke-f0bfabff.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Environment variables, project overrides, and registry configuration.

## Environment variables

| Variable                   | Default             | Description                                                      |
| -------------------------- | ------------------- | ---------------------------------------------------------------- |
| `RSTACK_HOME`              | —                   | Path to RStack asset root. Required for asset-only adapters.     |
| `RSTACK_RUN_DIR`           | `.rstack/runs`      | Override the run state directory                                 |
| `RSTACK_ALLOW_DESTRUCTIVE` | `0`                 | Set to `1` to bypass destructive action gates                    |
| `RSTACK_LOG_LEVEL`         | `info`              | Log verbosity: `debug`, `info`, `warn`, `error`                  |
| `RSTACK_MODEL_OPUS`        | `claude-opus-4-5`   | Model to use for Opus-tier agents (architecture, code, security) |
| `RSTACK_MODEL_SONNET`      | `claude-sonnet-4-5` | Model to use for Sonnet-tier agents                              |
| `RSTACK_DEFAULT_MODEL`     | —                   | Model for delegated builder agents                               |
| `RSTACK_ESCALATED_MODEL`   | —                   | Model used when a task reaches attempt ≥ 2                       |

### Business Flex profile files

These are project files, not environment variables:

| File                         | Description                                                                                     |
| ---------------------------- | ----------------------------------------------------------------------------------------------- |
| `.rstack/rstack.config.json` | Active profile, workflow, enabled domains, enabled agents/plugins, dashboard pages              |
| `.rstack/budget.json`        | Currency, run/daily/monthly budget, warning/block thresholds, approval threshold, stage budgets |

Create them with:

```bash theme={null}
npx rstack-agents init --profile business-flex
```

See [Business Flex Profiles](/getting-started/business-flex-profiles) for profile examples.

### Identity & people

| Variable            | Default          | Description                                |
| ------------------- | ---------------- | ------------------------------------------ |
| `RSTACK_USER`       | git `user.name`  | Who started the run / resolved an approval |
| `RSTACK_USER_EMAIL` | git `user.email` | Email recorded alongside the identity      |

### Business Hub

| Variable                 | Default | Description                                 |
| ------------------------ | ------- | ------------------------------------------- |
| `RSTACK_BUSINESS_PORT`   | `3008`  | Dashboard port                              |
| `RSTACK_NO_BUSINESS_HUB` | —       | Set to `1` to disable dashboard auto-launch |
| `RSTACK_NO_BROWSER`      | —       | Set to `1` to never open a browser tab      |

### Approvals (see [Approvals & Policy](/reference/approvals))

| Variable                | Default | Description                                                         |
| ----------------------- | ------- | ------------------------------------------------------------------- |
| `RSTACK_APPROVAL_TOKEN` | —       | Required to approve from the dashboard (prevents spoofing)          |
| `RSTACK_MANAGER_USERS`  | —       | Comma-separated manager allow-list (also settable in `policy.json`) |

### Notifications (see [Webhooks](/reference/webhooks))

| Variable                                                                    | Description                                             |
| --------------------------------------------------------------------------- | ------------------------------------------------------- |
| `RSTACK_SLACK_WEBHOOK`                                                      | Slack incoming webhook (Teams/Discord URLs auto-routed) |
| `RSTACK_TEAMS_WEBHOOK` / `RSTACK_DISCORD_WEBHOOK`                           | Teams / Discord webhooks                                |
| `RSTACK_TELEGRAM_BOT_TOKEN` + `RSTACK_TELEGRAM_CHAT_ID`                     | Telegram bot                                            |
| `RSTACK_WHATSAPP_TOKEN` + `RSTACK_WHATSAPP_PHONE_ID` + `RSTACK_WHATSAPP_TO` | WhatsApp Cloud API                                      |

***

## Project layout

```text theme={null}
your-project/
  .rstack/                    ← RStack state root
    agents/                   ← Project-local agent overrides
    skills/                   ← Project-local skill overrides
    plugins/                  ← Project-local plugin overrides
    prompts/                  ← Project-local prompt overrides
    memory/
      learnings.jsonl         ← Cross-run learnings
    registry/
      registry.json
      agents.json
      skills.json
      plugins.json
      routing.json
    rstack.config.json          ← Active Business Flex profile
    budget.json                 ← Budget policy and stage budgets
    runs/
      <run_id>/               ← One directory per run
        manifest.json
        context.md
        plan.md
        tasks.json
        approvals.json
        traceability.json
        events.jsonl
        specs/
        tasks/
```

***

## Project-local overrides

Place overrides in `.rstack/` or `.pi/rstack/`. Local files take precedence over the package defaults.

**Adding a custom agent:**

```bash theme={null}
mkdir -p .rstack/agents/sdlc
cat > .rstack/agents/sdlc/15-custom-stage.md << 'EOF'
---
name: 15-custom-stage
description: My custom SDLC stage (sdlc)
model: sonnet
tools:
  - Bash
  - Read
  - Write
---
# Custom Stage
...
EOF
```

**Adding a custom skill:**

```bash theme={null}
mkdir -p .rstack/skills/my-skill
cat > .rstack/skills/my-skill/SKILL.md << 'EOF'
# My Custom Skill
Instructions for the agent...
EOF
```

**Adding a custom plugin:**

```bash theme={null}
mkdir -p .rstack/plugins/my-domain/{agents,skills}
cat > .rstack/plugins/my-domain/plugin.json << 'EOF'
{
  "id": "my-domain",
  "name": "My Domain Pack",
  "version": "1.0.0",
  "domain": ["my-domain"],
  "agents": ["agents/specialist.md"],
  "skills": ["skills/my-skill/SKILL.md"]
}
EOF
```

***

## Agent frontmatter schema

All agent files follow this frontmatter schema:

```yaml theme={null}
---
name: agent-name              # Required. Unique across all agents.
description: |                # Required. Used for registry and routing.
  One-line description (role)
model: sonnet                 # Required. "sonnet", "opus", or "haiku"
tools:                        # Required. List of permitted tools.
  - Bash
  - Read
  - Write
  - Edit
  - Grep
color: cyan                   # Optional. Display color in Pi UI.
owner: Your Name              # Optional. Attribution.
---
```

Valid `model` values:

* `haiku` — Fast, lightweight tasks
* `sonnet` — Standard tasks (most pipeline agents)
* `opus` — Complex tasks: architecture, code generation, security

Valid `tools` values:

* `Bash`, `Read`, `Write`, `Edit`, `Grep`, `Find`, `LS`
* Validators should only have: `Read`, `Grep`, `Find`, `LS`

***

## Registry refresh

After adding local overrides, refresh the registry:

```bash theme={null}
rstack-agents validate
```

This re-scans all asset directories (package + project-local), rebuilds `registry/*.json`, and reports any errors.

***

## Adapter roadmap

Planned native adapters (not yet available):

| Adapter                | Status  | Description                                      |
| ---------------------- | ------- | ------------------------------------------------ |
| `adapters/mcp`         | Planned | Expose RStack tools to any MCP-compatible client |
| `adapters/claude-code` | Partial | Asset copy + CLAUDE.md bootstrap                 |
| `adapters/codex`       | Partial | AGENTS.md bootstrap                              |
| `adapters/gemini`      | Partial | GEMINI.md bootstrap                              |
| `adapters/sdk`         | Planned | Node/Python library for custom harnesses         |

Track progress and contribute at [github.com/richard-devbot/SDLC-rstack](https://github.com/richard-devbot/SDLC-rstack).