Configuration Guide

Rnix uses a layered configuration system with YAML files, agent definitions, and skill definitions. Run rnix init to bootstrap the configuration environment.

Configuration Model

Rnix configuration has three independent dimensions:

1. Config Layering (XDG-style)

YAML config files (providers.yaml, config.yaml, web-search.yaml) follow a global + project two-tier model:

Tier	Location	Purpose
Global	`~/.config/rnix/` (or `$XDG_CONFIG_HOME/rnix/`)	User-wide defaults
Project	`<project>/.rnix/`	Project-specific overrides

YAML files deep-merge: project values override global values.

2. Skill Storage (agentskills.io 2×2 model)

Skills follow the agentskills.io specification's dual-scope × dual-namespace model. Rnix implements two namespaces per scope:

	Native Namespace (Rnix)	Agents Namespace (agentskills.io)
Project scope	`<project>/.rnix/skills/`	`<project>/.agents/skills/`
User scope	`~/.config/rnix/skills/`	`~/.agents/skills/`

Native namespace (.rnix/skills/, ~/.config/rnix/skills/): Rnix-specific skills, highest priority within each scope
Agents namespace (.agents/skills/, ~/.agents/skills/): Follows the agentskills.io cross-tool standard — skills placed here are visible to Cursor, OpenCode, Windsurf, and other compatible tools

Priority: project/native > project/agents > user/native > user/agents. See Skill Packages for the full resolution model.

3. Data Directory (sessions & history)

Runtime artifacts — reasoning steps, checkpoints, events.jsonl, and resumable history — are not stored next to your config. They live in a single global data directory, resolved in this order:

Priority	Source	Resulting path
1	`RNIX_DATA_DIR`	the value, as-is
2	`XDG_DATA_HOME`	`$XDG_DATA_HOME/rnix`
3	(default)	`~/.local/share/rnix`

Under the data directory, every project gets its own subtree in a project registry, keyed by a deterministic, human-readable ID:

<data-dir>/
└── projects/
    ├── my-api-3f9a1c2b/         ← <sanitized-basename>-<hash8>
    │   └── steps/
    │       └── <uuid>/          ← events.jsonl, proc-info.json, checkpoints
    └── another-repo-7c4e0d11/
        └── steps/

The ID is <sanitized-basename>-<hash8>, where hash8 is the first 4 bytes of sha256(absolute-project-path). The hash keeps two projects that share a basename (e.g. two different api/ folders) from colliding, while the basename keeps the directory readable. Centralizing data this way lets rnix ps -a, rnix record, rnix replay, and rnix resume enumerate history across every project from one root, and lets garbage collection apply retention_days / max_entries globally.

Older releases stored session data in a cwd-relative <project>/.rnix/data/steps/. That location is superseded by the global data directory — .rnix/ now holds only config, state, and skills.

Directory Structure

~/.config/rnix/                  ← Global config (created by rnix init)
├── providers.yaml
├── config.yaml
├── web-search.yaml
├── agents/                      ← Global agent definitions
│   └── code-analyst/
│       ├── agent.yaml
│       └── instructions.md
└── skills/                      ← User skills (native namespace)
    └── code-analysis/
        └── SKILL.md

~/.agents/skills/                ← User skills (agents namespace, agentskills.io standard)
└── web-research/                ←   Shared with Cursor, OpenCode, etc.
    └── SKILL.md

<project>/.rnix/                  ← Project config (created by rnix init)
├── providers.yaml
├── config.yaml
├── init.yaml
├── compose.yaml
├── web-search.yaml
├── agents/                      ← Project agent definitions
├── skills/                      ← Project skills (native namespace)
└── state/                       ← Runtime state (trust marker, etc.)
                                 ← (session data lives in the global data dir — see "3. Data Directory")

<project>/.agents/skills/        ← Project skills (agents namespace, agentskills.io standard)
└── shared-util/                 ←   Shared across tools in the project
    └── SKILL.md

Note: ~/.agents/skills/ and .agents/skills/ are not created by rnix init. They are created on first use (rnix skill install --shared). This follows agentskills.io convention where the .agents/ directory belongs to the ecosystem, not any single tool.

Merge Rules

