Single-Source Project Config

One YAML, full runtime: model + MCP servers + permission policy in .praisonai/config.yaml

from praisonaiagents import Agent

agent = Agent(name="config-agent", instructions="Load all settings from a single config file.")
agent.start("Use praison.toml as the single source of truth for all settings.")

One .praisonai/config.yaml wires your project’s full agent runtime — model, MCP servers, permissions — for every praisonai run in the directory.

Values can reference ${VAR}, {env:NAME:-default}, or {file:./relative/path} — see Value Interpolation — and praisonai config provenance shows which layer/file supplied each key.

praisonai run "Open the docs site and screenshot the home page"

The user keeps settings in .praisonai/config.yaml; every praisonai run in the project loads that single source.

Quick Start

1. Drop a config file

   Create .praisonai/config.yaml in your project root:

   # .praisonai/config.yaml
   agent:
     model: gpt-4o
   
   mcp:
     servers:
       playwright:
         command: ["npx", "-y", "@playwright/mcp"]
   
   permissions:
     default: ask
     rules:
       - { pattern: "bash:git *", action: allow }
       - { pattern: "bash:rm *",  action: deny }

2. Run anywhere in the project

   praisonai run "Open the docs site and screenshot the home page"

   Model, MCP server, and permission rules are picked up automatically — no flags needed.

3. Verify resolution

   praisonai config show --sources

   Shows which layers contributed (defaults, global, project, env, CLI).

How It Works

The resolver deep-merges five layers (highest wins):

CLI flags always win. Config fills the gaps. Walk-up discovery deep-merges every ancestor config from the repo root down to cwd, not just the nearest one.

Configuration Schema

mcp.servers.<name>

permissions

Two equivalent forms:

Structured (rule list):

permissions:
  default: ask
  rules:
    - { pattern: "bash:git *", action: allow }
    - { pattern: "bash:rm *",  action: deny }

Flat mapping:

permissions:
  "read:*": allow
  "bash:rm *": deny
  "*": ask

Precedence

• --mcp, if present, merges with config-declared servers — CLI ad-hoc tools are added alongside every enabled config server.
• --allow / --deny / --permissions are merged on top of config rules — CLI wins per-pattern.
• --permission-default sets the fallback action, overriding permissions.default from config.

Common Patterns

Pin a model + a single MCP server

# .praisonai/config.yaml
agent:
  model: gpt-4o-mini

mcp:
  servers:
    filesystem:
      command: ["npx", "-y", "@modelcontextprotocol/server-filesystem", "."]

praisonai run "List all Python files in the project"

CI-safe defaults

# .praisonai/config.yaml
agent:
  model: gpt-4o

permissions:
  default: deny
  rules:
    - { pattern: "read:*",    action: allow }
    - { pattern: "bash:git *", action: allow }

All tool calls are denied unless explicitly allowed — safe for unattended CI runs.

Mix with CLI flags

Config gives the base; flags override per-run:

# Override MCP server for this run only
praisonai run "Scrape the homepage" --mcp "npx -y @playwright/mcp"

# Add an extra allow rule on top of config
praisonai run "Deploy" --allow 'bash:kubectl *'

Declare-but-not-wire a server

mcp:
  servers:
    experimental:
      command: ["node", "my-mcp-server.js"]
      enabled: false   # declared but not activated

Best Practices

Related