SecurityExecution Safety Model

Machine Execution Safety

Name: LyDos Agent OS
Author: LYDOS

LYDOS agents never mutate your system without explicit authorization. Every write, delete, and shell execution operation goes through a configurable safety layer with dry-run mode and approval gates.

Dry-run by default

Agents show exactly what they would do before doing it. No filesystem changes without opt-in.

Approval gates

Every mutation prompts [y/N] before executing. Headless mode requires explicit opt-out.

Blocked path list

Sensitive paths (.env, .git/config, node_modules) cannot be touched by any agent.

Mutation budget

Agents are capped at max_file_mutations (default 10) per task to prevent runaway changes.

Execution Modes

Two flags govern how LYDOS agents interact with your system. Both default to the safe position — you must explicitly disable them to unlock mutating operations.

Flag	Default	Effect when true
`dry_run`	true	Agent plans all actions and prints a diff but makes zero filesystem or network changes.
`require_approval`	true	Before any mutation, the agent prints the action and waits for [y/N] confirmation on stdin.

TIP

Run any agent with dry_run: true to review the complete action plan before committing. The output shows exactly which files would be read, written, or deleted — including line-level diffs for file mutations.

Blocked Paths

These paths are hardcoded into Q48 Kavach (the agent confinement engine) and cannot be overridden at runtime — not even with require_approval: false.

.lydos/config.yaml — blocked_paths (immutable defaults)TEXT

# These paths are ALWAYS blocked regardless of config overrides
blocked_paths:
  - ".env"                    # Environment secrets
  - ".env.*"                  # All .env variants (.env.local, .env.production, etc.)
  - ".git/config"             # Git remote and authentication config
  - ".git/hooks/**"           # Git lifecycle hooks
  - "node_modules/**"         # Dependency tree (read-only exceptions via allow_read)
  - "*.pem"                   # TLS certificates
  - "*.key"                   # Private keys
  - "**/.ssh/**"              # SSH keys
  - "**/secrets/**"           # Any directory named secrets/
  - "**/*.tfstate"            # Terraform state files (contain secrets)

NOTE

Agents can read files in blocked paths for analysis purposes (to detect secret leaks, for example), but they can never write, append, rename, or delete them. A blocked-path write attempt raises a PathConfinementError and terminates the task.

Allowed Actions

Actions are classified into three tiers. Tier 1 operations require no configuration changes — they are always available. Tier 2 operations require approval before each execution. Tier 3 operations require an explicit opt-in in the config and a per-task flag.

Operation	Tier	Default state	Notes
Read file	1 — Safe	Always allowed	No approval required. Blocked paths are read-only.
Analyze code	1 — Safe	Always allowed	AST parsing, semantic analysis. Zero side-effects.
Generate plan	1 — Safe	Always allowed	Agent produces a diff/action list without applying it.
Search / grep	1 — Safe	Always allowed	Filesystem search and pattern matching.
Write file	2 — Approval	Requires [y/N]	Shown as a unified diff before applying.
Delete file	2 — Approval	Blocked by default	Must set allow_delete: true in config.
Network request	2 — Approval	Requires opt-in	Set allow_network: true. Shown as URL + method.
Execute shell	3 — Explicit	Blocked by default	Requires allow_shell: true and explicit approval per command.
Deploy / publish	3 — Explicit	Blocked by default	Requires allow_deploy: true and a named target.

Mutation Classification

Every action an agent takes is classified into one of twelve mutation classes. The classification determines the risk level and approval requirements automatically.

Mutation Class	Risk	Approval	Example
`read_only`	Safe	None	File read, code analysis, search
`local_write`	Low	Config-based	Write markdown, update source file
`local_delete`	High	Required	Remove file, clean build artifacts
`shell_exec`	High	Required	Run test suite, execute build
`git_mutation`	Medium	Required	Commit, branch, tag operations
`dependency_install`	Medium	Required	npm install, pip install
`config_change`	Medium	Required	Update .lydos/config.yaml
`env_access`	High	Required	Read .env variables
`network_call`	Low	Config-based	HTTP GET to external API
`remote_write`	High	Required	POST to external service
`privileged_action`	Critical	Explicit confirm	System-level operations
`unknown`	High	Required	Unclassified action

Risk Levels and Approval Policy

Risk levels determine how LYDOS handles approval. The policy engine evaluates the mutation class, target paths, and active configuration to produce a final decision.

