Managed Config

Distribute org-wide defaults and enforce policy from one remote source — fail-soft, opt-in

Point PraisonAI at a URL or directory your organisation controls to distribute team defaults and enforce policy from one source of truth.

Quick Start

1. Point at a managed source

   The shortest opt-in — one environment variable:

   export PRAISONAI_MANAGED_CONFIG_URL="https://config.company.internal/praisonai.yaml"

   PraisonAI now pulls team defaults from that URL. If it is unreachable, PraisonAI uses the last-good cached copy or skips the layer — it never blocks a run.

2. Or use a managed directory

   For MDM / config-management tooling, drop config.yaml in a directory and point the CLI at it:

   export PRAISONAI_MANAGED_CONFIG_DIR=/etc/praisonai/managed

   Every praisonai run on that machine reads from /etc/praisonai/managed/config.yaml. No network required.

A managed config file looks like any other PraisonAI config, with optional policy keys:

# team.yml
agent:
  temperature: 0.3        # a suggested default (below local)
model_allowlist:          # enforced policy (above local)
  - gpt-4o
  - gpt-4o-mini
enforce: true             # default; set false to make the whole source advisory

Precedence Ladder

The managed layer splits into two: enforced policy sits above your local config, while managed defaults sit below it — so teams can suggest without clobbering deliberate local choices.

Enforcement vs. Advisory

Only two keys are treated as policy: permissions and model_allowlist. When enforced they replace (not merge or concat) their local counterpart wholesale — a local override of an enforced key is ignored, including nested local sub-keys the policy does not mention. Set enforce: false to make the entire managed source advisory.

Agent-Perspective Example

Org policy shapes what any Agent(...) run can do — no code change needed on the developer’s side.

from praisonaiagents import Agent

# Org policy at /etc/praisonai/config.yaml says:
#   model_allowlist: [gpt-4o]
#   permissions.bash.auto: false

agent = Agent(name="Analyst", instructions="Analyse the sales data.")
agent.start("Summarise Q3 revenue")
# ✓ uses gpt-4o (the only allowed model)
# ✓ bash tools require confirmation (org policy overrides any local `auto: true`)

How to Configure

Three ways to set a managed source. Environment variables override the global managed: block.

export PRAISONAI_MANAGED_CONFIG_URL="https://config.company.internal/praisonai.yaml"
export PRAISONAI_MANAGED_CONFIG_TIMEOUT=3

# ~/.praisonai/config.yaml
managed:
  url: "https://config.company.internal/praisonai.yaml"
  dir: /etc/praisonai/managed
  timeout: 3
  enforce: true       # false → whole managed source is advisory

# Served at PRAISONAI_MANAGED_CONFIG_URL or in the managed directory

# Non-policy defaults — below local config, overridable by any local layer
agent:
  model: org-default-model
  provider: org-provider

permissions:           # policy — enforced above local
  bash:
    auto: false
  allow_shell: false

model_allowlist:       # policy — enforced above local
  - "gpt-4o"
  - "gpt-4o-mini"

Fail-Soft Behaviour

The managed layer never blocks a run on network I/O.

• Short timeout via PRAISONAI_MANAGED_CONFIG_TIMEOUT (default 3 seconds).
• On-disk cache under ~/.praisonai/state/ (honours PRAISONAI_HOME).
• On failure: use the last-good cached copy, else skip the managed layer entirely.
• Only https:// URLs resolving to public IPs are fetched — an SSRF guard blocks http:// (except explicit loopback), private/link-local ranges, and cloud-metadata endpoints (e.g. 169.254.169.254).

Enforcement Semantics

Policy keys are replaced, not merged — a local override of an enforced key is ignored.

# Managed policy
permissions:
  bash:
    auto: false

# Local project .praisonai/config.yaml — ignored for enforced keys
permissions:
  default: allow
  rules:
    - allow-everything

Provenance

resolve_with_provenance labels every resolved key with the layer that set it, so you can see exactly where a value came from.

from praisonai_code.cli.configuration.resolver import ConfigResolver

resolver = ConfigResolver(cwd=".")
provenance = resolver.resolve_with_provenance()

print(provenance["agent.provider"])
# {'value': 'org-provider', 'layer': 'managed:/etc/praisonai/managed/config.yaml',
#  'source': '/etc/praisonai/managed/config.yaml'}

print(provenance["model_allowlist"])
# {'value': ['gpt-4o'], 'layer': 'managed-policy:/etc/praisonai/managed/config.yaml',
#  'source': '/etc/praisonai/managed/config.yaml', 'enforced': True}

print(provenance["agent.temperature"])
# {'value': 0.3, 'layer': 'managed:https://example.com/team.yml',
#  'source': 'https://example.com/team.yml'}

Best Practices

Related