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):

Layer	Source	Precedence
1	Built-in defaults	Lowest
2	~/.praisonai/config.yaml (global)
3	.praisonai/config.yaml (project, walk-up — all ancestors merged)
4	Environment variables
5	CLI flags	Highest

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>

Key	Type	Default	Description
command	list[str] or str	—	Local (stdio) server launch command. List form preferred. Required for local servers; ignored for remote.
args	list[str]	[]	Extra args appended to command. Local servers only.
env	dict[str, str]	{}	Env vars for the server process. Local servers only.
enabled	bool	true	Set false to declare-but-not-wire a server.
type	"remote"	—	Marks a remote server. Optional — a non-empty url also implies remote.
url	str	—	Remote endpoint (HTTP-stream, SSE, or WebSocket). Presence implies remote.
headers	dict[str, str]	{}	HTTP headers for remote servers. Ignored for legacy SSE URLs ending in /sse (a warning is printed).
timeout	int (milliseconds)	30000	Per-server connect timeout. Converted to seconds before being passed to the SDK MCP(...).

praisonai run wires every enabled server under mcp.servers.* — multiple local (stdio) servers and remote (url: / type: remote) servers are all aggregated and exposed to the agent. Servers with enabled: false are skipped silently. If --mcp "<command>" is also given on the command line, its tools are added on top of the config servers, not in place of them.

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

read:* here does not authorise .env / private-key reads — the built-in secret gate defaults those to ask unless a secret-specific rule (e.g. read:*.env=allow) opts in. See Secret Read Gate.

Key	Type	Default	Description
default	"allow" | "deny" | "ask"	—	Fallback action when no rule matches. Equivalent to "*": <default> in flat form.
rules	list[{pattern, action}]	[]	Structured rule list. action must be allow, deny, or ask. Invalid actions are silently dropped.
<pattern>	"allow" | "deny" | "ask"	—	Flat shorthand. Can be combined with rules and default.

---

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

Commit .praisonai/config.yaml for team alignment

Checked-in config ensures every teammate and CI runner uses the same model, MCP servers, and permission defaults automatically.

Keep secrets out of env in config

mcp.servers.<x>.env is fine for non-secret config values (paths, flags). For API tokens, use shell environment variables — they are read by the server process at runtime without being stored in YAML.

Use praisonai config show --sources to debug

When behaviour is unexpected, praisonai config show --sources prints exactly which layer won for each key.

Prefer the structured rules form when ordering matters

The rules: list is evaluated in order; priority fields are respected. The flat mapping form is convenient for simple deny lists but gives no ordering guarantees.

---

Related

Configuration File

Deep-merge semantics and ancestor discovery details

CLI Configuration

Full cascade reference for the praisonai CLI config layers

Declarative Permissions

All surfaces for pre-declaring allow/deny rules

MCP Transports

Remote MCP server configuration

Config CLI Reference

praisonai config subcommand reference