Skip to content

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.

HookWhen it runsExample
after_createAfter preparing the workspaceCreate directories
before_runBefore every assignmentDownload data and record the output path
after_runAfter confirmed agent completion, before sandbox pause or deletionSend 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.

Hook reference · Helpdesk example