Samsar is a generative video and media automation platform for turning prompts, product images, structured content, and creative ideas into finished videos and reusable studio assets. It brings together one-shot text-to-video, image-list-to-video, image editing, audio generation, semantic search, recommendations, assistant workflows, multi-provider model routing, and detailed post-production controls across one integrated Studio and API surface.

• One-shot text-to-video up to 3 minutes for documentary, infotainment, ed-tech, film summary, custom themes, and original ideas.
• One-shot image-list-to-video that turns product images into polished ad videos with optional narrator avatar, outro, and CTA.
• One-click scene re-rolls after render to fix small imperfections without rebuilding the full project.
• Full Studio workspace for detailed, granular post-processing.
• Sandboxed local logging, with logs and traces kept on your machine.
• Multi-provider model routing so each operation can use the best available provider and model.
• OpenRouter-backed Qwen 3.7 orchestration in hosted deployments, with native Alibaba Qwen available only in Docker deployments.
• Built-in search and recommendations for creating a generative video library and Studio knowledge base.

Run the fast, dependency-free test suite:

npm test

Validate the generated runtime files and full Docker Compose deployment configuration:

npm run test:deployment

GitHub Actions runs both checks for pull requests into main and pushes to main.

• Git.
• Node.js 20+ with npm.
• Docker running with the Compose plugin.
• rsync, only when syncing source projects from the parent workspace.

Install Docker from the official Docker docs for your platform:

Confirm Docker is installed and running before starting setup:

docker info
docker compose version

From the parent workspace checkout, enter the Samsar deployable monorepo. If you cloned this repository directly, start from the repository root instead.

cd samsar

Sync source projects only when this repository is being used as the deployable wrapper around sibling source projects. Skip this in a standalone clone.

npm run sync

npm run setup-wizard

The command builds and starts the setup wizard container, prints localhost/private-IP setup URLs, prints a public-IP setup URL only when TCP 8089 responds on that public address, waits for the wizard to respond, and tries to open http://localhost:8089 in the default browser on hosts with desktop browser access. Set SAMSAR_SETUP_OPEN_BROWSER=0 to skip browser auto-open. After you complete the browser flow, the wizard writes deployment config, renders runtime env and model availability, builds and starts the selected Docker Compose profiles, publishes the local media gateway when required, verifies the processor API and Studio client, and prepares local login.

Open the local services after setup completes:

Stop the stack:

npm run docker:down

Use the setup wizard when you want a UI-driven local Docker setup flow. Use the manual runtime/config/samsar.config.json flow when you want direct control over credentials, provider selection, storage URLs, database settings, or mail settings.

The wizard follows five configuration steps:

All provider keys are optional and enable different capabilities. A Samsar API key enables all capabilities and can also be used as a universal fallback with other provider keys.

For Alibaba Cloud, enter the Model Studio API key and, when using a workspace endpoint, its API host or full OpenAI-compatible base URL. The wizard validates the endpoint once before setup, stores the validated credential in runtime/secrets/provider.credentials.json, and renders ALIBABA_API_KEY and ALIBABA_API_HOST only into the backend Docker environment. The key is not retained in browser session storage or written to runtime/config/samsar.config.json.

For OpenRouter, expand the top-level Inference Router section and enter one optional API key. The wizard checks the authenticated key metadata, rejects management-only keys, and binds setup to a short-lived one-time validation token. It does not retain the key or token in browser storage or the general runtime config, and stores the accepted key in the same mode-0600 provider secret file. Runtime rendering exposes it to backend containers only as OPENROUTER_API_KEY. That single key enables the supported GPT 5.6 Sol, Gemini 3.1 Pro, and Qwen 3.7 inference families, including their corresponding vision-input paths.

During setup, the wizard saves deployment config, renders runtime env, starts containers, configures the optional reverse proxy, publishes the local media gateway when required, verifies the processor API and client, and prepares local login. See Setup Wizard for the detailed lifecycle.

Use this path only when you do not want the browser setup wizard to write runtime config for you.

Create a local runtime config:

mkdir -p runtime/config runtime/secrets
cp -n samsar.config.example.json runtime/config/samsar.config.json

Edit runtime/config/samsar.config.json for provider enablement, non-secret provider settings, storage, database, and public URLs. OpenRouter and Alibaba credentials can be kept in runtime/secrets/provider.credentials.json; legacy/manual OpenRouter values under providers.openrouter.apiKey remain supported for compatibility. The stable gemini-3.1-pro selection defaults to OpenRouter model google/gemini-3.1-pro-preview and can be overridden with providers.openrouter.gemini31ProModel. The checked-in example is safe for local Docker defaults: local MongoDB, local MinIO-compatible storage, local media gateway, and no external provider enabled.

Render env files:

npm run config:render

Install Docker-visible fonts and prepare the optional local logger stack:

npm run docker:setup-assets

