Files
shumai/README.md
T

6.7 KiB

Shumai Logo

Shumai

An open-source platform for all your creative work, similar to Frame.io.


Shumai App Screenshot

Features

  • S3-Compatible & Local FS Storage: Securely store and serve your creative assets using local filesystems or any S3-compatible cloud storage (AWS S3, Cloudflare R2, MinIO, etc.).
  • Comments with Draw Annotations & Timestamps: Give precise feedback with frame-specific drawing tools and exact timestamps directly on video and image assets.
  • Easy Share Links & Collections: Create secure external share links and curated media collections to collaborate with external clients and stakeholders.
  • Team & Project Member Management: Manage granular workspace permissions using team-level and project-level role-based access control.
  • Scalable Transcode Workflows via Temporal: Offload resource-heavy video transcoding to a reliable background worker pool orchestrated by Temporal.
  • Flexible Asset Metadata System: Customize your workspace metadata with dynamic, user-defined fields tailored to your production pipeline.

Shumai AI

  • Chat with Agent as a Collaborator: Converse with a context-aware AI agent directly within your project workspace.
  • Extend Agent with Skills: Easily register new tools and custom skills for the agent to run and automate workflows.
  • Secure Sandboxed Execution: Execute agent scripts and tasks in a secure, isolated sandbox environment.
  • AI-Powered Metadata Autofill: Automatically generate tags, descriptions, and custom metadata for new assets using Google Gemini.
  • Semantic Asset Search: Find assets instantly based on their visual and textual content using vector embeddings.

Installation

Option 1: Docker Compose (Quick Start)

The easiest way to run Shumai is using Docker Compose. You do not need to clone the repository:

  1. Create a docker-compose.yaml file by copying the configuration from GitHub or download it directly:
    curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose.yaml
    
  2. Start the services:
    docker compose up -d
    
  3. Access the application in your browser at:
    http://localhost:3000
    
  4. Stop and remove the services:
    docker compose down
    

Option 2: Install from NPM

You can run Shumai using the npm package @shumai-one/shumai. This option allows you to install and run Shumai globally or locally via your favorite package manager.

Step 1: Start PostgreSQL with pgvector

Shumai requires PostgreSQL with the pgvector extension. You can spin up a pre-configured database container using Docker:

docker run --name shumai_postgres \
  -e POSTGRES_USER=shumai \
  -e POSTGRES_PASSWORD=shumai_password \
  -e POSTGRES_DB=shumai_db \
  -p 5432:5432 \
  -d pgvector/pgvector:pg18

Step 2: Install Shumai globally

Install the main Shumai package using npm, pnpm, bun, or yarn:

npm install -g @shumai-one/shumai
# or: pnpm add -g @shumai-one/shumai
# or: bun add -g @shumai-one/shumai

Step 3: Configure Environment Variables

Create a new directory for your Shumai configuration and navigate into it:

mkdir my-shumai-app
cd my-shumai-app

Create a .env file in this folder and add the following configuration (which aligns with the Docker database command in Step 1):

DATABASE_URL=postgresql://shumai:shumai_password@localhost:5432/shumai_db?schema=public
BETTER_AUTH_SECRET=ySxs7DxzHDGBbeeHNPEwBuspYwipBqz5Gk5XdBjNhWw=
BETTER_AUTH_URL=http://localhost:3000
STORAGE_BACKEND=local

Step 4: Run Shumai

Start the application from your configuration folder:

shumai

On startup, Shumai will automatically run the necessary database migrations and start the web server at http://localhost:3000.


Option 3: Run from Source

To run Shumai locally for development:

  1. Clone the repository and install dependencies:
    git clone https://github.com/shumaiOne/shumai.git
    cd shumai
    bun install
    
  2. Start the pgvector database container (as described in Option 2, Step 1).
  3. Create a .env file at the root of the workspace using the example configuration from Option 2, Step 3.
  4. Run the database migrations:
    bun run db:migrate
    
  5. Start the development server:
    bun run dev
    

Advanced: Distributed Execution with Temporal

For production environments or workloads with heavy media processing and AI agent requirements, Shumai can delegate background activities to Temporal. This provides distributed queue management, task retries, and high availability.

How it works

By setting the environment variable WORKFLOW_EXECUTOR=temporal, the main Shumai application will delegate background workflows to a Temporal cluster instead of using the local polling-based engine. This allows you to run independent worker processes (shumai-agent and shumai-transcode) on separate specialized machines (e.g., transcoding workers on GPU-accelerated instances, and agents on sandboxed environments).

1. Configure the environment

Add the following variables to your .env configuration on all machines:

WORKFLOW_EXECUTOR=temporal
TEMPORAL_ADDRESS=localhost:7233

2. Set up the stack

An example setup using Docker Compose can spin up the main application, database, and Temporal services:

  1. Navigate to the temporal compose directory:
    cd docker-compose/temporal
    
  2. Start the services:
    docker compose up -d --build
    
    This exposes the Shumai Web UI at http://localhost:3000 and the Temporal dashboard at http://localhost:8080.

3. Run workers on separate machines

If you want to scale horizontally or isolate tasks, you can run the agent and transcoding workers separately:

  • Transcoding Worker: Install @shumai-one/shumai-transcode and run it on a machine with sufficient transcoding resources:

    npm install -g @shumai-one/shumai-transcode
    # Run worker with correct .env containing DATABASE_URL and TEMPORAL_ADDRESS
    shumai-transcode
    
  • AI Agent Worker: Install @shumai-one/shumai-agent and run it on a machine configured for AI tasks (with access to sandbox environments and GEMINI_API_KEY):

    npm install -g @shumai-one/shumai-agent
    # Run worker with correct .env containing DATABASE_URL and TEMPORAL_ADDRESS
    shumai-agent