# Headless execution A headless run starts an agent non-interactively with a prompt and returns a result, which lets other systems trigger it. > A headless run starts the agent with a prompt and no person at the keyboard. The loop runs to completion and returns a result and an exit status. Source: https://ai-sw-factory.mellicci.dev/fundamentals/headless-execution **Diagram:** A trigger starts the agent with a prompt and configuration; it runs unattended and returns output and an exit code. - Trigger — CI, schedule, webhook - → prompt + config - Headless run — agent loop, no person - → result - Output + exit code — parsed by the next step In interactive use, a person watches the loop and answers questions. In a headless run, the agent is started with a prompt from a script or CI job. It runs to completion, prints its result, and exits. Nobody is available to approve a command, so permissions must be decided before the run starts. Most agents offer a structured output format and meaningful exit codes, so a workflow can parse the outcome and branch on it. Sessions can usually be resumed, which lets a later step continue an earlier run. Headless execution replaces the person at both ends: a trigger supplies the prompt, and a parser reads the output. Because a single run is easy to script, headless runs are often repeated in [Loops](https://ai-sw-factory.mellicci.dev/fundamentals/loops). ## Why it exists An agent that needs a person at every step is an assistant. To turn "label an issue" into "a pull request appears", something other than a person must start the agent, give it the task and consume the result. Without headless runs, every unit of work waits for someone to open a terminal. ## How it works **Diagram:** Nobody is there to ask, so configuration answers for permissions, and the surrounding workflow decides what the result means. - Flag runs once — supplied prompt, no session - → - Config answers — permissions and tools from flags - → - Loop runs — until finished or a limit - → - Answer + exit code — optionally structured output - → - Workflow decides — open PR, retry, alert a person An unattended agent acts on whatever it reads, including issue text written by others. Decide its permissions with care; see the [Security model](https://ai-sw-factory.mellicci.dev/fundamentals/security-model). Run it inside a sandbox too, so a wrong step can only damage a disposable environment; see [Sandboxing & devcontainers](https://ai-sw-factory.mellicci.dev/fundamentals/sandboxing). ## Use it when - Work should start from an event, not from a person. - The result feeds another step, such as a test run or a pull request. - You want repeatable, logged runs. ## Use something else when - You are exploring a problem and need to steer → interactive use; see [How coding agents work](https://ai-sw-factory.mellicci.dev/fundamentals/how-coding-agents-work) - You need the run to be safe without a person → first read the [Security model](https://ai-sw-factory.mellicci.dev/fundamentals/security-model) and [Sandboxing](https://ai-sw-factory.mellicci.dev/fundamentals/sandboxing) - You need checks on every action → [Hooks](https://ai-sw-factory.mellicci.dev/fundamentals/hooks) ## Key terms - **Headless run** — a non-interactive agent invocation. - **Structured output** — machine-readable results. - **Exit code** — the process status callers branch on. - **Trigger** — the event that starts the run.