exec

Overview ¶

Package exec is the code interpreter: run a snippet in a sandbox and move files in and out.

It owns FOUR top-level /v1 segments — /v1/exec, /v1/upload, /v1/download and /v1/files — because the upstream client's contract fixes them as siblings (below), so it publishes under four OpenAPI product tags rather than one.

hanzo.chat (LibreChat fork) drives its execute_code agent tool against a code-interpreter API whose contract is fixed by the upstream client (@librechat/agents CodeExecutor): it POSTs {lang, code, files?} to `${LIBRECHAT_CODE_BASEURL}/exec` with header `X-API-Key`, and uses the sibling paths /exec/programmatic, /upload, /download/{id}, /files/{sid}. The response is {session_id, stdout, stderr, files:[{name}]}. cloud-api is the single edge that owns api.hanzo.ai/v1, so this subsystem mounts those paths and forwards each request UNCHANGED to a sandboxed executor upstream. No code runs here — this is a reverse proxy identical in shape to apps/o11y, so there is zero request/response drift from the contract.

SANDBOX: the upstream MUST be an isolated executor (Hanzo Runtime / a per-call container sandbox). This binary NEVER shells out; there is no os/exec anywhere in this package. Point CODE_EXEC_UPSTREAM at the sandbox service's in-cluster DNS. The executor is the isolation boundary; cloud only adds auth + the unified surface.

AUTH: the gateway (order 80) bypasses these paths (the credential is an opaque service key on X-API-Key, not a JWT), so this subsystem enforces the key itself with a constant-time compare against CODE_EXEC_API_KEY (KMS-sourced, synced into the pod env). Endpoints are never open: an unset key fails closed.