YAML files (providers.yaml, config.yaml, web-search.yaml): Deep merge — project overrides global
Agent directories (agents/): Shadow — project agent with same name completely replaces global agent
Skill directories (skills/): Shadow with 2×2 priority — project/native > project/agents > user/native > user/agents. Winning copy completely replaces shadowed copies.

Initialization

bash

# Create both global (~/.config/rnix/) and project (.rnix/) directories
$ rnix init
[init] created ~/.config/rnix/
[init] created .rnix/

# With MCP example configurations
$ rnix init --with-mcp-examples
[init] created ~/.config/rnix/
[init] created .rnix/
[init] added agents/playwright-demo/ with MCP Playwright config
[init] added agents/github-assistant/ with MCP GitHub config

rnix init is idempotent — it skips existing files and directories. --with-mcp-examples runs preflight checks to verify required binaries (e.g., npx) are available before creating example configs.

config.yaml — Global Configuration

Located at ~/.config/rnix/config.yaml (global) and optionally .rnix/config.yaml (project override).

Feature Profiles

Feature profiles control which emergent subsystems are active at runtime. They enable ablation experiments — selectively disabling capabilities to measure each layer's contribution to overall intelligence emergence.

There are four named presets and a custom mode for fine-grained control:

Profile	Description
`baseline`	Foundation only — bare LLM + VFS devices. No planning, spawning, or adaptive mechanisms.
`core`	Foundation + core mechanisms — planning, subprocess spawning, context compaction.
`adaptive`	Core + feedback loops — runtime learning, skill acquisition, path re-planning.
`full`	All capabilities enabled, including immune system. Default.
`custom`	Per-flag control — any flag not explicitly listed defaults to `true`.

Configuration:

yaml

# .rnix/config.yaml or ~/.config/rnix/config.yaml
features:
  profile: full   # baseline | core | adaptive | full | custom
  custom:         # only used when profile is "custom"
    planning: true
    replan: false
    specialize: true
    discover_skill: true
    spawn: true
    diff_memory: false
    stem_matcher: false
    immune: true
    compaction: true

Preset Matrix:

Feature	baseline	core	adaptive	full (default)
`planning`	false	true	true	true
`replan`	false	false	true	true
`specialize`	false	false	true	true
`discover_skill`	false	false	true	true
`spawn`	false	true	true	true
`diff_memory`	false	false	true	true
`stem_matcher`	false	false	true	true
`immune`	false	false	false	true
`compaction`	false	true	true	true

Environment Variable Override:

Set RNIX_FEATURE_PROFILE to override the config file setting. Valid values: baseline, core, adaptive, full, custom. Invalid values produce a warning and fall back to full.

bash

RNIX_FEATURE_PROFILE=baseline rnix "analyze this code"

Custom Mode:

When profile: custom, only the flags explicitly listed under custom: are applied. Unlisted flags default to true — custom mode is for surgical ablation, not wholesale disabling.

Inspecting the Active Profile:

Use rnix config show to display the active feature profile and flags. See CLI Reference for details.

See Feature Profiles & Ablation for how profiles map to the emergence stack.

Garbage Collection

yaml

gc:
  retention_days: 30      # Delete dead_at entries older than N days; 0 = disabled
  max_entries: 500        # Keep at most N history entries; 0 = disabled
  interval_seconds: 3600  # Background scan period (min 60, default 1h)

retention_days and max_entries are combined — hitting either triggers cleanup
Set both to 0 to disable the GC daemon entirely
Running and Suspended processes are permanently exempt

See Process Resume for GC CLI usage.

providers.yaml — LLM Providers

This file defines available LLM providers. Located at ~/.config/rnix/providers.yaml (global) and optionally .rnix/providers.yaml (project override).

yaml

version: "1"
default_provider: deepseek

providers:
  - name: claude
    driver: claude-cli
    default_model: haiku

  - name: cursor
    driver: cursor-cli
    command: agent              # CLI binary name (default: "agent")

  - name: groq
    driver: openai-compat
    base_url: https://api.groq.com/openai/v1
    default_model: llama-3.3-70b-versatile
    api_key_env: GROQ_API_KEY

  - name: ollama
    driver: openai-compat
    base_url: http://localhost:11434/v1
    default_model: llama3

  - name: deepseek
    driver: openai-compat
    base_url: https://api.deepseek.com/v1
    default_model: deepseek-chat
    api_key_env: DEEPSEEK_API_KEY

