> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# Operator reference: Assets environment
> Every Assets environment variable, its preparation default, secret boundary, runtime destination, and activation prerequisite.
## Goal
Configure storage, processing, rendering and delivery settings while preserving existing media and signing identity.
## Prerequisites
* Operator access to the existing private platform environment.
* Known storage and edge configuration; the platform Compose file.
## Workflow
Inventory the deployed environment and runtime values without printing secrets.
Preserve existing values and populate missing settings from verified configuration or documented defaults.
Select the spaces and output types that the installation should enable.
Validate both the environment and the rendered Compose configuration before the coordinated deployment.
## Scope and secret handling
This reference accounts for all 59 ASSETS\_\* application configuration keys in the current release plus the Compose scratch setting. Additional shared dependencies such as DATABASE\_URL, Redis/durable-job configuration, JWT\_SECRET and optional OPENAI\_API\_KEY belong to the complete platform environment and must be preserved.
Use deployments/assets/.env.example as an overlay into the complete private platform environment. Do not replace the platform environment with the Assets template. Store operational values outside Git with owner-only permissions; never place credentials in frontend environment variables or Docker build arguments.
The values below are template defaults. Preserve existing working storage and signing values. Cloudinary rendering enables from the installation’s existing credentials without extra credit budgets or launch allowlists.
## Storage and origin delivery
* `ASSETS_BASE_PATH` — Container path for Assets work/storage mounts; production Compose fixes this to /var/lib/stackshift/assets. Do not move existing storage by editing this value. Template: `/var/lib/stackshift/assets`.
* `ASSETS_MANAGED_STORAGE_BACKEND` — Production preparation requires the existing object backend. Generic application/Compose fallback is local; retain the deployed backend explicitly. Template: `object`.
* `ASSETS_MANAGED_OBJECT_ENDPOINT` — Existing S3-compatible endpoint. Use the actual configured private/public storage service; do not substitute Cloudinary. Template: `(empty)`.
* `ASSETS_MANAGED_OBJECT_REGION` — Existing object-store signing region. Template: `(empty)`.
* `ASSETS_MANAGED_OBJECT_BUCKET` — Existing Assets bucket, not a new bucket created by this guide. Template: `(empty)`.
* `ASSETS_MANAGED_OBJECT_ACCESS_KEY_ID` — Server-only credential for the existing object store. Template: `(empty)`.
* `ASSETS_MANAGED_OBJECT_SECRET_ACCESS_KEY` — Server-only object-store secret; preserve or rotate through the storage owner. Template: `(empty)`.
* `ASSETS_MANAGED_OBJECT_PREFIX` — Existing object key prefix. Changing it is not a migration. Template: `assets`.
* `ASSETS_MANAGED_OBJECT_PATH_STYLE` — Whether S3 requests use path-style addressing; preserve provider compatibility. Template: `true`.
* `ASSETS_CDN_BASE_URL` — HTTPS customer-facing Assets delivery origin. Template: `https://cdn.stackshift.cloud`.
* `ASSETS_ORIGIN_BASE_URL` — HTTPS API Assets origin behind delivery authorization. Template: `https://api.stackshift.cloud`.
* `ASSETS_EDGE_ORIGIN_TOKEN` — Existing shared edge-to-origin credential; match the Worker ASSETS\_ORIGIN\_TOKEN (legacy ASSETS\_EDGE\_ORIGIN\_TOKEN also supported). Template: `(empty)`.
* `ASSETS_TRANSFORM_SIGNING_SECRET` — Existing signing key; when previously unset it falls back to JWT\_SECRET. Preserve that exact identity and match Worker ASSET\_SIGNING\_SECRET. Template: `(empty)`.
* `ASSETS_REGION` — Logical Assets region; not an instruction to provision replicas. Template: `global`.
* `ASSETS_REPLICATION_FACTOR` — Preserve the actual deployment target. Production Compose defaults to one; setting three does not provision three replicas. Template: `1`.
## Processing and bounded resource controls
* `ASSETS_MAX_UPLOAD_BYTES` — Maximum configured upload bytes, 524288000 by default; bucket/content policies can impose smaller limits. Template: `524288000`.
* `ASSETS_MAX_TRANSFORMATION_WIDTH` — Default maximum derived width in pixels. Template: `4096`.
* `ASSETS_MAX_TRANSFORMATION_HEIGHT` — Default maximum derived height in pixels. Template: `4096`.
* `ASSETS_MAX_DERIVED_ASSETS_PER_ASSET` — Default derived-output count limit for one asset. Template: `50`.
* `ASSETS_MAX_DERIVED_ASSETS_PER_ACCOUNT` — Default account derived-output count limit. Template: `5000`.
* `ASSETS_PROVIDER_CONCURRENCY` — External-provider concurrency; default two. This is not native video encode concurrency. Template: `2`.
* `ASSETS_OCR_CONCURRENCY` — OCR concurrency; default two. Template: `2`.
* `ASSETS_SCRATCH_SIZE` — Compose tmpfs size; the configured size is 8g. It is not an application feature switch. Template: `8g`.
* `ASSETS_FFMPEG_PATH` — FFmpeg executable in the worker image. Template: `ffmpeg`.
* `ASSETS_FFPROBE_PATH` — FFprobe executable in the worker image. Template: `ffprobe`.
* `ASSETS_CLAMAV_ADDRESS` — Native scanner service and port on the platform network. Template: `clamav:3310`.
* `ASSETS_NATIVE_VIDEO_ADMISSION` — New native encode admission is enabled by default; an explicit false preserves delivery of existing packages. Template: `true`.
* `ASSETS_VIDEO_PROFILES` — Comma-separated name:height:video-bitrate:audio-bitrate ladder; retain H.264/AAC and the configured recipe. Template: `240p:240:400k:64k,360p:360:800k:96k,480p:480:1400k:128k,720p:720:2800k:128k,1080p:1080:5000k:192k`.
* `ASSETS_MODEL_PROCESSOR_IMAGE` — Isolated validation image reference; empty and not projected into production services by this release. Template: `(empty)`.
* `ASSETS_MODEL_PILOT_SPACES` — Isolated model-validation allowlist; empty and not projected into production services. Template: `(empty)`.
* `ASSETS_MODEL_DAILY_JOBS` — Default native model-pilot daily admission limit; does not enable the pilot. Template: `20`.
## Cloudflare control-plane configuration
* `ASSETS_CLOUDFLARE_ZONE_ID` — Actual Cloudflare zone containing the Assets domain; verify the zone before reusing a platform identifier. Template: `(empty)`.
* `ASSETS_CLOUDFLARE_ACCOUNT_ID` — Cloudflare account that owns the existing Assets Worker. Template: `(empty)`.
* `ASSETS_CLOUDFLARE_WORKER_SERVICE` — Actual deployed Worker name. The checked-in edge example is stackshift-assets-gateway; do not create a duplicate service. Template: `stackshift-assets-gateway`.
* `ASSETS_CLOUDFLARE_API_TOKEN` — Server-only token with the permissions needed by Assets zone/cache/custom-domain operations. Grant the specific zone/cache/custom-domain permissions used by your installation. Template: `(empty)`.
* `ASSETS_CLOUDFLARE_API_BASE_URL` — Cloudflare API base. Retain the official HTTPS endpoint in production. Template: `https://api.cloudflare.com/client/v4`.
## Cloudinary rendering configuration
* `ASSETS_RENDER_CLOUD_NAME` — Cloudinary account/product-environment namespace. Server-side only; use the Cloudinary product environment configured for 3D rendering. Template: `(empty)`.
* `ASSETS_RENDER_API_KEY` — Existing authorized Cloudinary API key; must be supplied together with cloud name and secret. Template: `(empty)`.
* `ASSETS_RENDER_API_SECRET` — Server-only Cloudinary secret. Keep it available until outstanding provider cleanup is reconciled. Template: `(empty)`.
* The three credentials enable rendering. Cloudinary accounts for its own credits; no extra StackShift provider budget, space allowlist or output activation list is required. Customer permissions and existing plan allowances still apply.
## Existing AI and OCR-adjacent settings
* `ASSETS_AI_PROVIDER` — Existing optional Assets AI provider selection; preserve current production configuration. Template: `openai`.
* `ASSETS_OPENAI_VISION_MODEL` — Model identifier used by opt-in vision analysis; the template default is not an instruction to change an existing deployment. Template: `gpt-5.6-luna`.
* `ASSETS_OPENAI_MODERATION_MODEL` — Existing AI moderation model; native video validation does not require AI video-content approval. Template: `omni-moderation-latest`.
* `ASSETS_OPENAI_TRANSCRIBE_MODEL` — Opt-in transcript model. Uploaded captions do not call automatic transcription. Template: `gpt-4o-transcribe`.
* `ASSETS_OPENAI_IMAGE_EDIT_MODEL` — Existing image-edit model. Template: `gpt-image-2`.
* `ASSETS_AI_EVAL_APPROVED_MODELS` — Comma-separated evaluated model allowlist for existing AI operations; not video human-review approval. Template: `gpt-5,gpt-5.6-luna,omni-moderation-latest,gpt-4o-transcribe,gpt-image-1.5,gpt-image-2`.
* `ASSETS_AI_MAX_IMAGE_BYTES` — Maximum image bytes for existing AI requests. Template: `10485760`.
* `ASSETS_AI_MAX_AUDIO_CHUNK_BYTES` — Maximum audio bytes per existing AI chunk. Template: `25000000`.
* `ASSETS_AI_AUTO_QUARANTINE` — Preserve existing AI policy behavior; not a substitute for native malware scanning. Template: `true`.
* `ASSETS_AI_VISION_INPUT_MICROS_PER_MTOK` — Existing internal cost-model default for vision input, in micro-units per million tokens; not a verified provider price quote. Template: `1000000`.
* `ASSETS_AI_VISION_OUTPUT_MICROS_PER_MTOK` — Existing internal cost-model default for vision output. Template: `6000000`.
* `ASSETS_AI_TRANSCRIBE_INPUT_MICROS_PER_MTOK` — Existing internal cost-model default for transcription input. Template: `2500000`.
* `ASSETS_AI_TRANSCRIBE_OUTPUT_MICROS_PER_MTOK` — Existing internal cost-model default for transcription output. Template: `10000000`.
* `ASSETS_AI_IMAGE_EDIT_MICROS_PER_IMAGE` — Existing internal cost-model default per image edit. Template: `100000`.
## API, worker and edge consistency
The prepared Compose configuration passes the native-video/rendering settings to API and dedicated Assets workers, including green release slots. API-derived backend services inherit API configuration as before. Cloudinary credentials must not be included in frontend/general-worker/Mail-submission environments.
The API/Assets worker slots account for 57 runtime settings. ASSETS\_SCRATCH\_SIZE configures worker tmpfs; the two isolated native-model activation fields remain excluded. Production Assets workers retain two CPUs, four GiB RAM, eight GiB scratch and the existing shared release fence.
Worker ASSET\_SIGNING\_SECRET must match API ASSETS\_TRANSFORM\_SIGNING\_SECRET, and Worker ASSETS\_ORIGIN\_TOKEN must match API ASSETS\_EDGE\_ORIGIN\_TOKEN. ASSETS\_ORIGINS\_JSON maps regions to HTTPS API origins; ASSETS\_COLO\_REGION\_JSON optionally maps colos to those regions. Configure matching values on both sides of each authorization boundary.
## Configuration validation commands
The checker reads a literal dotenv file without sourcing shell code. It rejects nonregular/symlink files, group/world permissions, files over one MiB, duplicate Assets keys, shell expansion and unknown current Assets variables. It checks required storage/delivery inputs, secret lengths, integer bounds and capability relationships without displaying values.
```bash theme={null}
./deploy.sh assets-check --env-file /private/platform.env
# Only require capabilities when activation evidence and values are complete:
./deploy.sh assets-check --env-file /private/platform.env --require-video
./deploy.sh assets-check --env-file /private/platform.env --require-rendering
```
## Expected result
All 60 Assets configuration entries are accounted for, storage/signing identity is preserved, and the selected spaces and media outputs have the intended settings.
## Common failures
* Replacing the complete platform environment with a partial Assets overlay.
* Changing a fallback signing key and unintentionally invalidating current delivery URLs.
* Treating a configured no-overage flag as provider-enforced spending protection.
## Related guides
Configure Assets services, build images, run deployment checks, and roll back processing admission without interrupting existing delivery.
Use model-preview controls, estimate rendering units, request proofs or final media, and publish approved immutable outputs.
Version-pinned video packages, scan and review gates, replacement behavior, playback sessions, API routes, and failure recovery.