bluefox-yml 0.1.0

Parser and validator for bluefox.yml app manifests

bluefox-yml

Parser and validator for bluefox.yml app manifests.

Define your application's compute, data, and in-memory primitives in a single YAML file. bluefox-yml validates the manifest and provides typed access to every field.

Part of the Bluefox Stack.

Documentation · PyPI

---

Install

uv add bluefox-yml

---

Quick start

Create a bluefox.yml in your project root:

version: 1
name: my-saas

compute:
  app:
    port: 8000
  worker: {}

data:
  engine: postgres
  version: 17
  migrate: "uv run alembic upgrade head"

Load and validate it:

from bluefox_yml import load_manifest

manifest = load_manifest("bluefox.yml")

print(manifest.name)                    # "my-saas"
print(manifest.compute["app"].port)     # 8000
print(manifest.data.engine)             # "postgres"
print(manifest.routable_process())      # ("app", ComputeProcess(...))

---

What it does

• Schema validation — catches invalid manifests early with clear error messages.
• DNS-safe names — enforces lowercase, alphanumeric, hyphenated names (3-63 chars).
• Engine constraints — only allows supported engines (postgres, redis in v1).
• Single routable process — ensures at most one compute process declares a port.
• Healthcheck defaults — auto-injects /health for processes with a port.
• Helper methods — service_name(), image_tag(), db_image(), env_vars(), and more.
• Reserved name guard — prevents bluefox-* prefixed names (reserved for platform services).

---

Error handling

from bluefox_yml import load_manifest, format_error, ManifestError

try:
    manifest = load_manifest("bluefox.yml")
except ManifestError as e:
    print(format_error(e))

---

Documentation

Full docs at bluefox-yml.bluefox.software/docs/

• Getting started — install and write your first manifest
• Reference — full API documentation