Fields

Field	Type	Description
`version`	`string`	Config format version (`"1"`)
`default_provider`	`string`	Default provider when none specified (default: `deepseek`)
`providers[].name`	`string`	Provider name, maps to `/dev/llm/<name>`
`providers[].driver`	`string`	Driver type: `claude-cli`, `cursor-cli`, or `openai-compat`
`providers[].command`	`string`	CLI binary name override for CLI drivers
`providers[].default_model`	`string`	Default model name
`providers[].base_url`	`string`	API base URL (for `openai-compat` driver)
`providers[].api_key_env`	`string`	Environment variable name for API key

Driver Types

Driver	How It Works	Examples
`claude-cli`	Invokes Claude Code CLI (`claude -p`)	Anthropic Claude
`cursor-cli`	Invokes Cursor CLI (`agent --print`)	Cursor
`openai-compat`	Calls OpenAI-compatible HTTP API	Ollama, Groq, DeepSeek, any OpenAI-compatible endpoint

Provider Resolution Priority

--provider CLI flag (highest priority)
agent.yaml → models.provider field
providers.yaml → default_provider
Built-in default: deepseek

Model Resolution Priority

--model CLI flag
agent.yaml → models.preferred field
Provider's default_model
Driver's built-in default

API Key Management

API keys are referenced via environment variables — never stored directly in config files. Resolved from project .env files first, then daemon process environment.

web-search.yaml — Web Search Backends

Configure search backends for the /dev/web device. Located at ~/.config/rnix/web-search.yaml (global) or .rnix/web-search.yaml (project, takes priority).

yaml

version: "1"
default_backend: tavily
backends:
  - name: tavily
    driver: tavily
    api_key_env: TAVILY_API_KEY
    max_results: 5
    search_depth: basic

  - name: exa
    driver: exa
    api_key_env: EXA_API_KEY
    num_results: 5

  - name: local-searxng
    driver: searxng
    base_url: http://localhost:8888

The project file fully overrides the global file (no merging). See Web Search for backend details and quick-start options.

Environment Files (.env)

Rnix supports project-level .env files for managing API keys and other environment variables without polluting the daemon's process environment.

Loading Order

.env — Base environment
.env.local — Local overrides (gitignore this)
.env.{RNIX_ENV} — Environment-specific (e.g., .env.production)
.env.{RNIX_ENV}.local — Environment-specific local overrides

RNIX_ENV

The RNIX_ENV environment variable selects which environment-specific files to load. Default: development.

bash

RNIX_ENV=production rnix "deploy the service"

Project Isolation

Each spawn request generates an independent environment snapshot from .env files. Variables are not written to os.Setenv — different projects' environments are fully isolated, even when sharing the same daemon.

init.yaml — Bootstrap Services

Defines services that start automatically when the daemon launches. Located at .rnix/init.yaml.

yaml

version: "1.0"

services:
  health-monitor:
    intent: "Monitor system health and report anomalies"
    agent: "monitor"
    restart: always
    max_restarts: 3

  code-watcher:
    intent: "Watch for file changes and trigger analysis"
    agent: "watcher"
    restart: on-failure
    depends_on:
      - health-monitor

Service Fields

Field	Type	Default	Description
`intent`	`string`	Required	Intent string for the service agent
`agent`	`string`	`""`	Named agent definition (empty = generic)
`restart`	`string`	`"no"`	Restart policy: `no`, `always`, `on-failure`
`max_restarts`	`int`	`3`	Maximum restart attempts
`depends_on`	`[]string`	`[]`	Services that must start first

Restart Policies

Policy	Behavior
`no`	Never restart (default)
`always`	Restart on any exit
`on-failure`	Restart only on non-zero exit code

compose.yaml — Multi-Agent Workflows

Compose files define DAG-based multi-agent workflows. Located at .rnix/compose.yaml.

yaml

version: "1.0"
intent: "Code review workflow"
model: "deepseek-v4-flash"

