> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Jobs agent_file Root

> Keep Jobs API agent_file paths inside a trusted directory with PRAISONAI_JOBS_AGENT_ROOT

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# ./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 points
```

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai 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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    Req[📤 POST /runs<br/>agent_file] --> Resolve[🔍 Resolve path<br/>symlinks + ..]
    Resolve --> Check{📁 Inside root?}
    Check -->|Yes| Run[🤖 Job queued]
    Check -->|No| Reject[⛔ 400]

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef warn fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef ok fill:#10B981,stroke:#7C90A0,color:#fff
    class Req input
    class Resolve tool
    class Check warn
    class Run ok
    class Reject agent
```

## Quick Start

**1. Start the server next to your YAML**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
cd /srv/praisonai/agents
praisonai serve jobs --port 8005
```

Any `agent_file` under `/srv/praisonai/agents` is accepted.

**2. Or set an explicit root**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

> [!NOTE]
>
> Requests without `agent_file` (for example inline `agent_yaml` or a `recipe_name`) are not affected.

> [!WARNING]
>
> Before this default, an unset `PRAISONAI_JOBS_AGENT_ROOT` meant **no sandbox** — any path was accepted. If you relied on that, set `PRAISONAI_JOBS_AGENT_ROOT` explicitly to the directory you need.

***

## Best Practices

> [accordion] 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 `/`.

> [accordion] 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.

> [accordion] 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.

***

## Related

> [card] [Async Jobs](https://praison.ai/docs/features/async-jobs.md)
>
> Submit and manage long-running jobs

> [card] [Headless YAML Runs](https://praison.ai/docs/features/headless-yaml-runs.md)
>
> Run YAML agents without a UI

> [card] [Protected Paths](https://praison.ai/docs/features/protected-paths.md)
>
> Block tools from sensitive files

> [card] [Security Environment Variables](https://praison.ai/docs/features/security-environment-variables.md)
>
> All security-related env vars


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.