Risk Level	Default Behavior	Can Override?
safe	Auto-allowed (if dry_run is false)	N/A
low	Auto-allowed or ask, based on config	Yes, via require_approval
medium	Prompt for approval	Yes, in balanced/fast mode
high	Always prompt for approval	Only in unrestricted CI mode
critical	Explicit confirmation with warning	No bypass available

Execution Plans

Before any task runs, LYDOS builds an execution plan that describes exactly what the agent intends to do. The plan is persisted and can be reviewed via CLI, API, or the dashboard.

terminalBASH

# Preview the execution plan before running
lydos plan code-reviewer --prompt "Review authentication layer"

# Output:
# Plan ID:        plan_a7f3c9e2
# Agent:          code-reviewer
# Provider/Model: groq / llama-3.3-70b-versatile
# Planned Actions: 4
#   1. Read src/auth/*.ts (read_only)
#   2. Read src/middleware/auth.ts (read_only)
#   3. Analyze token validation (read_only)
#   4. Generate review report (local_write)
# Risk Level:     low
# Approval:       not required (read-heavy task)
# Dry-run:        true
# Files affected:  1 (report output)

# Run with plan preview inline
lydos run --explain --provider groq "Analyze this codebase"

# Get plan via API
curl -s -X POST http://localhost:8888/api/execution/plan \
  -H "Content-Type: application/json" \
  -d '{"task_description": "Review auth", "agent_type": "code-reviewer"}'

TIP

Use lydos plan as a non-destructive way to see what any agent would do before committing to a live run. The plan is computed without any side effects.

Execution Receipts

After every execution (including dry-runs), LYDOS generates an execution receipt documenting exactly what happened. Receipts are the audit trail for every agent action.

terminalBASH

# List recent execution receipts
lydos receipts --limit 10

# View a specific receipt
lydos receipt rcpt_b8d4e1f3

# Output includes:
# Receipt ID:      rcpt_b8d4e1f3
# Task ID:         task_9c2a7f01
# Agent:           code-reviewer
# Provider:        groq / llama-3.3-70b-versatile
# Mode:            live
# Duration:        2340ms
# Actions:         4 attempted, 4 completed
# Files read:      3
# Files written:   1
# Files deleted:   0
# Errors:          0
# Rollback:        possible (file backup available)

# Get receipt via API
curl -s http://localhost:8888/api/execution/receipt/rcpt_b8d4e1f3

Rollback Visibility

LYDOS does not claim automatic rollback for all operations. Instead, it provides honest rollback visibility — telling you exactly what can and cannot be reversed.

Action	Rollback	Strategy
File write	Yes	SHA-256 hash + before/after snapshot
File delete	Partial	File content cached if < 1MB
Git commit	Yes	git revert suggested in receipt
Shell command	No	Side effects not automatically reversible
Dependency install	Partial	Package diff shown, manual uninstall
Network write	No	External API calls not reversible
Config change	Yes	Old/new config snapshot preserved

WARNING

Rollback is best-effort and not guaranteed for all mutation types. Shell command side effects, network writes, and external API calls cannot be automatically reversed. Always use dry-run mode first to preview changes before committing to a live execution.

Approval Workflow

When an action requires approval, LYDOS follows a structured workflow: plan, review, approve/reject, execute, receipt.

terminalBASH

# Step 1: Plan the task (automatic)
lydos run --provider groq "Refactor auth module"
# → Execution plan generated, approval required

# Step 2: Review pending approvals
lydos approvals
# ID            Agent           Risk    Action
# plan_a7f3c9   code-reviewer   medium  Write 3 files

# Step 3: Approve or reject
lydos approve plan_a7f3c9
# → Task execution begins

lydos reject plan_a7f3c9 --reason "Scope too broad"
# → Task rejected, no changes made

# Step 4: View receipt after execution
lydos receipt plan_a7f3c9

Agent Access Boundaries

Each agent task runs within a workspace boundary defined at invocation time. The agent cannot read or write files outside this boundary, even if those files are accessible to the current user.

.lydos/config.yamlYAML

# Workspace boundary — agents cannot operate outside this path
workspace:
  root: "."                   # Relative to the project root (default: current directory)
  follow_symlinks: false       # Do not follow symlinks that escape the workspace
  max_depth: 10                # Maximum directory traversal depth