agents:
  analyzer:
    intent: "Analyze kernel/kernel.go code quality"
    agent: "code-analyst"

  doc-gen:
    intent: "Generate improvement documentation"
    depends_on:
      analyzer: completed

  checker:
    intent: "Verify analysis and documentation quality"
    depends_on:
      doc-gen: completed

Top-Level Fields

Field	Type	Description
`version`	`string`	Compose spec version (currently `"1.0"`)
`intent`	`string`	Overall workflow description
`model`	`string`	Global default model (agents can override)
`agents`	`map`	Agent definitions

Agent Fields

Field	Type	Description
`intent`	`string`	Task description for this agent
`agent`	`string`	Named agent definition (optional)
`model`	`string`	Model override for this agent
`provider`	`string`	Provider override for this agent
`depends_on`	`map`	Dependencies: `<upstream>: completed`
`timeout`	`duration`	Execution timeout
`max_retries`	`int`	Retry count on failure

Running Compose Workflows

bash

rnix compose up          # Run the workflow
rnix compose up --json   # Run with JSON output
rnix compose down        # Stop all compose processes
rnix compose resume --node <name>  # Resume a failed DAG node

Agent Manifest — agent.yaml

Each agent is defined by an agent.yaml file and an instructions.md file in agents/<name>/ (global: ~/.config/rnix/agents/, project: .rnix/agents/).

yaml

name: code-analyst
description: "Code quality analysis agent"
models:
  provider: deepseek
  preferred: deepseek-v4-flash
  fallback: deepseek-v4-pro
max_steps: 20
max_tokens: 50000
skills:
  - code-analysis
  - security-scan
mcp:
  servers:
    github:
      command: "npx"
      args: ["-y", "@anthropic/mcp-github"]
      env:
        GITHUB_TOKEN: "${GITHUB_TOKEN}"
      timeout: 30s
      max_output_tokens: 4096

Fields

Field	Type	Required	Description
`name`	`string`	Yes	Unique agent identifier
`description`	`string`	No	Human-readable description
`models`	`object`	No	LLM model preferences
`models.provider`	`string`	No	LLM provider name
`models.preferred`	`string`	No	Preferred model name
`models.fallback`	`string`	No	Fallback model name
`context_budget`	`int`	No	Per-step context window guard: max input tokens allowed in a single LLM call. When exceeded, the process self-suspends with exit code 3 (`context_full`) and can be resumed. `0` = auto-derive from `context_window × 0.9`; explicitly set values are clamped to `min(budget, context_window)`.
`max_steps`	`int`	No	Maximum reasoning steps (0 = default 10)
`max_tokens`	`int`	No	Maximum total tokens (0 = unlimited)
`skills`	`[]string`	No	Referenced skill names
`mcp`	`object`	No	MCP server configurations

MCP Server Config Fields

Field	Type	Required	Description
`command`	`string`	Yes	Executable to launch the MCP server
`args`	`[]string`	No	Command-line arguments
`env`	`map[string]string`	No	Environment variables (`${VAR}` expansion)
`timeout`	`duration`	No	Per-server timeout (default: `30s`)
`max_output_tokens`	`int`	No	Max tokens per tool output

Skill Definition — SKILL.md

Skills are defined as SKILL.md files following the agentskills.io standard. Storage uses a four-path model (project/user × native/agents namespace):

Path	Scope	Namespace	Priority
`<project>/.rnix/skills/`	project	native	1 (highest)
`<project>/.agents/skills/`	project	agents	2
`~/.config/rnix/skills/`	user	native	3
`~/.agents/skills/`	user	agents	4 (lowest)

See Skill Packages for the full multi-scope management model.

markdown

---
name: code-analysis
description: >
  Analyze code quality, identify bugs, performance issues
  and security vulnerabilities.
allowed-tools: /dev/fs /dev/shell /dev/web
metadata:
  author: rnix
  version: "1.0"
  tags: "code, quality"
---

# Code Analysis

## When to Use
...

## Workflow
1. Read source files via /dev/fs
2. Run analysis via /dev/shell
3. Generate report

Frontmatter Fields

Field	Type	Required	Description
`name`	`string`	Yes	Unique skill identifier
`description`	`string`	No	Short description (~100 tokens)
`allowed-tools`	`string`	Key field	Space-separated VFS device paths
`metadata`	`map`	No	Arbitrary key-value pairs

