Hooks and environment variables
Supply each hook as script text with a shebang in configuration.hooks. The working directory is the session workspace. Choose an interpreter installed in the template.
| Variable | Availability | Purpose |
|---|---|---|
ORPHEUS_SESSION_ID | All executed hooks | Session UUID |
ORPHEUS_WORKSPACE_PATH | All executed hooks | Absolute workspace path |
ORPHEUS_HOOK_OPERATION_ID | All executed hooks | Stable hook operation ID |
ORPHEUS_RUN_ID | before_run, after_run | Run UUID |
ORPHEUS_INPUT_FINGERPRINT | before_run, after_run, when supplied | Input snapshot version |
ORPHEUS_AGENT_STATUS | after_run, when known | completed, failed, cancelled |
ORPHEUS_STOP_REASON | after_run, when known | Stop reason |
Run variables do not become agent environment variables. Pass necessary non-secret context through a prepared file or task text.
When names overlap, top-level run env, env_from and services override session values for before_run and after_run. They do not affect after_create or the agent process.
after_create runs after environment creation, before_run before an assignment and after_run after confirmed agent completion. before_remove is not executed.
A nonzero exit code or timeout is recorded as a hook error. The retained stdout/stderr limit does not stop the script. Give network calls a shorter timeout than the overall hook deadline.