# Per-task mutation budget
limits:
  max_file_mutations: 10       # Max files an agent can modify per task (default: 10)
  max_file_size_kb: 512        # Max size of any single file read into context
  max_total_tokens: 200000     # Token budget for the full task context window

# Network access (off by default)
network:
  allow_network: false
  allowed_hosts: []            # Whitelist of hostnames when allow_network: true
  deny_hosts:                  # Always-blocked hosts (even when allow_network: true)
    - "169.254.169.254"        # AWS/GCP metadata service
    - "metadata.google.internal"

Configuration

Safety settings live in .lydos/config.yaml at the project root. They can also be passed as flags to the lydos CLI or set per-request in the REST API.

.lydos/config.yaml — full safety sectionYAML

# ── Safety configuration ─────────────────────────────────────────────────────
safety:
  # Dry-run mode: plan but never execute mutations
  dry_run: true                # default: true (must set false to mutate)

  # Approval gate: prompt before every mutation
  require_approval: true       # default: true

  # File deletion requires explicit flag AND approval
  allow_delete: false          # default: false

  # Shell command execution (highest privilege, disabled by default)
  allow_shell: false           # default: false

  # Outbound network access
  allow_network: false         # default: false

  # Deploy / publish operations
  allow_deploy: false          # default: false

  # Hard limit on files modified per task
  max_file_mutations: 10       # default: 10

  # Paths that CANNOT be written/deleted (in addition to immutable defaults)
  extra_blocked_paths:
    - "infrastructure/**"
    - "*.prod.env"

Override for Power Users

Experienced users running LYDOS in a fully sandboxed CI environment or isolated container may want to disable the interactive prompts. The following configuration runs agents in fully autonomous mode — read this carefully before applying.

WARNING

Disabling dry_run and require_approval removes all interactive guardrails. Only use this in environments where the workspace is completely disposable (a fresh Docker container, a CI ephemeral runner, etc.). Never run autonomous mode directly on a production filesystem or a machine with cloud credentials attached.

.lydos/config.yaml — autonomous CI modeYAML

# WARNING: Only use in isolated, ephemeral environments
safety:
  dry_run: false               # Mutations will be applied immediately
  require_approval: false      # No prompts — agent runs to completion autonomously
  allow_delete: true           # Allow file deletion
  allow_shell: true            # Allow shell command execution
  allow_network: true          # Allow outbound network access
  max_file_mutations: 50       # Higher budget for CI refactor tasks

  allowed_hosts:               # Still restrict to known hosts even in CI
    - "api.github.com"
    - "pypi.org"
    - "registry.npmjs.org"

The same overrides work as CLI flags for one-off autonomous runs:

terminalBASH

# Run a single agent task with all approval gates disabled
# (Use only in isolated environments)
lydos agent run code-reviewer \
  --dry-run=false \
  --require-approval=false \
  --allow-shell \
  --prompt "Refactor all imports in ./src to use path aliases"

# Or via environment variable (useful in CI pipelines)
export LYDOS_DRY_RUN=false
export LYDOS_REQUIRE_APPROVAL=false
lydos agent run code-reviewer --prompt "..."

# Always preview first with dry-run before disabling it
lydos agent run code-reviewer --dry-run=true --prompt "..." | head -50

Q48 Kavach — Agent Confinement Engine

All safety enforcement is implemented in the Q48 Kavach engine (/api/q48/*). Kavach runs as a policy layer between the agent runtime and the filesystem/network adapters. Every operation is checked against the active policy before execution — the agent cannot bypass this layer.

Kavach emits structured audit events for every approved and rejected action. Events are written to ~/.config/lydos/audit.jsonl and available via the REST API at GET /api/q48/audit.

terminalBASH

# View recent Kavach audit events
curl -s http://localhost:8888/api/q48/audit | python3 -m json.tool | head -40

# Get the current active policy
curl -s http://localhost:8888/api/q48/policy | python3 -m json.tool

# Update policy at runtime (reload without server restart)
curl -X POST http://localhost:8888/api/q48/policy \
  -H "Content-Type: application/json" \
  -d '{"dry_run": false, "require_approval": true, "max_file_mutations": 20}'

Machine Execution Safety

Execution Modes

Blocked Paths

Allowed Actions

Mutation Classification

Risk Levels and Approval Policy

Execution Plans

Execution Receipts

Rollback Visibility

Approval Workflow

Agent Access Boundaries

Configuration

Override for Power Users

Q48 Kavach — Agent Confinement Engine

Related Documentation