Skip to main content

Filesystem policy and PNG promo export

This page covers two optional features that are installed by the same setup step:

  • a filesystem/exec policy (a YAML file) that controls which files the agent may read or write and which commands it may run in the session sandbox;
  • Playwright (a headless browser) for the promo_render MCP server, which turns React/HTML designs into PNG images.

It is for administrators and IT staff who run the setup and upgrade scripts. MCP (Model Context Protocol) servers are the plug-in tool providers the agent calls.

What the scripts do​

ScriptRole
scripts/runtime_extras_setup.pyCopies fs_policy template to config/, appends promo keys to .env, optional dev policy activation, installs Playwright
scripts/setup_promo_playwright.shpip install playwright + playwright install chromium on the backend Python (.venv or mcp_servers/promo_render/.venv)
scripts/setup-aion-env.shEnv wizard + --prepare-runtime → invokes setup_core → runtime extras
scripts/upgrade-aion.shLocal upgrade or --docker → upgrade_core → runtime extras after sync_config / sync_mcp_servers

Useful commands​

# Initial setup (venv + sync + Playwright promo, if not skipped)
./scripts/setup-aion-env.sh

# Only runtime extras (dry-run)
python3 scripts/runtime_extras_setup.py --dry-run

# Enable sandbox exec (local dev only)
./scripts/setup-aion-env.sh --enable-fs-policy-dev
# or
./scripts/upgrade-aion.sh --enable-fs-policy-dev

# Skip Chromium download (~150 MB)
./scripts/upgrade-aion.sh --skip-promo-playwright

After changes to AION_FS_POLICY_PATH or Playwright installation: restart the backend (./scripts/dev-api.sh or backend container).


Filesystem policy (AION_FS_POLICY_PATH)​

Default​

If AION_FS_POLICY_PATH is empty, the runtime uses the in-code policy (src/runtime/agent_fs_policy.py): generally exec.enabled=false. The sandbox_exec_allowlisted tool remains disabled until you point to a YAML with exec.enabled: true.

Templates in config_std/​

FileUsage
fs_policy.example.yamlCommented example for production
fs_policy.dev.yamlDev: exec.enabled: true with minimal allowlist (grep, wc, sort)

runtime_extras_setup copies templates to config/ if missing (idempotent).

Dev activation (--enable-fs-policy-dev)​

  1. Copies config/fs_policy.dev.yaml → config/fs_policy.yaml
  2. Adds to .env: AION_FS_POLICY_PATH=config/fs_policy.yaml (only if the key does not exist)

Mandatory: without AION_FS_POLICY_PATH in .env, the backend ignores config/fs_policy.yaml and remains exec.enabled=false (error exec_disabled).

For production: start from fs_policy.example.yaml, adapt allowlist and paths, do not use the dev file without security review.

Dev allowlist (fs_policy.dev.yaml)​

CategoryExecutables
Python office/docxpython, python3 — only scripts under scripts/, workspace/, uploads/, derived/ (no -c / -m)

| Text | grep, wc, sort, head, tail, cat, cut, tr, uniq, file | | File system | find, ls, du, cp, mv, mkdir, touch, zip, unzip | | Documents | pandoc, pdftoppm |

Not included (by design): bash, sh, curl, wget, pip, npm (use sandbox_install_* / sandbox_run_*_file).

Promo PNG and exec​

PNG export does not use sandbox_exec: it uses Playwright in the promo_render MCP process. The exec policy is used for other workflows (grep on workspace, allowlisted Python scripts under scripts/ after skill_view — see Skill and system prompt).


Promo render MCP (Playwright)​

See also Promo Render MCP.

Variables​

VariableTypical defaultDescription
AION_PROMO_CAPTURE_ENABLED10 disables capture
AION_PROMO_CAPTURE_TIMEOUT_MS(optional)Capture timeout

Automatic append from setup/upgrade if absent in .env.

Correct Python​

Playwright must be installed on the same interpreter that starts the backend/MCP, not on the chat session venv. setup_promo_playwright.sh tries in order:

  1. .venv/bin/python
  2. mcp_servers/promo_render/.venv/bin/python
  3. system python3

Verify in chat (Graphic Designer profile): tool promo_check_environment → "ok": true.


Docker Compose​

  • ./scripts/setup-aion-env.sh --docker only copies .env.docker.example; it does not create a local venv nor install Playwright on the host.
  • ./scripts/upgrade-aion.sh --docker still runs runtime_extras_setup on the host (config/ templates, .env keys), but Chromium must be installed in the backend image if promo in container is needed.

One-off example in the backend container (after docker compose up):

docker compose exec backend bash -c \
'python -m pip install "playwright>=1.49.0" && python -m playwright install --with-deps chromium'

For persistent production, extend docker/Dockerfile.backend with the same commands in the runtime stage (including the installation of system dependencies).


Code references​

  • Policy loader: src/runtime/agent_fs_policy.py
  • Capture: src/tools/promo_capture.py
  • MCP: mcp_servers_std/promo_render/
  • Recommended profile: config_std/profiles/graphic_designer.yaml