Jobs agent_file Root
Keep Jobs API agent_file paths inside a trusted directory with PRAISONAI_JOBS_AGENT_ROOT
# ./agents.yaml — lives in the directory you start the jobs server from
framework: praisonai
topic: Research
roles:
researcher:
role: Researcher
goal: Summarise {topic}
backstory: You write short, clear summaries.
tasks:
summarise:
description: Summarise the latest news about {topic}
expected_output: Three bullet pointspraisonai serve jobs --port 8005
# ✅ Accepted — resolves under the server's working directory
curl -X POST http://127.0.0.1:8005/api/v1/runs \
-H "Content-Type: application/json" \
-d '{"prompt": "AI agents", "agent_file": "agents.yaml"}'
# ❌ 400 — outside the root
curl -X POST http://127.0.0.1:8005/api/v1/runs \
-H "Content-Type: application/json" \
-d '{"prompt": "x", "agent_file": "/etc/passwd"}'The Jobs API only loads agent_file paths under a trusted root — the server’s working directory by default.
Quick Start
- Start the server next to your YAML
bash cd /srv/praisonai/agents praisonai serve jobs --port 8005Any
agent_fileunder/srv/praisonai/agentsis accepted. - Or set an explicit root
bash export PRAISONAI_JOBS_AGENT_ROOT=/srv/praisonai/agents praisonai serve jobs --port 8005 curl -X POST http://127.0.0.1:8005/api/v1/runs \ -H "Content-Type: application/json" \ -d '{"prompt": "AI agents", "agent_file": "/srv/praisonai/agents/agents.yaml"}'Relative paths still resolve against the server’s working directory, so send absolute paths when the root differs from it.
How It Works
| Step | What happens |
|---|---|
| Resolve | agent_file is made absolute (relative paths against the server’s working directory, not the root) and symlinks are resolved |
| Confine | The resolved path must equal the root or sit below it |
| Accept / reject | Inside → job is queued. Outside → 400 with agent_file must be within PRAISONAI_JOBS_AGENT_ROOT (<root>) |
Configuration
| Env var | Default | Effect |
|---|---|---|
PRAISONAI_JOBS_AGENT_ROOT | server’s current working directory | Directory every submitted agent_file must resolve under. Set it to widen or narrow the scope. |
What returns 400
- Absolute paths outside the root, e.g.
/etc/passwd - Relative escapes, e.g.
../outside.yaml - Symlinks inside the root that point outside it
Best Practices
Use a dedicated agents directory
Keep YAML files in one folder and point PRAISONAI_JOBS_AGENT_ROOT at it, rather than widening the root to /.
Set an API key on shared hosts
Without PRAISONAI_JOBS_API_KEY, the server logs a startup warning that any local process can submit jobs. Set the key whenever other users or services share the host.
Start the server from a known directory
The default root is the working directory at request time, so launch the server from your agents folder (or set the env var) in systemd units and containers.