---
title: "Configuration"
description: "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
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
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
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
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
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
---
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
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).