Configuration

Configuration Files

Runeya stores all its configuration in ./.runeya/ in the current folder (or via the DATA_DIR variable).

settings.json

Global settings, notification preferences, AI scenarios, enterprises, and log parsers.

{
  "mode": "local-simple",
  "notifications": {
    "scenario_waiting_input": true,
    "ai_conversation_complete": true,
    "ai_conversation_error": true,
    "service_error_log": true,
    "service_status_changed": true,
    "service_health_changed": true
  },
  "logParsers": [
    {
      "id": "uuid",
      "name": "JSON Parser",
      "code": "(line) => { ... }",
      "version": 2
    }
  ],
  "scenarios": [],
  "enterprises": []
}

Notifications in the UI

In Settings → Notifications, preferences are grouped by theme:

• Scenarios: scenario_waiting_input
• AI Conversations: ai_conversation_complete, ai_conversation_error
• Services: service_error_log, service_status_changed, service_health_changed

Each section also includes quick controls:

• Collapse/Expand from the section header (chevron)
• Enable all / Disable all to toggle the full section in one action

This grouping is visual only: the settings.json format is unchanged.

Scenario Editor (UI)

In the scenario editor (Settings → Scenarios), you can delete the selected element:

• Selected node: Delete node button or Delete / Backspace
• Selected group: Delete group button or Delete / Backspace
• Selected link (edge): Delete edge button or Delete / Backspace
• The selected link is also visually highlighted in the canvas.

Conditional branching (edges)

When a node has multiple outgoing edges, you can configure a description per edge to guide the AI's choice:

1. In the scenario editor, click the source node to open the edit panel.
2. The Branches section lists each outgoing edge with a description field.
3. Enter a short description (max 500 characters) that describes the condition or intent of that branch (e.g. "Tests passed", "Error detected").
4. Save the node.

At runtime, the runner automatically injects the choices into the AI prompt:

Reply PASS1 for "Tests passed" or PASS2 for "Error detected"

The AI must end its response with PASS1 or PASS2 on its own line to select the branch. If a description is empty, a generic label (Branch 1, Branch 2, …) is used.

Nodes with a single edge: unchanged behavior — the AI responds PASS or FAIL as before.

Scenario Run Start (UI)

When starting a scenario from the AI tab:

• A modal lets you enter a run name (conversation title).
• The Generate name with AI button pre-fills this field.
• If left blank, Runeya falls back to the scenario name.
• Overly generic LLM outputs (for example scenario) are filtered server-side.

Enterprise Editor (UI)

In Settings → Scenarios, you can also manage enterprises:

• Create/edit an enterprise (name, description, leader).
• Manage teams and people (manager parentId, teamId, per-person prompt).
• Delete an enterprise.

When creating an AI conversation with an enterprise selected:

• The backend creates a workspace in DATA_DIR/enterprise-runs/<conversationId>/.
• The initial brief is saved to USER_REQUEST.md.
• One markdown file is created for each enterprise member.

services.json

Configuration for all services.

[
  {
    "id": "service-uuid",
    "name": "api",
    "description": "REST API",
    "command": "node dist/index.js",
    "cwd": "/home/user/my-app",
    "shell": false,
    "projectId": "project-uuid",
    "agentId": "agent-uuid",
    "parserIds": ["parser-uuid"],
    "envSecrets": []
  }
]

environments.json

Global environments and their variables.

[
  {
    "id": "env-uuid",
    "name": "development",
    "variables": {
      "var-uuid": {
        "key": "DATABASE_URL",
        "value": "postgres://localhost:5432/myapp",
        "secret": false
      }
    }
  }
]

System Environment Variables

Variable	Default	Description
RUNEYA_HTTP_PORT	9545	Server HTTP port (takes priority over PORT)
PORT	9545	Server HTTP port (legacy — use RUNEYA_HTTP_PORT instead)
DATA_DIR	./.runeya	Project data directory
RUNEYA_AGENT_PORT	9546	Local agent port (default: RUNEYA_HTTP_PORT + 1)
RUNEYA_LOG_LEVEL	info	Server log level

Atomic Writes

All JSON files are written atomically:

1. write data to services.json.tmp
2. rename services.json.tmp → services.json

This guarantees that a crash during writing won't corrupt the data.