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:

npx rstack-agents init --profile business-flex

See 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)

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)

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

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:

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:

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:

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:

---
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:

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.