#AIO Hooks

AIO Hooks let you run startup commands at defined points in the container lifecycle. They are useful for installing lightweight dependencies, preparing files, or starting companion processes.

#Startup Order

container starts
  -> RUN_HOOK_INIT
  -> runtime user and workspace are prepared
  -> RUN_HOOK_PRE_SERVICES
  -> managed services start
  -> readiness checks pass
  -> RUN_HOOK_POST_READY

#Hooks

#Example

docker run --security-opt seccomp=unconfined --rm -it \
  -p 127.0.0.1:8080:8080 \
  -e RUN_HOOK_PRE_SERVICES="python -m pip install requests" \
  ghcr.io/agent-infra/sandbox:latest

For heavier customization, prefer a custom Docker image so startup remains fast and reproducible.

#Runtime Shutdown Hooks

You can also register shutdown hooks while the sandbox is running. These hooks are useful for flushing state or writing a marker before the sandbox exits. The runtime API currently supports the shutdown event.

curl -X POST "http://localhost:8080/v1/sandbox/hooks" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "write-shutdown-marker",
    "event": "shutdown",
    "command": "printf stopped > /home/gem/workspace/shutdown.txt",
    "timeout": 10,
    "priority": 100
  }'

List registered hooks:

curl "http://localhost:8080/v1/sandbox/hooks?event=shutdown"

Remove an API-registered hook:

curl -X DELETE "http://localhost:8080/v1/sandbox/hooks/write-shutdown-marker"

#Guidelines

• Keep hook commands idempotent.
• Keep secrets out of hook values and image layers.
• Use custom images for large dependencies.
• Use Workspace for mounted project files.