Skip to content

hooks.md

Latest commit

 

History

History
154 lines (119 loc) · 4.03 KB

hooks.md

File metadata and controls

154 lines (119 loc) · 4.03 KB

Lifecycle Hooks

OpenAB supports lifecycle hooks that run custom scripts at specific points during the container lifecycle. Hooks are configured in config.toml under the [hooks] table.

Available Hooks

Hook Timing Use Case
pre_boot Before agent pool creation Bootstrap files, sync from S3, install CLIs
pre_shutdown After pool shutdown, before exit Backup state, sync to S3

Configuration

Each hook supports exactly one script source:

Option A: File path

[hooks.pre_boot]
script = "/etc/openab/pre-boot.sh"
timeout_seconds = 60
on_failure = "abort"

Option B: Inline script

[hooks.pre_boot]
inline = '''
#!/bin/sh
set -e
aws s3 sync "$BOOTSTRAP_URI" "$HOME/"
'''
timeout_seconds = 120
on_failure = "abort"

Option C: Remote URL (with SHA-256 verification)

[hooks.pre_boot]
url = "https://raw.githubusercontent.com/acme/config/main/pre-boot.sh"
sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
timeout_seconds = 60
on_failure = "abort"

Fields

Field Default Description
script — Absolute path to an executable script
inline — Script content (written to temp file and executed)
url — Remote script URL (max 1 MiB)
sha256 — Required with url — hex-encoded SHA-256 of the script
timeout_seconds 60 Max wall-clock time before the script is killed
on_failure "abort" "abort" exits openab; "warn" logs and continues

Validation Rules

  • Exactly one of script, inline, or url must be set
  • url requires sha256
  • script must be an absolute path

Validation runs at startup — config errors are caught before any side effects.

Environment

Scripts run with a sanitized environment:

Always passed:

  • HOME, PATH, USER (unix) / USERPROFILE, USERNAME, SystemRoot, SystemDrive (windows)

Cloud credentials (auto-detected and passed through):

  • AWS_*, AMAZON_*, ECS_CONTAINER_METADATA_URI*
  • GOOGLE_*, GCLOUD_*, CLOUDSDK_*
  • AZURE_*

Bootstrap variables (passed if set):

  • BOOTSTRAP_URI, BOOTSTRAP_BASE_URI, BOOTSTRAP_PERSONAL_URI
  • STATE_BUCKET, TASK_FAMILY

OpenAB identity (passed if set):

  • OPENAB_AGENT_NAME — the agent's configured name
  • OPENAB_BACKEND_AGENT — the backend agent type (e.g. claude, codex)

Note: DISCORD_BOT_TOKEN and other openab secrets are NOT exposed to hook scripts.

Security

  • Temp files are created atomically with 0700 permissions (unix)
  • Remote scripts require SHA-256 verification — openab refuses to execute on mismatch
  • Scripts run as the container's UID (not root, unless the container runs as root)
  • Remote script size is capped at 1 MiB

Examples

Sync config from S3 on startup

[hooks.pre_boot]
timeout_seconds = 120
on_failure = "abort"
inline = '''
#!/bin/sh
set -e
if [ ! -f "$HOME/AGENTS.md" ]; then
  aws s3 sync "$BOOTSTRAP_BASE_URI" "$HOME/"
fi
'''

Backup state on shutdown (ECS Fargate)

[hooks.pre_shutdown]
timeout_seconds = 30
on_failure = "warn"
inline = '''
#!/bin/sh
aws s3 sync "$HOME/" "s3://$STATE_BUCKET/$TASK_FAMILY/" \
  --exclude "aws-cli/*" --exclude "bin/*" --quiet
'''

Conditional OAuth token refresh

[hooks.pre_boot]
script = "/etc/openab/pre-boot.sh"
timeout_seconds = 60
on_failure = "warn"
#!/bin/sh
# /etc/openab/pre-boot.sh
set -e
if [ -f "$HOME/.kiro/auth.json" ]; then
  EXPIRES=$(jq -r '.expires' "$HOME/.kiro/auth.json")
  NOW=$(date +%s)
  if [ "$NOW" -gt "$EXPIRES" ]; then
    kiro-cli auth refresh || true
  fi
fi

Platform Comparison

Option Best for Requires redeploy? Network at boot?
script k8s (ConfigMap mount), EFS, image bake Only if image-baked No
inline ECS, Docker Compose, bare metal Config change only No
url + sha256 Central script repo, multi-cluster No (update sha256 to roll) Yes