Preparation and finalization hooks
Hooks execute repeatable actions inside the sandbox before or after the agent works. Supply executable script text with a shebang in configuration.hooks.
| Hook | When it runs | Example |
|---|---|---|
after_create | After preparing the workspace | Create directories |
before_run | Before every assignment | Download data and record the output path |
after_run | After confirmed agent completion, before sandbox pause or deletion | Send a finished file |
json
{
"before_run": "#!/bin/sh\nset -eu\nmkdir -p replies\n",
"timeout_seconds": 120
}Check agent status before publishing. after_run can also follow an unsuccessful agent outcome. Use ORPHEUS_AGENT_STATUS and ORPHEUS_STOP_REASON. A hook does not replace external delivery tracking when the sandbox is lost or execution cannot be confirmed.
Use ORPHEUS_SESSION_ID, ORPHEUS_RUN_ID and ORPHEUS_HOOK_OPERATION_ID to associate results with work. A delivery retry must check whether the result was already published.
timeout_seconds limits each hook independently. Run details show hook output and errors. before_remove is not executed. Do not use it for cleanup.