Skip to content

Paths & Security

Complete guide to path configuration and file access control in Agent.md.

Overview

Agent.md uses a two-level path system:

  1. Global paths (runtime) — Configure where agents and databases live
  2. Agent paths (frontmatter) — Declare what each agent can access

Resolution order: CLI → ENV → Defaults

Workspace Structure

Default layout:

~/.config/agentmd/
└── config.yaml         # Application settings (auto-created on first run)

~/agentmd/
├── .env                # API keys (secrets)
├── agents/
│   ├── agent1.md
│   ├── agent2.md
│   └── mcp-servers.json (optional)
└── data/
    └── agentmd.db

Global Paths (Runtime Level)

Four paths can be configured:

Path Description Default
workspace Root directory for agents ~/agentmd
agents_dir Where .md files live {workspace}/agents
db_path SQLite execution history {workspace}/data/agentmd.db
mcp_config MCP servers file {agents_dir}/mcp-servers.json

Configuration File

Runtime settings live in ~/.config/agentmd/config.yaml (XDG standard). This file is auto-created with defaults on first run — no manual setup needed.

# ~/.config/agentmd/config.yaml
workspace: ~/agentmd
agents_dir: agents          # relative to workspace

defaults:
  provider: google
  model: gemini-2.5-flash

CLI Arguments (Highest Priority)

agentmd start \
  --workspace /path/to/workspace \
  --agents-dir /path/to/agents \
  --db-path /path/to/db.db

# Available for: start, run, list

Defaults (Lowest Priority)

workspace     → ~/agentmd
agents_dir    → {workspace}/agents
db_path       → {workspace}/data/agentmd.db
mcp_config    → {agents_dir}/mcp-servers.json

Resolution Examples

Example 1: All defaults 

config     → ~/.config/agentmd/config.yaml
workspace  → ~/agentmd
agents_dir → ~/agentmd/agents
db_path    → ~/agentmd/data/agentmd.db

Example 2: Custom workspace via config.yaml 

workspace: /home/alice/my-agents

workspace  → /home/alice/my-agents
agents_dir → /home/alice/my-agents/agents
db_path    → /home/alice/my-agents/data/agentmd.db

Example 3: Config + CLI (CLI wins) 

# config.yaml
workspace: /home/alice/agents

agentmd start --db-path /var/lib/agentmd.db

workspace  → /home/alice/agents           (config.yaml)
db_path    → /var/lib/agentmd.db          (CLI - highest)

Agent Paths (Frontmatter Level)

Each agent declares allowed paths in frontmatter. The paths field controls which directories and files the agent can access for reading, writing, and listing.

Configuration

paths:
  - ./data
  - ./output

Defaults: [workspace_root] (entire workspace)

Behavior: - Directory: access all files within (recursive) - File: access specific file only - Relative paths resolve from workspace_root (for both reads and writes) - Absolute paths used as-is - ~ expanded to home directory

Examples:

# Access entire workspace (default, omit field)

# Single directory
paths: ./data

# Multiple locations
paths:
  - ./data
  - ./logs
  - /var/log/app
  - ./output

# Specific files
paths:
  - ./config/settings.json
  - ./data/input.csv
  - ./output/result.txt

Path resolution example:

paths:
  - ./reports
  - ./data

When agent writes reports/summary.txt: - Resolves to: workspace root + reports/summary.txt

Security Restrictions

File access is validated before every operation.

Forbidden Paths

Cannot access:

  1. Agents directory (workspace/agents)
  2. Prevents reading or modifying agent code

  3. Error: "Access denied: cannot access agents directory"

  4. .env files (any .*env*)

  5. Prevents credential leakage or modification

  6. Error: "Access denied: cannot access .env files"

  7. .db files (write only)

  8. Prevents database corruption
  9. Error: "Access denied: cannot write to .db files"

Watch Triggers

Agents with watch triggers automatically gain access to watched paths:

trigger:
  type: watch
  paths:
    - ./data/input.txt

# Implicit access to ./data/input.txt

Explicit paths is combined with watch paths:

trigger:
  type: watch
  paths:
    - ./data/input.txt
paths:
  - ./config
  - ./output
# Can access ./data/input.txt, ./config, AND ./output

Common Patterns

Minimal Access

paths: ./data
# Can only access ./data

Isolated Agent

paths:
  - ./data/input
  - ./output/agent1

Multi-Source Agent

paths:
  - ./data
  - ./logs
  - /var/log/app
  - ./reports

Specific File Access

paths:
  - ./config/settings.json
  - ./data/input.csv
  - ./output/result.txt

Setup Examples

Development

Use defaults (zero-config):

agentmd start

Structure: 

~/.config/agentmd/config.yaml
~/agentmd/
├── .env
├── agents/
└── data/agentmd.db

Production

Custom workspace via config:

# ~/.config/agentmd/config.yaml
workspace: /srv/agentmd

Structure: 

/srv/agentmd/agents/
/srv/agentmd/data/agentmd.db

Multi-Workspace

agentmd start --workspace ~/projects/project1
agentmd start --workspace ~/projects/project2

Docker

docker run -v ./agentmd:/root/agentmd agentmd start

Best Practices

Principle of Least Privilege

Grant minimum necessary access:

# ✅ Good: specific paths
paths:
  - ./data/input
  - ./output/results

# ❌ Avoid: overly broad
paths: /

Separate Concerns

Use different directories per agent:

# Agent 1
paths:
  - ./data/agent1
  - ./output/agent1

# Agent 2
paths:
  - ./data/agent2
  - ./output/agent2

Use Relative Paths

Prefer relative for portability:

# ✅ Portable
paths:
  - ./data
  - ./output

# ⚠️ Machine-specific
paths: /Users/alice/data

Keep Workspace Self-Contained

workspace/
├── agents/
├── data/
└── config/

Troubleshooting

"No agents found"

Cause: Wrong agents_dir

Fix: Check path: 

ls -la ~/agentmd/agents
agentmd start --agents-dir /correct/path

"Access denied: outside allowed paths"

Cause: Agent tried to access an unlisted path

Fix: Add to paths: 

paths:
  - ./data
  - ./logs    # Add missing
  - ./output
  - /tmp/cache  # Add missing

"Access denied: cannot read from agents directory"

Cause: Tried to read workspace/agents

Fix: Move files to readable location: 

mv workspace/agents/file.txt workspace/data/

"Database error"

Cause: db_path directory missing

Fix: Create parent or use a custom path: 

mkdir -p ~/agentmd/data
agentmd start --db-path ~/agentmd/data/agentmd.db

"Permission denied"

Cause: No write access to paths

Fix: Use accessible paths: 

agentmd start --workspace ~/agentmd