{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://docs.aetherfy.com/aetherfy-yaml.schema.json",
  "title": "aetherfy.yaml",
  "description": "Configuration for an Aetherfy agent. Every deploy applies the whole file: a field you omit takes its default, never the value the agent had before, and an explicit null is the same as omitting it (nullable fields only). A field not listed here, at any depth, fails the deploy with \"unknown field `<path>`\", plus \", did you mean `<field>`?\" when an accepted field is close.",
  "type": "object",
  "required": [
    "runtime"
  ],
  "additionalProperties": false,
  "properties": {
    "runtime": {
      "type": "string",
      "enum": [
        "python3.11",
        "python3.12",
        "python3.13",
        "python3.14",
        "python3.15",
        "node22",
        "node24",
        "node26",
        "node22-ts",
        "node24-ts",
        "node26-ts",
        "bun",
        "dockerfile"
      ],
      "description": "Execution runtime. Immutable after the agent is created — a changed runtime is rejected with RUNTIME_IMMUTABLE. Note \"python\" alone is not valid; pick an explicit version."
    },
    "type": {
      "type": "string",
      "enum": [
        "service",
        "job"
      ],
      "default": "service",
      "description": "service = a long-lived HTTP server. job = runs once and exits. Either can carry a schedule: a job run executes the entrypoint, a service run is a POST /aetherfy/run request."
    },
    "regions": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string",
        "enum": [
          "us-east-1",
          "eu-central-1",
          "ap-southeast-1"
        ]
      },
      "default": null,
      "description": "Regions to deploy into, within the agent's workspace's regions and bounded by your plan: Free and Starter allow one; Performance allows up to 3. Omit to deploy into the workspace's regions, capped at your plan's limit. Not stored on the agent — it applies per deployment."
    },
    "memory_mb": {
      "type": "integer",
      "enum": [
        256,
        512,
        1024,
        2048,
        4096,
        8192
      ],
      "default": 256,
      "description": "Memory per machine. Also bounded by your plan maximum. An explicit null is rejected."
    },
    "idle_timeout_minutes": {
      "type": "integer",
      "minimum": 1,
      "default": 5,
      "description": "Minutes of inactivity before a service agent sleeps. At least 1; an explicit null is rejected. The maximum is your plan's (Free 5, Starter 15, Performance 30, Enterprise unlimited), checked on every deploy exactly as on create and update, and only where the timeout takes effect: a service with keep_alive off. A job or an always-on service never sleeps, so its value is never refused; making it take effect (type: service, or keep_alive: false) with a value above the maximum fails the deploy with PLAN_LIMIT_EXCEEDED, detail.limit max_idle_timeout_minutes, and nothing in the file is applied."
    },
    "drain_timeout_minutes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 240,
      "default": 30,
      "description": "Minutes a replaced version of a service keeps running to let its open calls end, counted from the redeploy. At the maximum a call that comes through the agent's address is closed with code 1012 and the process is stopped. The ceiling, 240 (4 hours), is the same on every plan and for always-on agents. An explicit null is rejected. Rejected on type: job, at any value."
    },
    "keep_alive": {
      "type": "boolean",
      "default": false,
      "description": "Always-on mode. Requires a plan that allows it, and counts as usage. An explicit null is rejected."
    },
    "entrypoint": {
      "type": [
        "string",
        "null"
      ],
      "default": null,
      "description": "File to execute. Defaults by runtime: python3.11, python3.12, python3.13, python3.14, python3.15 -> main.py; node22, node24, node26 -> index.js; node22-ts, node24-ts, node26-ts -> index.ts; bun -> main.ts. The file must exist in the uploaded archive."
    },
    "schedule": {
      "type": [
        "string",
        "null"
      ],
      "default": null,
      "description": "A scheduled task cadence: exactly five whitespace-separated fields (minute hour day-of-month month day-of-week), always interpreted in UTC. Minimum interval is 5 minutes. @-aliases such as @hourly and 6-field seconds syntax are rejected, as is an expression that can never fire. Valid on either type, including an agent other agents spawn. Use null to remove the schedule (which also clears any pause).",
      "examples": [
        "0 3 * * *",
        "*/15 * * * *",
        "30 2 * * 1",
        "15 2 * * 1-5"
      ]
    },
    "spawn": {
      "type": [
        "object",
        "null"
      ],
      "default": null,
      "additionalProperties": false,
      "description": "Agent-to-agent spawning configuration. Off by default; when enabled, the workers are listed explicitly.",
      "properties": {
        "enabled": {
          "type": "boolean",
          "default": false,
          "description": "Whether this agent may spawn runs of other agents. Requires workers: enabled with no workers is refused at deploy with AGENT_SPAWN_WORKERS_REQUIRED."
        },
        "workers": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string"
          },
          "default": null,
          "description": "The agents this agent may spawn, by name, or [\"*\"] for any of your agents. Each name must be a live agent, of either type, at deploy time. \"*\" must be the only entry. Omitted, no workers are listed; an empty list allows no spawns."
        }
      }
    },
    "github_dependencies": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+@[A-Za-z0-9._/-]+$"
      },
      "default": [],
      "description": "Extra GitHub repositories to install, each as owner/repo@ref. Private repositories require the Aetherfy GitHub App to be connected."
    },
    "writable_paths": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^/([^/]+/)*[^/]+$"
      },
      "default": [],
      "description": "Absolute paths your agent must be able to write on a runtime: dockerfile image, beyond what the user your image ends on already owns. The agent runs as an unprivileged user (that user, when it is not root); before it starts, Aetherfy hands exactly these paths (a directory with everything inside it, or a single file) to that user. A path that does not exist is created as a directory. /etc, /run, /proc, /sys, /dev and /aetherfy are not allowed, each path is listed once, and the most it takes is 32. Standard runtimes own their app directory already."
    }
  }
}
