Operator reference: Assets environment

​

Goal

​

Prerequisites

• Operator access to the existing private platform environment.
• Known storage and edge configuration; the platform Compose file.

​

Workflow

​

Scope and secret handling

​

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.

​

3D rendering configuration

• ASSETS_RENDER_CLOUD_NAME — Server-side 3D processing account namespace. Template: (empty).
• ASSETS_RENDER_API_KEY — Server-side 3D processing key; must be supplied together with the account namespace and secret. Template: (empty).
• ASSETS_RENDER_API_SECRET — Server-only 3D processing secret. Keep it available until outstanding cleanup is reconciled. Template: (empty).
• ASSETS_3D_RELEASE_MODE — New-work admission: disabled, allowlist, or all. Start with disabled. ASSETS_3D_ALLOWLIST_SPACES lists canary space UUIDs when mode is allowlist. Delivery and cleanup continue while admission is disabled.

​

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

​

Configuration validation commands

./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

​

Common failures

​

Related guides