Sandbox Variables
This page lists all SANDBOX_* variables used by the sandbox sidecar and its session containers. They only affect the sandbox process; after changing them, restart the sandbox service. SANDBOX_BASE_URL and SANDBOX_API_KEY are the application-side connection variables for accessing the sandbox and are already described in the Environment Variables Overview; they are listed here as well for easy cross-checking.
For deployment and operating procedures, start with the Python Sandbox Guide. For the sidecar's HTTP contract, see the Sandbox API Reference.
The official Full edition starts the built-in sidecar by default. The Personal edition does not start it by default; Python is only available after enabling --profile sandbox or configuring an external sandbox. The sidecar drives the host Docker socket and has high privileges; do not publish its ports, do not disable authentication, and do not endlessly raise resource limits to fix timeouts.
Configuration layers
| Layer | Common variables | Purpose |
|---|---|---|
| Application to sidecar | SANDBOX_BASE_URL, SANDBOX_API_KEY | Determine whether Aivory can advertise and call Python tools |
| Sidecar control plane | SANDBOX_IMAGE, authentication, concurrency, queue, Docker timeouts | Create, reuse, and reclaim session containers |
| Single session container | CPU, memory, PID, read-only root, tmpfs, seccomp, file limits | Limit the resources and system capabilities of untrusted code |
| Workspace archiving | Local directory, object storage timeouts, archive size and TTL | Control the persistent workspace after session reclamation |
The totals of SANDBOX_MEMORY, SANDBOX_CPUS, SANDBOX_MAX_SESSIONS, and SANDBOX_WORKSPACE_SIZE must not exceed what the host can sustain. Do not budget only by the per-session allowance; also leave headroom for the sidecar, application, database, image pulls, and peak concurrency.
Connection, image, and authentication
| Variable | Default | Purpose and values | Security notes |
|---|---|---|---|
SANDBOX_BASE_URL | Empty | Base URL the application uses to request the sidecar. The Personal edition local profile uses http://sandbox:8000; the official Full edition pins the internal address. | Should not point to an unauthenticated public-internet service. |
SANDBOX_API_KEY | Empty | Sidecar Bearer key; the application and sidecar must match. The official Compose provides an internal value; external sandboxes must set their own strong random value. | Secret; a leak can become an execution entry point. |
SANDBOX_IMAGE | aivory-sandbox:latest | Runtime image the sidecar starts for each execution session. The official Compose replaces it with the released image. | Point only at controlled images; avoid untrusted images. |
SANDBOX_PULL_ON_START | Off | Pre-pull the runtime image at startup when set to 1/true. The official Compose enables it. | Can reduce first-execution timeouts, but increases startup time and outbound traffic. |
SANDBOX_ALLOW_NO_AUTH | 0 | Allows the sidecar to start without an API key only when true. | Trusted local development only; must stay off in production. |
SANDBOX_DOCKER_CALL_TIMEOUT_S | 30 | Default timeout for Docker control calls such as inspect and version, in seconds. | Too high delays failure surfacing. |
SANDBOX_ARCHIVE_TIMEOUT_S | 120 | Total time budget when packaging a workspace archive, in seconds. | Too high holds session reclamation locks. |
SANDBOX_IDLE_REAPER_SWEEP_INTERVAL | 300 | Interval for scanning and reclaiming idle sessions, in seconds. | Shorter reclaims resources faster; longer increases idle occupancy. |
Session resources and isolation
| Variable | Default | Purpose and values | Security notes |
|---|---|---|---|
SANDBOX_MEMORY | 2g | Memory limit per session container, using Docker size format. | Reserve total memory by the maximum concurrency. |
SANDBOX_CPUS | 1 | CPUs or Docker CPU quota available to each session container. | Do not allocate all host CPUs to a single session. |
SANDBOX_PIDS_LIMIT | 256 | Processes allowed per session container. | Keep the limit to mitigate fork bombs. |
SANDBOX_NOFILE_ULIMIT | 1024:1024 | Soft/hard limits on container open file descriptors. | Assess file and socket abuse before raising. |
SANDBOX_READ_ONLY_ROOTFS | 1 | Read-only session root filesystem; 0 disables it. | Keep it enabled in production. |
SANDBOX_TMPFS_SIZE | 256m | Writable tmpfs size for /tmp and the user directory in read-only root mode. | Affects available temp space and memory usage. |
SANDBOX_WORKSPACE_SIZE | 512m | Writable tmpfs size for the session /workspace. | Plan together with the archive limit and the file upload limit. |
SANDBOX_WORKSPACE_TMPFS_SIZE | 512m | Legacy compatibility alias; only takes effect when SANDBOX_WORKSPACE_SIZE is unset. | New deployments should use the official variable. |
SANDBOX_DISK_SIZE | Empty | Optional container writable-layer size limit; requires host Docker storage driver support. | Falls back on a best-effort basis when unsupported; it cannot replace the read-only root. |
SANDBOX_SECCOMP_PROFILE | Empty | Path to a seccomp profile readable inside the sidecar. | Only use reviewed local read-only profiles. |
Execution, concurrency, and reclamation
| Variable | Default | Purpose and values | Operational notes |
|---|---|---|---|
SANDBOX_EXEC_TIMEOUT_CAP_MS | 600000 | Hard cap for a single execution, in milliseconds; the backend per-run timeout cannot exceed it. | Lowering it reduces resource risk. |
SANDBOX_DEFAULT_EXEC_TIMEOUT_MS | 120000 | Default timeout when the caller provides no execution duration, in milliseconds. | Should not default to the hard cap. |
SANDBOX_IDLE_TTL_SECONDS | 1800 | Idle reclamation duration when no session-level TTL is specified, in seconds. | Shorter releases resources faster; longer retains more workspaces. |
SANDBOX_IDLE_TTL_CAP_SECONDS | 86400 | Hard cap for the session-level idle TTL issued by the admin backend, in seconds. | Administrators cannot exceed this operational boundary. |
SANDBOX_MAX_SESSIONS | 16 | Number of active sandbox session containers that can exist simultaneously. The official Personal edition profile overrides it to 4 by default. | Correlates with memory, CPU, and Docker socket load. |
SANDBOX_MAX_CONCURRENT_EXECS | 4 | Maximum total concurrent /exec executions across all sessions. | Raising it amplifies CPU, memory, and image/file pressure. |
SANDBOX_MAX_CONCURRENT_CREATES | 2 | Maximum number of session containers created at the same time. | Conservative values prevent Docker daemon spikes. |
SANDBOX_QUEUE_TIMEOUT_SECONDS | 150 | Longest a request waits for an internal execution or creation slot, in seconds. | Timeouts should return diagnosable errors rather than queueing indefinitely. |
Request, code, and artifact limits
| Variable | Default | Purpose and values | Operational notes |
|---|---|---|---|
SANDBOX_MAX_BODY_BYTES | 58720256 | Maximum bytes read for /exec and file request bodies, about 56 MiB, including base64/JSON overhead. | Should exceed the encoded size of the raw upload file limit. |
SANDBOX_MAX_STORAGE_BODY_BYTES | 314572800 | Maximum bytes for /storage/put request bodies, about 300 MiB. | Document archives need more room; must still match proxy limits. |
SANDBOX_MAX_CODE_BYTES | 1048576 | Maximum bytes for the source code field of a single /exec, default 1 MiB. | Keep the cap to avoid control-plane memory pressure. |
SANDBOX_MAX_UPLOAD_BYTES | 41943040 | Maximum decoded bytes for a single input file, default 40 MiB. | Coordinate with application upload, staging, and body limits. |
SANDBOX_MAX_OUTPUT_BYTES | 32768 | Total-byte truncation cap for stdout/stderr returned to the model. | Prevents unbounded printing from consuming memory and context. |
SANDBOX_MAX_ARTIFACT_BYTES | 20971520 | Maximum bytes for a single generated artifact, default 20 MiB. | Large files should use controlled storage rather than direct responses. |
SANDBOX_MAX_FILES_PER_EXEC | 20 | Maximum number of artifact files returned per execution. | Limits bulk file abuse. |
SANDBOX_MAX_TOTAL_ARTIFACT_BYTES | 52428800 | Maximum total size of artifacts returned per execution, default 50 MiB. | Takes effect together with the per-file limit. |
SANDBOX_MAX_COLLECT_SECONDS | 60 | Total time budget for collecting execution artifacts, in seconds. | Too high stretches user requests and holds execution slots. |
SANDBOX_COLLECT_FILE_TIMEOUT_S | 30 | Timeout for collecting a single artifact file, in seconds. | Too low may lose large files; too high increases stuck risk. |
Workspace archiving and object storage
| Variable | Default | Purpose and values | Security notes |
|---|---|---|---|
SANDBOX_LOCAL_STORAGE_DIR | Empty | Local workspace archive directory. Once set, it must be on a mounted persistent volume; if empty, local archiving has no effect. | Single node only; the path may only be set by operators. |
SANDBOX_MAX_ARCHIVE_BYTES | 209715200 | Maximum size of the workspace tar that can be archived on reclamation or deletion, default 200 MiB. | Oversized archives are skipped; state this clearly in user documentation. |
SANDBOX_STORAGE_DEFAULT_TTL | 3600 | Default validity of presigned read URLs when /storage/put does not specify one, in seconds. | Keep it short; avoid long-lived public access. |
SANDBOX_STORAGE_MAX_TTL | 86400 | Hard cap for presigned read URLs, in seconds. | Do not raise it beyond what the business requires. |
SANDBOX_S3_MAX_ATTEMPTS | 3 | Maximum retries for a single S3 SDK operation. | Too high amplifies outages into queueing. |
SANDBOX_S3_CONNECT_TIMEOUT_S | 10 | S3 connection timeout, in seconds. | Coordinate with private network/cross-region latency. |
SANDBOX_S3_READ_TIMEOUT_S | 120 | S3 read timeout, in seconds. | For large objects, also check the total body limit. |
SANDBOX_OSS_CONNECT_TIMEOUT_S | 30 | OSS client connection timeout, in seconds. | Only use controlled endpoints. |
Other runtime variables
| Variable | Default | Purpose and values | Notes |
|---|---|---|---|
MPLCONFIGDIR | Not set | Matplotlib config cache directory. | Usually no need to set; if set, it should point to a writable, restricted directory inside the session and never to sensitive host paths. |
On the application side there are also AIVORY_SANDBOX_MAX_SANDBOX_RESP_BYTES, AIVORY_SANDBOX_EXEC_CLIENT_OVERHEAD, and AIVORY_SANDBOX_SANDBOX_ERROR_BODY_READ_CAP, which limit the size and duration of sidecar responses handled by the API; see Advanced runtime variables.