Start the complete local Docker stack:

npm run docker:up

Provider availability is explicit. npm run config:render reads runtime/config/samsar.config.json and the optional runtime/secrets/provider.credentials.json, writes runtime/secrets/root.env, and generates runtime/config/available-models.json from enabled providers. The video API then filters supported model responses through that generated availability file.

In Docker, direct native provider keys are used first, followed by OpenRouter and then the Samsar fallback. Hosted Qwen routing is stricter: production, external-production, staging, and other non-Docker runtimes always send QWEN3.7 inference through OpenRouter. A saved native or deployed authorization does not override that server-side policy. See Providers and Models.

The built-in inference adapters normalize stable model selections, text and vision payloads, structured output, timeouts, retries, and provider authorization across the processor and inference workers. They are separate from configuration.custom_adapters, which are user-supplied media-operation endpoints for workflows such as text-to-image, image-to-video, speech, music, and sound effects.

The stable QWEN3.7 selection maps OpenRouter text and vision requests to qwen/qwen3.7-plus; OPENROUTER_QWEN_37_PLUS_MODEL can override that mapping. Native Alibaba routing uses qwen3.7-max for text-only inference and qwen3.7-plus for image or video input. OpenRouter requests explicitly use high reasoning for Qwen and Gemini and the native-equivalent xhigh setting for GPT, with a 65,536-token completion allowance. Structured requests also require compatible provider parameters and enable response healing.

The same adapter contract is used by processor, generator, audio-generator, ai-video-layer-generator, express-video-listener, and assistant-query-processor. This keeps provider selection consistent across chat, assistant, prompt generation, vision analysis, and express-video stages.

All routes below are served by the processor API at http://localhost:3002 in local Docker. Auth accepts a Samsar API key, auth token, or app key where supported by the route.

After the setup wizard completes, or after npm run config:render in the manual flow, validate the rendered Compose configuration:

npm run docker:config

npm run docker:up renders runtime/secrets/root.env and runtime/config/available-models.json, then starts the local default profiles. The setup wizard adds the reverse-proxy profile only when nginx access is enabled.

Run npm run docker:setup-assets during manual setup or whenever fonts/logger config need to be refreshed. The script installs subtitle/render fonts into runtime/fonts, copies them into any running Samsar service containers, and recreates Promtail/Grafana only when services.logger is enabled so Docker logs are available in local Grafana.

Persistent Docker state is stored in named volumes:

• mongo-data
• minio-data
• media-assets
• media-assets-v2
• persistent-data
• loki-data
• promtail-data
• grafana-data

To inspect logs:

docker compose -f deploy/compose/docker-compose.yml logs -f processor client

To rebuild and replace only the frontend container:

docker compose -f deploy/compose/docker-compose.yml --profile core build client
docker compose -f deploy/compose/docker-compose.yml --profile core up -d --force-recreate --no-deps client

Avoid restarting generation workers while a video, audio, or sound-effect job is active unless you have confirmed the worker is stuck or the job can safely resume.

In local Docker, completed render URLs are expected to look like:

http://localhost:3002/assets_v2/video/output/<session-id>/<file>.mp4

That browser URL is served by the configured processor API from the mounted media volume. It is not an S3 or CloudFront URL unless external media publishing is enabled in runtime config.

If the setup wizard configures a reverse proxy, browser media URLs use that configured processor API origin. Public/private IP installs use one machine IP: Studio is served at http://<ip> and processor/media URLs use http://<ip>/api. External AI adapters still use the separately managed, validated media tunnel unless external S3/CloudFront publishing is explicitly enabled.

When a remote provider must fetch local-only media from your Docker stack, Samsar needs a public media base URL. The local-media profile includes a Compose-managed Cloudflared controller. It starts a quick tunnel when runtime config enables a remote media consumer, validates the exact media-gateway health marker, atomically publishes localMediaTunnel.publicUrl, and replaces the tunnel when its health checks fail or a worker writes the shared refresh marker. It does not mount the Docker socket and does not depend on the setup-wizard process.

For a manual runtime, start or recreate only the local-media services with:

docker compose --env-file runtime/secrets/root.env \
  -f deploy/compose/docker-compose.yml \
  --profile local-media up -d --build \
  media-gateway media-tunnel-controller

Inspect its lifecycle and the current URL with:

docker compose --env-file runtime/secrets/root.env \
  -f deploy/compose/docker-compose.yml \
  --profile local-media logs -f media-tunnel-controller

Provider workers reload and validate the published URL before each public adapter request. The controller keeps publicUrls.media on the configured processor/reverse-proxy URL, so the temporary tunnel is never used for browser previews.

The legacy scripts/start-local-media-tunnel.sh command remains as a compatibility wrapper; it now starts and waits for these same Compose services instead of creating a second tunnel container.

The main config file is:

runtime/config/samsar.config.json

The example config uses local Docker defaults:

• database.provider: local-mongo
• storage.provider: s3-compatible
• storage.staticCdnUrl: http://localhost:3002/
• storage.externalMediaPublishEnabled: false
• publicUrls.clientApp: http://localhost:3000
• publicUrls.processorApi: http://localhost:3002
• publicUrls.media: http://localhost:3002
• reverseProxy.enabled: false

Provider enablement is configured under providers. Enable only the providers you intend to use, then rerender config:

npm run config:render

For a manual OpenRouter or Alibaba Cloud setup, enable the matching provider in runtime/config/samsar.config.json and create the following mode-0600 secret file. The setup wizard performs these steps automatically after validating the credentials.

{
  "version": 1,
  "openrouter": {
    "apiKey": "<openrouter-api-key>"
  },
  "alibabaCloud": {
    "apiKey": "<alibaba-model-studio-api-key>",
    "apiHost": "https://workspace-id.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
  }
}

Save it as runtime/secrets/provider.credentials.json, then run chmod 600 runtime/secrets/provider.credentials.json before rendering the runtime config.

Generated files:

• runtime/secrets/root.env: env consumed by Docker services.
• runtime/secrets/provider.credentials.json: setup-wizard-managed OpenRouter key plus Alibaba Cloud key and validated endpoint. Keep this file private and mode 0600.
• runtime/config/available-models.json: model/action availability derived from enabled providers.

All API provider keys are optional. Add only the credentials needed for the generative features you want to enable. Common minimal setups are:

• Samsar API key only
• OpenRouter only for GPT, Gemini, and Qwen text/vision inference and assistant workflows
• Alibaba Cloud only for native Qwen 3.7 inference and assistant workflows in Docker
• Alibaba Cloud + Samsar API key for native Qwen with Samsar fallback in Docker
• OpenAI + FAL
• OpenAI + Samsar API key
• Google Cloud service account + FAL

Provider keys can provide direct or routed inference while still using the Samsar media generation pipeline inside your environment. The setup wizard stores OpenRouter and Alibaba Cloud credentials separately in runtime/secrets/provider.credentials.json; npm run config:render then renders them into runtime/secrets/root.env for backend Docker services only. Every backend service inherits that single env file, so one OpenRouter secret is sufficient for processor and inference workers. Do not commit runtime/ or copy keys into browser/client-side code.

External IP access is not enabled by default. Keep the Docker stack on localhost unless you intentionally want public access to your generative server.

The setup wizard can optionally enable nginx for a public domain/subdomain, public IP, or private IP. For public domain access, add A records for the Studio and processor domains pointing to the machine IP in your DNS provider. For public/private IP access, the wizard can detect IP candidates and uses a single IP with the processor under /api. For production deployment, non-SSL access needs port 80; Let's Encrypt SSL setup uses ports 80 and 443, then closes port 80 if Samsar opened it. The wizard can try to manage these host firewall rules automatically on supported Linux hosts. Warning: this allows public access to your instance, so set a strong setup/admin password first and restrict access with HTTPS, firewall rules, and authentication.

For custom enterprise deployments behind a VPS, private network, or managed ingress, contact hello@samsar.one.

If a local Docker page fails only on first navigation with a dynamic import error, the browser is usually holding an old frontend build while the container serves a newer build. Refresh the tab. The Docker client server also returns a reload module for missing hashed JS chunks so stale tabs can recover automatically.

If local downloads open in a new tab instead of downloading, confirm the processor API can serve the mounted asset:

curl -I http://localhost:3002/assets_v2/video/output/<session-id>/<file>.mp4

If remote generation providers cannot fetch local media, confirm the setup wizard remains available to service JIT tunnel-refresh requests. A samsar-media-tunnel container should be running; provider workers validate the exact asset and wait for a refreshed tunnel before dispatching.

If an OpenRouter-backed inference model is missing from a Docker deployment, confirm providers.openrouter.enabled is true, confirm runtime/secrets/provider.credentials.json contains the OpenRouter key, rerun npm run config:render, and recreate the processor and inference workers. For hosted production and external-production, Qwen requires OPENROUTER_API_KEY; Alibaba credentials do not satisfy hosted Qwen inference. In Docker, Qwen can instead use validated Alibaba credentials or the configured Samsar fallback unless SAMSAR_QWEN_OPENROUTER_ONLY=true.

For a remote Docker host, set GRAFANA_ROOT_URL and optionally GRAFANA_DOMAIN, GRAFANA_PORT, or LOKI_PORT before starting Compose.

Use these public surfaces for the live product, developer reference, publishing, and demo channels.

Do not commit runtime credentials, generated assets, local uploads, dependency folders, or build output. The sync script excludes common secret and generated paths when copying projects into this monorepo.

When making changes during an active generation session, prefer restarting only the affected client or API container. Restart generation workers only after checking logs and confirming the in-flight job can resume safely.