allowed-tools and Security

The allowed-tools field is the core of Rnix's permission model. A skill can only access VFS devices listed here:

Device	Capability
`/dev/fs`	Host filesystem read/write
`/dev/shell`	Shell command execution
`/dev/llm/<provider>`	LLM inference
`/dev/web`	Web search and fetch
`/mnt/mcp/*`	MCP server tools

When multiple skills are loaded by an agent, their allowed-tools are unioned — the agent can access any device permitted by any of its skills. Empty allowed-tools means no restrictions (can access all devices).

Environment Variables

Variable	Description
`RNIX_ENV`	Select environment for `.env` file loading (default: `development`)
`RNIX_ASCII`	Set to `1` to force ASCII mode (disable Unicode glyphs)
`RNIX_FEATURE_PROFILE`	Feature profile override: `baseline`, `core`, `adaptive`, `full`, `custom`
`XDG_CONFIG_HOME`	Override global config directory (default: `~/.config`)
`XDG_RUNTIME_DIR`	Used to determine socket path
`TAVILY_API_KEY`	Tavily search API key (auto-detected for `/dev/web`)
`EXA_API_KEY`	Exa search API key (auto-detected for `/dev/web`)
`RNIX_SEARCH_URL`	SearXNG instance URL (auto-detected for `/dev/web`)

Socket Path

The daemon socket location follows this priority:

$XDG_RUNTIME_DIR/rnix/rnix.sock (e.g., /run/user/1000/rnix/rnix.sock)
/tmp/rnix-{uid}/rnix.sock (fallback)

Directory permissions: 0700 (current user only).

Quick Start — Installation and first run
LLM Providers — Provider details and serve gateway
Web Search — Search backend configuration
Skill Packages — Multi-scope skill management
Process Resume — GC configuration and process recovery
MCP Integration — MCP server configuration
Intelligence Emergence — Emergent architecture and feature profile mapping
Core Concepts — Process, VFS, Agent/Skill model
Reference Manual — Complete API and CLI reference

Configuration Guide ​

Configuration Model ​

1. Config Layering (XDG-style) ​

2. Skill Storage (agentskills.io 2×2 model) ​

3. Data Directory (sessions & history) ​

Directory Structure ​

Merge Rules ​

Initialization ​

config.yaml — Global Configuration ​

Feature Profiles ​

Garbage Collection ​

providers.yaml — LLM Providers ​

Fields ​

Driver Types ​

Provider Resolution Priority ​

Model Resolution Priority ​

API Key Management ​

web-search.yaml — Web Search Backends ​

Environment Files (.env) ​

Loading Order ​

RNIX_ENV ​

Project Isolation ​

init.yaml — Bootstrap Services ​

Service Fields ​

Restart Policies ​

compose.yaml — Multi-Agent Workflows ​

Top-Level Fields ​

Agent Fields ​

Running Compose Workflows ​

Agent Manifest — agent.yaml ​

Fields ​

MCP Server Config Fields ​

Skill Definition — SKILL.md ​

Frontmatter Fields ​

allowed-tools and Security ​

Environment Variables ​

Socket Path ​

Related Documentation ​

Configuration Guide

Configuration Model

1. Config Layering (XDG-style)

2. Skill Storage (agentskills.io 2×2 model)

3. Data Directory (sessions & history)

Directory Structure

Merge Rules

Initialization

config.yaml — Global Configuration

Feature Profiles

Garbage Collection

providers.yaml — LLM Providers

Fields

Driver Types

Provider Resolution Priority

Model Resolution Priority

API Key Management

web-search.yaml — Web Search Backends

Environment Files (.env)

Loading Order

RNIX_ENV

Project Isolation

init.yaml — Bootstrap Services

Service Fields

Restart Policies

compose.yaml — Multi-Agent Workflows

Top-Level Fields

Agent Fields

Running Compose Workflows

Agent Manifest — agent.yaml

Fields

MCP Server Config Fields

Skill Definition — SKILL.md

Frontmatter Fields

allowed-tools and Security

Environment Variables

Socket Path

Related Documentation