GitHub JavaScript Monthly Trending

Anil-matcha/Open-Generative-AI

Open-source alternative to AI video platforms — Free AI image & video generation studio with 200+ models (Flux, Midjourney, Kling, Sora, Veo). No content filters. Self-hosted, MIT licensed.

Open Generative AI — Open-Source Alternative to AI Video Platforms

The free, open-source alternative to AI Video Platforms. Generate AI images and videos using 200+ state-of-the-art models — no content filters, no closed ecosystem, no subscription fees.

Community: Join Reddit & Discord for discussions and support

🤖 Automate media generations with AI coding agents: Generative-Media-Skills — a library of skills that let agents like Claude Code, Codex, and other coding assistants drive 200+ image/video models end-to-end (prompt → generate → edit → stitch) directly from your terminal. Perfect for building automated media pipelines without touching a UI.

Related projects

Open-source Node based workflow builder -> https://github.com/SamurAIGPT/Vibe-Workflow

Open-source AI Clipping — turn any long-form YouTube video into viral-ready vertical shorts -> https://github.com/SamurAIGPT/AI-Youtube-Shorts-Generator

Open-source AI Design Agent -> https://github.com/Anil-matcha/Open-AI-Design-Agent

🌐 Try it Online — No Install Required

Hosted version: https://muapi.ai/open-generative-ai

Use all four studios (Image, Video, Lip Sync, Cinema) directly in your browser — no Node.js, no setup. Sign up for a free account to start generating. The hosted version is always up to date with the latest models.

Follow the creator for updates

⬇️ Download Desktop App

One-click installers — no Node.js or terminal required.

Platform	Download
macOS Apple Silicon (M1/M2/M3/M4)	Open Generative AI-1.0.9-arm64.dmg
macOS Intel (x64)	Open Generative AI-1.0.9.dmg
Windows (x64)	Open Generative AI Setup 1.0.9.exe
Linux (Ubuntu x64)	v1.0.9 release (`.AppImage` / `.deb`), or build locally with `npm run electron:build:linux`.

All releases: github.com/Anil-matcha/Open-Generative-AI/releases

macOS Installation Guide

Because the app is not notarized by Apple, macOS Gatekeeper will block it on first launch. Follow these steps:

Step 1 — Mount the DMG and drag the app to /Applications

Step 2 — Open Terminal and run:

xattr -cr "/Applications/Open Generative AI.app"

Step 3 — Right-click the app in /Applications → click Open → click Open again on the dialog

You only need to do this once. After that, the app opens normally.

Alternative (no Terminal):

Try to open the app — macOS will block it
Go to System Settings → Privacy & Security
Scroll down to find "Open Generative AI was blocked"
Click Open Anyway → Open

Windows Installation — SmartScreen warning fix

Windows SmartScreen may show a warning because the installer is not code-signed:

Click More info on the SmartScreen dialog
Click Run anyway

The app will install silently to %LocalAppData% with a Start Menu shortcut.

Ubuntu / Linux Installation

Linux artifacts are available when building with Electron Builder:

# Build Linux installers (AppImage + .deb)
npm run electron:build:linux

Generated files are written to the release/ folder:

AppImage — portable, run directly after making executable:

chmod +x "release/Open Generative AI-*.AppImage"
./release/Open\ Generative\ AI-*.AppImage

.deb — install on Debian/Ubuntu:

sudo apt install ./release/open-generative-ai_*_amd64.deb

If AppImage fails to start on older systems, install libfuse2:

sudo apt install libfuse2

Ubuntu 24.04+ / AppArmor sandbox restriction

Ubuntu 24.04 and later enable a kernel security policy (apparmor_restrict_unprivileged_userns) that blocks Chromium's user-namespace sandbox. If the app fails to start silently or crashes immediately, you have two options:

Option A — Recommended: install the .deb instead. The .deb package ships an AppArmor profile that grants the required permission automatically on install with no system-wide changes.

Option B — Temporary system fix (AppImage users):

sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

This lasts until next reboot. To make it permanent:

echo 'kernel.apparmor_restrict_unprivileged_userns=0' | sudo tee /etc/sysctl.d/99-userns.conf

Open Generative AI is a free, open-source AI image, video, cinema, and lip sync studio that brings creative workflows to everyone. No content filters, no prompt rejections, no guardrails — just full creative freedom. Powered by Muapi.ai, it supports text-to-image, image-to-image, text-to-video, image-to-video, and audio-driven lip sync generation across models like Flux, Nano Banana, Midjourney, Kling, Sora, Veo, Seedream, Infinite Talk, LTX Lipsync, Wan 2.2, and more — all from a sleek, modern interface you can self-host and customize.

Why Open Generative AI instead of other AI Video Platforms?

No filters — no content filters, no nanny guardrails, no prompt rejections
Free & open-source — no subscription, no vendor lock-in
Self-hosted — your data stays on your machine, full creative control
200+ models — text-to-image, image-to-image, text-to-video, image-to-video, lip sync
Multi-image input — feed up to 14 reference images into compatible models
Lip Sync Studio — animate portraits or sync lips to any audio with 9 dedicated models
Extensible — add your own models, modify the UI, build on top of it

For a deep dive into the technical architecture and the philosophy behind the "Infinite Budget" cinema workflow, see our comprehensive guide and roadmap.

⚡ Local Model Inference (Desktop App Only)

The desktop app supports two independent local engines. Pick whichever fits the machine you actually run on:

Engine	What it is	Best for
sd.cpp (bundled)	C++ engine from stable-diffusion.cpp, runs on the same machine as the app. Metal GPU on Apple Silicon, CUDA/Vulkan/ROCm on Linux/Windows.	Image-only models. Works on Mac M-series.
Wan2GP (BYO server)	HTTP client to a user-run Wan2GP server. The server runs Python + PyTorch on a CUDA/ROCm GPU; the desktop app only sends prompts and receives results.	Video models (Wan 2.2, Hunyuan, LTX) and large image models (Flux, Qwen-Image). NVIDIA/AMD GPU required on the server; the desktop app itself can run on a Mac.

Both engines share the same UI: open Settings → Local Models to configure each.

Engine 1 — sd.cpp (bundled)

Model	Type	Size	Notes
Z-Image Turbo ⚡	Diffusion Transformer	2.5 GB + 2.7 GB aux	8-step turbo. Heavy on memory.
Z-Image Base ⚡	Diffusion Transformer	3.5 GB + 2.7 GB aux	50-step high-quality. Heavy on memory.
Dreamshaper 8	SD 1.5	2.1 GB	20-step versatile. Lightest tested option on Mac.
Realistic Vision v5.1	SD 1.5	2.1 GB	25-step photorealistic
Anything v5	SD 1.5	2.1 GB	20-step anime/illustration
SDXL Base 1.0	SDXL	6.9 GB	30-step high-res

Z-Image models require two shared auxiliary files (downloaded once, shared across both models):

Qwen3-4B Text Encoder — 2.4 GB

FLUX VAE — 335 MB

How to use:

Open Settings → Local Models in the desktop app
Install the sd.cpp inference engine (one click — auto-downloaded)
Download your chosen model (and auxiliary files for Z-Image)
In Image Studio, click the ⚡ Local toggle next to the model selector
Select your local model and generate — no API key needed

All downloads happen inside the app. Nothing is installed system-wide.

Engine 2 — Wan2GP (remote Gradio server)

The app does not bundle Python or model weights for Wan2GP. You run Wan2GP yourself on a machine with a CUDA or ROCm GPU and point the desktop app at its URL.

# On your GPU machine
git clone https://github.com/deepbeepmeep/Wan2GP
cd Wan2GP
./install.sh                          # or install.bat on Windows
python wgp.py --listen --server-name 0.0.0.0   # binds to all interfaces

Then in the desktop app: Settings → Local Models → Wan2GP server, paste the URL (e.g. http://192.168.1.42:7860), click Test, then Save. The Wan2GP models become available — image models in Image Studio, video models reachable via the same generation API (Image Studio rejects video output explicitly; full Video Studio wiring is on the roadmap).

Model	Type	Notes
Flux.1 Dev	Image	1024px, 28 steps
Qwen Image	Image	1024px, 30 steps
Wan 2.2 (T2V / I2V)	Video	Slow on consumer GPUs
Hunyuan Video	Video	High-quality T2V
LTX Video	Video	Fastest video option

Why a separate server? Wan2GP's runtime (Sage attention, flash-attn, AWQ/GGUF kernels) is CUDA-only — there is no MPS / Apple Silicon path. Treating it as a remote server lets a Mac-only user keep the desktop app while offloading inference to a Linux/Windows GPU box, a gaming PC on the LAN, or a rented RunPod/vast.ai instance.

Local inference is only available in the desktop app. The hosted web version always uses cloud APIs.

Hardware Notes

sd.cpp runs on CPU (all platforms) and Metal GPU on Apple Silicon (M1/M2/M3/M4); CUDA/Vulkan/ROCm on Linux/Windows.
Metal GPU acceleration is built into the macOS desktop binary — significantly faster than CPU-only.
Recommended for sd.cpp Z-Image: 16 GB RAM (7.4 GB weights + 2.4 GB compute buffer). On a base 8 GB M-series Mac, Z-Image is known to hang the system — stick to SD 1.5 there.
For SD 1.5 on M2: expect ~1–2 s/step with the Metal dylib active. If you see ~10 s/step instead, the binary may have fallen back to CPU — see verification below.

Verifying the SD 1.5 path (the fastest sanity test on Mac)

If you want to confirm sd.cpp is installed correctly without going through the UI, you can drive sd-cli directly. This is the same binary the app uses.

# 1. App data layout (created on first app launch)
APP_DATA="$HOME/Library/Application Support/open-generative-ai/local-ai"
ls "$APP_DATA/bin"     # sd-cli, libstable-diffusion.dylib
ls "$APP_DATA/models"  # whatever you've downloaded

# 2. Grab a small SD 1.5 model directly (Dreamshaper 8, ~2 GB)
curl -L --fail --progress-bar \
  -o "$APP_DATA/models/DreamShaper_8_pruned.safetensors" \
  "https://huggingface.co/Lykon/DreamShaper/resolve/main/DreamShaper_8_pruned.safetensors"

# 3. Run a single 512x512 / 12-step inference
DYLD_LIBRARY_PATH="$APP_DATA/bin" "$APP_DATA/bin/sd-cli" \
  -m "$APP_DATA/models/DreamShaper_8_pruned.safetensors" \
  -p "a serene mountain lake at sunrise, oil painting" \
  -o /tmp/sd15-test.png \
  --steps 12 -H 512 -W 512 --cfg-scale 7.5 --seed 42 \
  --sampling-method euler_a

A healthy run on Apple Silicon prints total params memory size = 1969.78MB (VRAM 1969.78MB, RAM 0.00MB) (Metal-backed) and produces a coherent 512×512 PNG. If VRAM is 0.00MB instead, the dylib is CPU-only — check otool -L "$APP_DATA/bin/libstable-diffusion.dylib" | grep -i metal and reinstall the engine from Settings → Local Models if Metal is missing.

✨ Features

Image Studio — Generate images from text prompts (50+ text-to-image models) or transform existing images (55+ image-to-image models). Switches model set automatically based on whether a reference image is provided. Quality and resolution controls visible for models that support them.
Local Inference — Two engines: sd.cpp (bundled, runs on Mac/Win/Linux with Metal/CUDA/Vulkan/ROCm) for SD 1.5, SDXL, and Z-Image; and Wan2GP (BYO Gradio server) for Flux, Qwen-Image, and video models (Wan 2.2, Hunyuan, LTX). Configure both in Settings → Local Models.
Multi-Image Input — Upload up to 14 reference images for compatible edit models (Nano Banana 2 Edit, Flux Kontext Dev, GPT-4o Edit, and more). Multi-select picker with order badges, batch upload, and a "Use Selected" confirmation flow.
Video Studio — Generate videos from text prompts (40+ text-to-video models) or animate a start-frame image (60+ image-to-video models). Same intelligent mode switching as Image Studio.
Lip Sync Studio — Animate portrait images or sync lips on existing videos using audio. 9 dedicated models across two modes: portrait image + audio → talking video, and video + audio → lipsync video.
Cinema Studio — Interface for photorealistic cinematic shots with pro camera controls (Lens, Focal Length, Aperture)
Workflow Studio — Build and run multi-step AI pipelines visually. Chain image, video, and audio models into automated flows. Browse community templates, create your own with a node-based editor, and run them via an interactive playground.
Upload History — Reference images are uploaded once and stored locally. A picker panel lets you reuse any previously uploaded image across sessions — no re-uploading.
Smart Controls — Dynamic aspect ratio, resolution/quality, and duration pickers that adapt to each model's capabilities (including t2i models with resolution or quality options)
Generation History — Browse, revisit, and download all past generations (persisted in browser storage)
Image & Video Download — One-click download of generated outputs in full resolution
API Key Management — Secure API key storage in browser localStorage (never sent to any server except Muapi)
Responsive Design — Works seamlessly on desktop and mobile with dark glassmorphism UI

🖼️ Image Studio — Dual Mode

The Image Studio automatically switches between two model sets:

Mode	Trigger	Models	Prompt
Text-to-Image	Default (no image)	50+ t2i models (Flux, Nano Banana 2, Seedream 5.0, Ideogram, GPT-4o, Midjourney…)	Required
Image-to-Image	Reference image uploaded	55+ i2i models (Kontext, Nano Banana 2 Edit, Seedream 5.0 Edit, Seededit, Upscaler…)	Optional

Newly Added Models

Model	Type	Key Features
Nano Banana 2	Text-to-Image	Google Gemini 3.1 Flash Image · Resolution 1K/2K/4K · Google Search enhancement · aspect ratio `auto`
Nano Banana 2 Edit	Image-to-Image	Up to 14 reference images · Resolution 1K/2K/4K · Google Search enhancement
Seedream 5.0	Text-to-Image	ByteDance · Quality basic/high · 8 aspect ratios · up to 4K
Seedream 5.0 Edit	Image-to-Image	ByteDance · Natural language style transfer · Quality basic/high
MiniMax Image 01	Text-to-Image	MiniMax · 8 aspect ratios · up to 4 images per request · 1500 char prompt

Multi-Image Input

Models that accept multiple reference images expose a multi-select picker when active:

Model	Max Images
Nano Banana 2 Edit	14
Nano Banana Edit	10
Flux Kontext Dev I2I	10
Kling O1 Edit Image	10
GPT-4o Edit / GPT Image 1.5 Edit	10
Bytedance Seedream Edit v4 / v4.5	10
Vidu Q2 Reference to Image	7
Flux 2 Flex/Pro Edit	8
Nano Banana Pro Edit	8
Flux Kontext Pro/Max I2I	2
Wan 2.5/2.6 Image Edit	2–3
Qwen Image Edit Plus / 2511	3
GPT-4o Image to Image	5
Flux 2 Klein 4b/9b Edit	4

When a multi-image model is selected the upload trigger switches to multi-select mode:

Checkboxes with order numbers — images are sent to the model in the order you select them
Batch upload — pick multiple files at once from your file dialog
Count badge on the trigger shows how many images are active; a + badge appears when more slots are available
"Use Selected" button confirms and closes the picker

🎬 Video Studio — Dual Mode

The Video Studio follows the same pattern:

Mode	Trigger	Models	Prompt
Text-to-Video	Default (no image)	40+ t2v models (Kling, Sora, Veo, Wan, Seedance 2.0, Hailuo, Runway…)	Required
Image-to-Video	Start frame uploaded	60+ i2v models (Kling I2V, Veo3 I2V, Runway I2V, Wan I2V, Seedance 2.0 I2V, Midjourney I2V…)	Optional

Newly Added Models

Model	Type	Key Features
Seedance 2.0	Text-to-Video	ByteDance · Aspect ratios 16:9 / 9:16 / 4:3 / 3:4 · Duration 5 / 10 / 15s · Quality basic/high
Seedance 2.0 I2V	Image-to-Video	ByteDance · Animate images into video · Up to 9 reference images · Aspect ratios 16:9 / 9:16 / 4:3 / 3:4 · Duration 5 / 10 / 15s · Quality basic/high
Seedance 2.0 Extend	Video Extension	ByteDance · Seamlessly continue any Seedance 2.0 generation · Preserves style, motion & audio · Optional continuation prompt · Duration 5 / 10 / 15s · Quality basic/high
Grok Imagine T2V	Text-to-Video	xAI · Duration 6 / 10 / 15s · Modes: fun / normal / spicy · Aspect ratios 9:16 / 16:9 / 2:3 / 3:2 / 1:1
Grok Imagine I2V	Image-to-Video	xAI · Duration 6 / 10 / 15s · Modes: fun / normal / spicy · Cinematic motion from still images
MiniMax Hailuo 02 / 2.3 Standard & Pro	Text-to-Video / Image-to-Video	MiniMax · Full HD video · Multiple aspect ratios · Fast variant included

🎙️ Lip Sync Studio

The Lip Sync Studio generates audio-driven talking videos using 9 models across two input modes:

Mode	Trigger	Description
Portrait Image	Default	Upload a portrait image + audio file → animated talking video
Video	Switch to Video mode	Upload an existing video + audio file → lipsync video

Image-based Models (Portrait Image + Audio → Video)

Model	Endpoint	Resolutions	Prompt
Infinite Talk	`infinitetalk-image-to-video`	480p, 720p	Optional
Wan 2.2 Speech to Video	`wan2.2-speech-to-video`	480p, 720p	Optional
LTX 2.3 Lipsync	`ltx-2.3-lipsync`	480p, 720p, 1080p	Optional
LTX 2 19B Lipsync	`ltx-2-19b-lipsync`	480p, 720p, 1080p	Optional

Video-based Models (Video + Audio → Lipsync Video)

Model	Endpoint	Resolutions	Prompt
Sync Lipsync	`sync-lipsync`	—	—
LatentSync	`latentsync-video`	—	—
Creatify Lipsync	`creatify-lipsync`	—	—
Veed Lipsync	`veed-lipsync`	—	—
Infinite Talk V2V	`infinitetalk-video-to-video`	480p, 720p	Optional

How it works:

Select Portrait Image or Video mode using the toggle
Upload your portrait image (or video) using the image/video upload button
Upload your audio file using the audio upload button
Optionally enter a prompt to guide the motion style
Select a model and resolution (where supported), then click Generate

Generation history is saved separately in lipsync_history and pending jobs resume automatically on page reload.

🔀 Workflow Studio

The Workflow Studio lets you build and run multi-step AI pipelines without writing code.

Key capabilities:

Templates — Start from pre-built workflows (image chains, video pipelines, and more)
My Workflows — Save and manage your own custom pipelines
Community — Browse and run workflows published by other users
Node-based Builder — Drag-and-drop visual editor to connect models and route outputs between steps
Playground — Run any workflow interactively with a form UI; results render inline
API execution — Every workflow is also callable via the Muapi API

💡 Want to add workflows to your own app? Check out Vibe Workflow — the open-source workflow engine powering this feature. Drop it into any project.

🎥 Cinema Studio Controls

The Cinema Studio offers precise control over the virtual camera, translating your choices into optimized prompt modifiers:

Category	Available Options
Cameras	Modular 8K Digital, Full-Frame Cine Digital, Grand Format 70mm Film, Studio Digital S35, Classic 16mm Film, Premium Large Format Digital
Lenses	Creative Tilt, Compact Anamorphic, Extreme Macro, 70s Cinema Prime, Classic Anamorphic, Premium Modern Prime, Warm Cinema Prime, Swirl Bokeh Portrait, Vintage Prime, Halation Diffusion, Clinical Sharp Prime
Focal Lengths	8mm (Ultra-Wide), 14mm, 24mm, 35mm (Human Eye), 50mm (Portrait), 85mm (Tight Portrait)
Apertures	f/1.4 (Shallow DoF), f/4 (Balanced), f/11 (Deep Focus)

📁 Upload History & Picker

Every image you upload is saved locally (URL + thumbnail) so you never upload the same file twice:

Click the upload button to open the reference image picker
Previously uploaded images appear in a 3-column grid with thumbnails
Single-image models — click a thumbnail to instantly select and close
Multi-image models — toggle multiple thumbnails (shown with order numbers), then click Use Selected
Upload new images with the Upload files button (supports multi-file selection in multi-image mode)
Remove individual images from history with the ✕ button
History persists across browser sessions (stored in localStorage)

🚀 Quick Start

Prerequisites

Node.js (v18+)
A Muapi.ai API key

Setup

Most users want the desktop app, not this dev path. If you just want to run Open Generative AI on your machine, download a prebuilt installer instead — no Node.js required. The instructions below are for contributors building from source.

Pick the entry point that matches your goal:

Desktop app (Electron) → npm run electron:dev
Hosted web version (Next.js) → npm run dev

# Clone the repository (with submodules — required for the workflow + agent packages)
git clone --recurse-submodules https://github.com/Anil-matcha/Open-Generative-AI.git
cd Open-Generative-AI

# If you already cloned without --recurse-submodules, run this once:
# git submodule update --init --recursive

# Install dependencies + build workspace packages (studio, workflow, agents).
# This step is REQUIRED — `npm install` alone is not enough; the workspaces
# need to be built before either dev script will work.
npm run setup

# Then start ONE of:
npm run electron:dev   # Desktop app (Electron + Vite) — recommended
npm run dev            # Hosted web version (Next.js) → http://localhost:3000

You'll be prompted to enter your Muapi API key on first use (skip the key if you only plan to use local models).

Troubleshooting — Couldn't find a 'pages' directory: this means Next.js can't see the app/ folder. Confirm you're running npm run dev from the repo root (the directory that contains app/, package.json, and next.config.mjs), and that you cloned with submodules. Re-run npm run setup if packages/Vibe-Workflow or packages/Open-Poe-AI are empty.

Production Build

npm run build
npm run start

Desktop App Build

Build native desktop apps with Electron:

# macOS (DMG — Intel + Apple Silicon)
npm run electron:build

# Windows (NSIS installer — x64 + ARM64)
npm run electron:build:win

# Linux (AppImage + DEB — x64)
npm run electron:build:linux

# Both platforms in one pass
npm run electron:build:all

Installers are output to the release/ folder. Pre-built binaries are also available on the Releases page.

🏗️ Architecture

The app is a Next.js monorepo with a shared packages/studio component library.

Open-Generative-AI/
├── app/                        # Next.js App Router
│   ├── layout.js               # Root layout (Tailwind, fonts)
│   ├── page.js                 # Redirects → /studio
│   └── studio/
│       └── page.js             # Studio page — renders StandaloneShell
├── components/
│   ├── StandaloneShell.js      # Tab nav + BYOK (API key from localStorage)
│   └── ApiKeyModal.js          # API key entry modal
├── packages/
│   └── studio/                 # Shared React component library
│       └── src/
│           ├── index.js        # Exports: ImageStudio, VideoStudio, LipSyncStudio, CinemaStudio, WorkflowStudio
│           ├── models.js       # 200+ model definitions (single source of truth)
│           ├── muapi.js        # API client (named exports, apiKey as first param)
│           └── components/
│               ├── ImageStudio.jsx    # Dual-mode t2i/i2i studio
│               ├── VideoStudio.jsx    # Dual-mode t2v/i2v studio
│               ├── LipSyncStudio.jsx  # Portrait/video + audio → talking video
│               ├── CinemaStudio.jsx   # Pro studio with camera controls
│               └── WorkflowStudio.jsx # Multi-step pipeline builder & playground
├── next.config.mjs             # transpilePackages: ['studio']
├── tailwind.config.js
└── package.json                # workspaces: ["packages/studio"]

The packages/studio library is also consumed by the hosted version on muapi.ai — model updates made in packages/studio/src/models.js apply to both the self-hosted app and the hosted version automatically.

🔌 API Integration

The app communicates with Muapi.ai using a two-step pattern:

Submit — POST /api/v1/{model-endpoint} with prompt and parameters
Poll — GET /api/v1/predictions/{request_id}/result until status is completed

Authentication uses the x-api-key header. During development, a Vite proxy handles CORS by routing /api requests to https://api.muapi.ai.

File uploads use POST /api/v1/upload_file (multipart/form-data) and return a hosted URL that is passed to image-conditioned models. For multi-image models the full images_list array is forwarded to the API in one request.

Lip sync jobs use the same two-step pattern: a dedicated processLipSync() method accepts image_url or video_url alongside audio_url, dispatches to the model's endpoint, and polls until the output video URL is available.

🎨 Supported Model Categories

Category	Count	Examples
Text-to-Image	50+	Flux Dev, Nano Banana 2, Seedream 5.0, Ideogram v3, Midjourney v7, GPT-4o, SDXL
Image-to-Image	55+	Nano Banana 2 Edit (×14), Flux Kontext Pro, GPT-4o Edit, Seededit v3, Upscaler, Background Remover
Text-to-Video	40+	Kling v3, Sora 2, Veo 3, Wan 2.6, Seedance 2.0, Seedance 2.0 Extend, Seedance Pro, Hailuo 2.3, Runway Gen-3
Image-to-Video	60+	Kling v2.1 I2V, Veo3 I2V, Runway I2V, Seedance 2.0 I2V, Midjourney v7 I2V, Hunyuan I2V, Wan2.2 I2V
Lip Sync	9	Infinite Talk I2V, Wan 2.2 Speech to Video, LTX 2.3 Lipsync, LTX 2 19B Lipsync, Sync, LatentSync, Creatify, Veed, Infinite Talk V2V

🛠️ Tech Stack

Next.js 14 — App Router, server components, fast dev server
React 18 — Studio UI components
Tailwind CSS v3 — Utility-first styling
npm workspaces — Monorepo with shared packages/studio library
Muapi.ai — AI model API gateway

🤔 How is this different from other AI Video Plaforms?

Open Generative AI is a community-driven, open-source alternative that provides similar creative capabilities without the closed ecosystem:

	Other providers	Open Generative AI
Cost	Subscription-based	Free (open-source)
Content filters	Yes — prompts blocked or altered	None
Restrictions	Platform guardrails enforced	Full creative freedom
Models	Proprietary	200+ open & commercial models
Multi-image input	Limited	Up to 14 images per request
Lip sync	No	9 models, image & video modes
Hosted version	Subscription	Free at muapi.ai/open-generative-ai
Self-hosting	No	Yes
Customizable	No	Fully hackable
Data privacy	Cloud-based	Your data stays local
Source code	Closed	MIT licensed

📄 License

MIT

🙏 Credits

Built with Muapi.ai — the unified API for AI image and video generation models.

Deep Dive: For more details on the "AI Influencer" engine, upcoming "Popcorn" storyboarding features, and the future of this project, read the full technical overview.

Looking for a free, open-source AI Video Platform? Open Generative AI is an open-source AI image and video generation studio — with no content filters that you can self-host, customize, and extend.

decolua/9router

Unlimited FREE AI coding. Connect Claude Code, Codex, Cursor, Cline, Copilot, Antigravity to FREE Claude/GPT/Gemini via 40+ providers. Auto-fallback, RTK -40% tokens, never hit limits.

9Router - FREE AI Router & Token Saver

Never stop coding. Save 20-40% tokens with RTK + auto-fallback to FREE & cheap AI models.

Connect All AI Code Tools (Claude Code, Cursor, Antigravity, Copilot, Codex, Gemini, OpenCode, Cline, OpenClaw...) to 40+ AI Providers & 100+ Models.

🚀 Quick Start • 💡 Features • 📖 Setup • 🌐 Website

🇻🇳 Tiếng Việt • 🇨🇳 中文 • 🇯🇵 日本語

🤔 Why 9Router?

Stop wasting money, tokens and hitting limits:

❌ Subscription quota expires unused every month
❌ Rate limits stop you mid-coding
❌ Tool outputs (git diff, grep, ls...) burn tokens fast
❌ Expensive APIs ($20-50/month per provider)
❌ Manual switching between providers

9Router solves this:

✅ RTK Token Saver - Auto-compress tool_result content, save 20-40% tokens per request
✅ Maximize subscriptions - Track quota, use every bit before reset
✅ Auto fallback - Subscription → Cheap → Free, zero downtime
✅ Multi-account - Round-robin between accounts per provider
✅ Universal - Works with Claude Code, Codex, Cursor, Cline, any CLI tool

🔄 How It Works

┌─────────────┐
│  Your CLI   │  (Claude Code, Codex, OpenClaw, Cursor, Cline...)
│   Tool      │
└──────┬──────┘
       │ http://localhost:20128/v1
       ↓
┌─────────────────────────────────────────────┐
│           9Router (Smart Router)            │
│  • RTK Token Saver (cut tool_result tokens) │
│  • Format translation (OpenAI ↔ Claude)     │
│  • Quota tracking                           │
│  • Auto token refresh                       │
└──────┬──────────────────────────────────────┘
       │
       ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, GitHub Copilot
       │   ↓ quota exhausted
       ├─→ [Tier 2: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)
       │   ↓ budget limit
       └─→ [Tier 3: FREE] Kiro, OpenCode Free, Vertex ($300 credits)

Result: Never stop coding, minimal cost + 20-40% token savings via RTK

⚡ Quick Start

1. Install globally:

npm install -g 9router
9router

🎉 Dashboard opens at http://localhost:20128

2. Connect a FREE provider (no signup needed):

Dashboard → Providers → Connect Kiro AI (free Claude unlimited) or OpenCode Free (no auth) → Done!

3. Use in your CLI tool:

Claude Code/Codex/OpenClaw/Cursor/Cline Settings:
  Endpoint: http://localhost:20128/v1
  API Key: [copy from dashboard]
  Model: kr/claude-sonnet-4.5

That's it! Start coding with FREE AI models.

Alternative: run from source (this repository):

This repository package is private (9router-app), so source/Docker execution is the expected local development path.

cp .env.example .env
npm install
PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev

Production mode:

npm run build
PORT=20128 HOSTNAME=0.0.0.0 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run start

Default URLs:

Dashboard: http://localhost:20128/dashboard
OpenAI-compatible API: http://localhost:20128/v1

Video Guides

🇺🇸 English _{9Router + Claude Code FREE Setup by Build AI With Hamid}	🇻🇳 Tiếng Việt _{Tiết kiệm chi phí LLM cho OpenClaw với 9Router by Mì AI}	🇺🇸 English _{Claude Code FREE Forever — Unlimited Models by Build AI With Hamid}
🇺🇸 English _{Claude CLI Free Setup with 9Router 🚀 by CodeVerse Soban}	🇻🇳 Tiếng Việt _{Cài Đặt OpenClaw Free Từ A-Z + 9Router by Mai Gia}	🇺🇸 English _{FREE OpenClaw + Claude Opus 4.6 by Build AI With Hamid}

🎬 Made a video about 9Router? Submit a Pull Request adding your video to this section — we'll merge it!

🛠️ Supported CLI Tools

9Router works seamlessly with all major AI coding tools:

Claude-Code	OpenClaw	Codex	OpenCode	Cursor	Antigravity
Cline	Continue	Droid	Roo	Copilot	Kilo Code

🌐 Supported Providers

🔐 OAuth Providers

Claude-Code

Antigravity

Codex

GitHub

Cursor

🆓 Free Providers

Kiro AI
_{Claude 4.5 + GLM-5 + MiniMax
Unlimited FREE}

OpenCode Free
_{No auth • Auto-fetch models
Unlimited FREE}

Vertex AI
_{Gemini 3 Pro + GLM-5 + DeepSeek
$300 credits free}

Note: iFlow, Qwen and Gemini CLI free tiers were discontinued in 2026. Use Kiro / OpenCode Free / Vertex instead.

🔑 API Key Providers (40+)

_OpenRouter	_GLM	_Kimi	_MiniMax	_OpenAI	_Anthropic
_Gemini	_DeepSeek	_Groq	_xAI	_Mistral	_Perplexity
_{Together AI}	_Fireworks	_Cerebras	_Cohere	_NVIDIA	_SiliconFlow

...and 20+ more providers including Nebius, Chutes, Hyperbolic, and custom OpenAI/Anthropic compatible endpoints

💡 Key Features

Feature	What It Does	Why It Matters
🚀 RTK Token Saver (RTK ⭐40K)	Compress tool outputs (`git diff`, `grep`, `ls`, `tree`...) before sending to LLM	Save 20-40% input tokens per request
🪨 Caveman Mode (Caveman ⭐52K)	Inject caveman-speak prompt → LLM replies terse, technical substance preserved	Save up to 65% output tokens
🎯 Smart 3-Tier Fallback	Auto-route: Subscription → Cheap → Free	Never stop coding, zero downtime
📊 Real-Time Quota Tracking	Live token count + reset countdown	Maximize subscription value
🔄 Format Translation	OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro ↔ Vertex	Works with any CLI tool
👥 Multi-Account Support	Multiple accounts per provider	Load balancing + redundancy
🔄 Auto Token Refresh	OAuth tokens refresh automatically	No manual re-login needed
🎨 Custom Combos	Create unlimited model combinations	Tailor fallback to your needs
📝 Request Logging	Debug mode with full request/response logs	Troubleshoot issues easily
💾 Cloud Sync	Sync config across devices	Same setup everywhere
📊 Usage Analytics	Track tokens, cost, trends over time	Optimize spending
🌐 Deploy Anywhere	Localhost, VPS, Docker, Cloudflare Workers	Flexible deployment options

📖 Feature Details

🚀 RTK Token Saver

Tool outputs (git diff, grep, find, ls, tree, log dumps...) often eat 30-50% of your prompt budget. RTK detects them and applies smart, lossless compression before the request hits the LLM:

Filters: git-diff, git-status, grep, find, ls, tree, dedup-log, smart-truncate, read-numbered, search-list
Auto-detect: No config needed — RTK peeks the first 1KB of each tool_result and picks the right filter.
Safe by design: If a filter fails, throws, or makes output bigger, RTK silently keeps the original text. Errors never break your request.
Universal: Works across all formats (OpenAI, Claude, Gemini, Cursor, Kiro, OpenAI Responses) because it runs before any format translation.
Default ON: Toggle anytime in Dashboard → Endpoint settings.

Without RTK: 47K tokens sent to LLM
With RTK:    28K tokens sent to LLM   (40% saved · same context · same answer)

🎯 Smart 3-Tier Fallback

Create combos with automatic fallback:

Combo: "my-coding-stack"
  1. cc/claude-opus-4-6        (your subscription)
  2. glm/glm-4.7               (cheap backup, $0.6/1M)
  3. if/kimi-k2-thinking       (free fallback)

→ Auto switches when quota runs out or errors occur

📊 Real-Time Quota Tracking

Token consumption per provider
Reset countdown (5-hour, daily, weekly)
Cost estimation for paid tiers
Monthly spending reports

🔄 Format Translation

Seamless translation between formats:

OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro ↔ Vertex ↔ Antigravity ↔ Ollama ↔ OpenAI Responses
Your CLI tool sends OpenAI format → 9Router translates → Provider receives native format
Works with any tool that supports custom OpenAI endpoints

👥 Multi-Account Support

Add multiple accounts per provider
Auto round-robin or priority-based routing
Fallback to next account when one hits quota

🔄 Auto Token Refresh

OAuth tokens automatically refresh before expiration
No manual re-authentication needed
Seamless experience across all providers

🎨 Custom Combos

Create unlimited model combinations
Mix subscription, cheap, and free tiers
Name your combos for easy access
Share combos across devices with Cloud Sync

📝 Request Logging

Enable debug mode for full request/response logs
Track API calls, headers, and payloads
Troubleshoot integration issues
Export logs for analysis

💾 Cloud Sync

Sync providers, combos, and settings across devices
Automatic background sync
Secure encrypted storage
Access your setup from anywhere

Cloud Runtime Notes

Prefer server-side cloud variables in production:
- BASE_URL (internal callback URL used by sync scheduler)
- CLOUD_URL (cloud sync endpoint base)
NEXT_PUBLIC_BASE_URL and NEXT_PUBLIC_CLOUD_URL are still supported for compatibility/UI, but server runtime now prioritizes BASE_URL/CLOUD_URL.
Cloud sync requests now use timeout + fail-fast behavior to avoid UI hanging when cloud DNS/network is unavailable.

📊 Usage Analytics

Track token usage per provider and model
Cost estimation and spending trends
Monthly reports and insights
Optimize your AI spending

💡 IMPORTANT - Understanding Dashboard Costs:

The "cost" displayed in Usage Analytics is for tracking and comparison purposes only. 9Router itself never charges you anything. You only pay providers directly (if using paid services).

Example: If your dashboard shows "$290 total cost" while using iFlow models, this represents what you would have paid using paid APIs directly. Your actual cost = $0 (iFlow is free unlimited).

Think of it as a "savings tracker" showing how much you're saving by using free models or routing through 9Router!

🌐 Deploy Anywhere

💻 Localhost - Default, works offline
☁️ VPS/Cloud - Share across devices
🐳 Docker - One-command deployment
🚀 Cloudflare Workers - Global edge network

💰 Pricing at a Glance

Tier	Provider	Cost	Quota Reset	Best For
🚀 TOKEN SAVER	RTK (built-in)	FREE	Always on	Save 20-40% tokens on EVERY request
💳 SUBSCRIPTION	Claude Code (Pro/Max)	$20-200/mo	5h + weekly	Already subscribed
	Codex (Plus/Pro)	$20-200/mo	5h + weekly	OpenAI users
	GitHub Copilot	$10-19/mo	Monthly	GitHub users
	Cursor IDE	$20/mo	Monthly	Cursor users
💰 CHEAP	GLM-5.1 / GLM-4.7	$0.6/1M	Daily 10AM	Budget backup
	MiniMax M2.7	$0.2/1M	5-hour rolling	Cheapest option
	Kimi K2.5	$9/mo flat	10M tokens/mo	Predictable cost
🆓 FREE	Kiro AI	$0	Unlimited	Claude 4.5 + GLM-5 + MiniMax free
	OpenCode Free	$0	Unlimited	No auth, auto-fetch models
	Vertex AI	$300 credits	New GCP accounts	Gemini 3 Pro + DeepSeek + GLM-5

💡 Pro Tip: RTK + Kiro AI + OpenCode Free combo = $0 cost + 20-40% token savings!

📊 Understanding 9Router Costs & Billing

9Router Billing Reality:

✅ 9Router software = FREE forever (open source, never charges)
✅ Dashboard "costs" = Display/tracking only (not actual bills)
✅ You pay providers directly (subscriptions or API fees)
✅ FREE providers stay FREE (iFlow, Kiro, Qwen = $0 unlimited)
❌ 9Router never sends invoices or charges your card

How Cost Display Works:

The dashboard shows estimated costs as if you were using paid APIs directly. This is not billing - it's a comparison tool to show your savings.

Example Scenario:

Dashboard Display:
• Total Requests: 1,662
• Total Tokens: 47M
• Display Cost: $290

Reality Check:
• Provider: iFlow (FREE unlimited)
• Actual Payment: $0.00
• What $290 Means: Amount you SAVED by using free models!

Payment Rules:

Subscription providers (Claude Code, Codex): Pay them directly via their websites
Cheap providers (GLM, MiniMax): Pay them directly, 9Router just routes
FREE providers (iFlow, Kiro, Qwen): Genuinely free forever, no hidden charges
9Router: Never charges anything, ever

🎯 Use Cases

Case 1: "I have Claude Pro subscription"

Problem: Quota expires unused, rate limits during heavy coding

Solution:

Combo: "maximize-claude"
  1. cc/claude-opus-4-7        (use subscription fully)
  2. glm/glm-5.1               (cheap backup when quota out)
  3. kr/claude-sonnet-4.5      (free emergency fallback)

Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total
vs. $20 + hitting limits = frustration

Case 2: "I want zero cost"

Problem: Can't afford subscriptions, need reliable AI coding

Solution:

Combo: "free-forever"
  1. kr/claude-sonnet-4.5      (Claude 4.5 free unlimited)
  2. kr/glm-5                  (GLM-5 free via Kiro)
  3. oc/<auto>                 (OpenCode Free, no auth)

Monthly cost: $0
Quality: Production-ready models + RTK saves 20-40% tokens

Case 3: "I need 24/7 coding, no interruptions"

Problem: Deadlines, can't afford downtime

Solution:

Combo: "always-on"
  1. cc/claude-opus-4-7        (best quality)
  2. cx/gpt-5.5                (second subscription)
  3. glm/glm-5.1               (cheap, resets daily)
  4. minimax/MiniMax-M2.7      (cheapest, 5h reset)
  5. kr/claude-sonnet-4.5      (free unlimited)

Result: 5 layers of fallback = zero downtime
Monthly cost: $20-200 (subscriptions) + $10-20 (backup)

Case 4: "I want FREE AI in OpenClaw"

Problem: Need AI assistant in messaging apps (WhatsApp, Telegram, Slack...), completely free

Solution:

Combo: "openclaw-free"
  1. kr/claude-sonnet-4.5      (Claude 4.5 free)
  2. kr/glm-5                  (GLM-5 free)
  3. kr/MiniMax-M2.5           (MiniMax free)

Monthly cost: $0
Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal...

❓ Frequently Asked Questions

📊 Why does my dashboard show high costs?

The dashboard tracks your token usage and displays estimated costs as if you were using paid APIs directly. This is not actual billing - it's a reference to show how much you're saving by using free models or existing subscriptions through 9Router.

Example:

Dashboard shows: "$290 total cost"
Reality: You're using iFlow (FREE unlimited)
Your actual cost: $0.00
What $290 means: Amount you saved by using free models instead of paid APIs!

The cost display is a "savings tracker" to help you understand your usage patterns and optimization opportunities.

💳 Will I be charged by 9Router?

No. 9Router is free, open-source software that runs on your own computer. It never charges you anything.

You only pay:

✅ Subscription providers (Claude Code $20/mo, Codex $20-200/mo) → Pay them directly on their websites
✅ Cheap providers (GLM, MiniMax) → Pay them directly, 9Router just routes your requests
❌ 9Router itself → Never charges anything, ever

9Router is a local proxy/router. It doesn't have your credit card, can't send invoices, and has no billing system. It's completely free software.

🆓 Are FREE providers really unlimited?

Yes! The current FREE providers (Kiro, OpenCode Free, Vertex) are genuinely free with no hidden charges.

These are free services offered by those respective companies:

Kiro AI: Free unlimited Claude 4.5 + GLM-5 + MiniMax via AWS Builder ID / Google / GitHub OAuth
OpenCode Free: No-auth passthrough proxy, models auto-fetched from opencode.ai/zen/v1/models
Vertex AI: $300 free credits for new Google Cloud accounts (90 days)

9Router just routes your requests to them - there's no "catch" or future billing. They're truly free services, and 9Router makes them easy to use with fallback support.

Discontinued free tiers (no longer recommended):

❌ iFlow: Was free unlimited, now changed to paid (2026)
❌ Qwen Code: Free OAuth tier discontinued by Alibaba on 2026-04-15
❌ Gemini CLI: Still works, but using it with non-CLI tools (Claude, Codex, Cursor...) may result in account bans — only use if you stick to Gemini CLI itself

💰 How do I minimize my actual AI costs?

Free-First Strategy:

Start with 100% free combo:

1. gc/gemini-3-flash (180K/month free from Google)
2. if/kimi-k2-thinking (unlimited free from iFlow)
3. qw/qwen3-coder-plus (unlimited free from Qwen)

Cost: $0/month

Add cheap backup only if you need it:
```
4. glm/glm-4.7 ($0.6/1M tokens)
```
Additional cost: Only pay for what you actually use
Use subscription providers last:
- Only if you already have them
- 9Router helps maximize their value through quota tracking

Result: Most users can operate at $0/month using only free tiers!

📈 What if my usage suddenly spikes?

9Router's smart fallback prevents surprise charges:

Scenario: You're on a coding sprint and blow through your quotas

Without 9Router:

❌ Hit rate limit → Work stops → Frustration
❌ Or: Accidentally rack up huge API bills

With 9Router:

✅ Subscription hits limit → Auto-fallback to cheap tier
✅ Cheap tier gets expensive → Auto-fallback to free tier
✅ Never stop coding → Predictable costs

You're in control: Set spending limits per provider in dashboard, and 9Router respects them.

📖 Setup Guide

🔐 Subscription Providers (Maximize Value)

Claude Code (Pro/Max)

Dashboard → Providers → Connect Claude Code
→ OAuth login → Auto token refresh
→ 5-hour + weekly quota tracking

Models:
  cc/claude-opus-4-7
  cc/claude-opus-4-6
  cc/claude-sonnet-4-6
  cc/claude-haiku-4-5-20251001

Pro Tip: Use Opus for complex tasks, Sonnet for speed. 9Router tracks quota per model!

OpenAI Codex (Plus/Pro)

Dashboard → Providers → Connect Codex
→ OAuth login (port 1455)
→ 5-hour + weekly reset

Models:
  cx/gpt-5.5
  cx/gpt-5.4
  cx/gpt-5.3-codex
  cx/gpt-5.2-codex

GitHub Copilot

Dashboard → Providers → Connect GitHub
→ OAuth via GitHub
→ Monthly reset (1st of month)

Models:
  gh/gpt-5.4
  gh/claude-opus-4.7
  gh/claude-sonnet-4.6
  gh/gemini-3.1-pro-preview
  gh/grok-code-fast-1

Cursor IDE

Dashboard → Providers → Connect Cursor
→ OAuth login
→ Monthly subscription

Models:
  cu/claude-4.6-opus-max
  cu/claude-4.5-sonnet-thinking
  cu/gpt-5.3-codex

💰 Cheap Providers (Backup)

GLM-5.1 / GLM-4.7 (Daily reset, $0.6/1M)

Sign up: Zhipu AI
Get API key from Coding Plan
Dashboard → Add API Key:
- Provider: glm
- API Key: your-key

Use: glm/glm-5.1, glm/glm-5, glm/glm-4.7

Pro Tip: Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM.

MiniMax M2.7 (5h reset, $0.20/1M)

Sign up: MiniMax
Get API key
Dashboard → Add API Key

Use: minimax/MiniMax-M2.7, minimax/MiniMax-M2.5

Pro Tip: Cheapest option for long context (1M tokens)!

Kimi K2.5 ($9/month flat)

Subscribe: Moonshot AI
Get API key
Dashboard → Add API Key

Use: kimi/kimi-k2.5, kimi/kimi-k2.5-thinking

Pro Tip: Fixed $9/month for 10M tokens = $0.90/1M effective cost!

🆓 FREE Providers (Recommended)

Kiro AI (Claude 4.5 + GLM-5 + MiniMax FREE)

Dashboard → Connect Kiro
→ AWS Builder ID, AWS IAM Identity Center, Google, or GitHub
→ Unlimited usage

Models:
  kr/claude-sonnet-4.5
  kr/claude-haiku-4.5
  kr/glm-5
  kr/MiniMax-M2.5
  kr/qwen3-coder-next
  kr/deepseek-3.2

Pro Tip: Best free option for Claude. No API key, no payment, fully unlimited.

OpenCode Free (No auth, auto-fetch models)

Dashboard → Connect OpenCode Free
→ No login required (passthrough proxy)
→ Models auto-fetched from opencode.ai/zen/v1/models

Pro Tip: Fastest setup. Just connect and start coding.

Vertex AI ($300 free credits for new GCP accounts)

Dashboard → Connect Vertex AI
→ Upload Google Cloud Service Account JSON
→ Enable Vertex AI API in your GCP project

Models:
  vertex/gemini-3.1-pro-preview
  vertex/gemini-3-flash-preview
  vertex/gemini-2.5-flash

Vertex Partner (Anthropic / DeepSeek / GLM / Qwen via Vertex):
  vertex-partner/glm-5-maas
  vertex-partner/deepseek-v3.2-maas
  vertex-partner/qwen3-next-80b-a3b-thinking-maas

Pro Tip: New Google Cloud accounts get $300 credits free for 90 days. Plenty for daily coding.

🎨 Create Combos

Example 1: Maximize Subscription → Cheap Backup

Dashboard → Combos → Create New

Name: premium-coding
Models:
  1. cc/claude-opus-4-7 (Subscription primary)
  2. glm/glm-5.1 (Cheap backup, $0.6/1M)
  3. minimax/MiniMax-M2.7 (Cheapest fallback, $0.20/1M)

Use in CLI: premium-coding

Monthly cost example (100M tokens):
  80M via Claude (subscription): $0 extra
  15M via GLM: $9
  5M via MiniMax: $1
  Total: $10 + your subscription

Example 2: Free-Only (Zero Cost)

Name: free-combo
Models:
  1. kr/claude-sonnet-4.5 (Claude 4.5 free unlimited)
  2. kr/glm-5 (GLM-5 free via Kiro)
  3. vertex/gemini-3.1-pro-preview ($300 free credits)

Cost: $0 forever (+ 20-40% token savings via RTK)!

🔧 CLI Integration

Cursor IDE

Settings → Models → Advanced:
  OpenAI API Base URL: http://localhost:20128/v1
  OpenAI API Key: [from 9router dashboard]
  Model: cc/claude-opus-4-7

Or use combo: premium-coding

Claude Code

Edit ~/.claude/config.json:

{
  "anthropic_api_base": "http://localhost:20128/v1",
  "anthropic_api_key": "your-9router-api-key"
}

Codex CLI

export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-9router-api-key"

codex "your prompt"

OpenClaw

Option 1 — Dashboard (recommended):

Dashboard → CLI Tools → OpenClaw → Select Model → Apply

Option 2 — Manual: Edit ~/.openclaw/openclaw.json:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "9router/kr/claude-sonnet-4.5"
      }
    }
  },
  "models": {
    "providers": {
      "9router": {
        "baseUrl": "http://127.0.0.1:20128/v1",
        "apiKey": "sk_9router",
        "api": "openai-completions",
        "models": [
          {
            "id": "kr/claude-sonnet-4.5",
            "name": "Claude Sonnet 4.5 (Kiro Free)"
          }
        ]
      }
    }
  }
}

Note: OpenClaw only works with local 9Router. Use 127.0.0.1 instead of localhost to avoid IPv6 resolution issues.

Cline / Continue / RooCode

Provider: OpenAI Compatible
Base URL: http://localhost:20128/v1
API Key: [from dashboard]
Model: cc/claude-opus-4-7

🚀 Deployment

VPS Deployment

# Clone and install
git clone https://github.com/decolua/9router.git
cd 9router
npm install
npm run build

# Configure
export JWT_SECRET="your-secure-secret-change-this"
export INITIAL_PASSWORD="your-password"
export DATA_DIR="/var/lib/9router"
export PORT="20128"
export HOSTNAME="0.0.0.0"
export NODE_ENV="production"
export NEXT_PUBLIC_BASE_URL="http://localhost:20128"
export NEXT_PUBLIC_CLOUD_URL="https://9router.com"
export API_KEY_SECRET="endpoint-proxy-api-key-secret"
export MACHINE_ID_SALT="endpoint-proxy-salt"

# Start
npm run start

# Or use PM2
npm install -g pm2
pm2 start npm --name 9router -- start
pm2 save
pm2 startup

Docker

Published images (multi-platform linux/amd64 + linux/arm64):

Docker Hub: decolua/9router
GHCR: ghcr.io/decolua/9router

Quick start (use published image):

docker run -d \
  --name 9router \
  -p 20128:20128 \
  -v "$HOME/.9router:/app/data" \
  -e DATA_DIR=/app/data \
  decolua/9router:latest

→ Open http://localhost:20128

Build from source (dev):

git clone https://github.com/decolua/9router.git
cd 9router/app
docker build -t 9router .
docker run -d --name 9router -p 20128:20128 \
  -v "$HOME/.9router:/app/data" -e DATA_DIR=/app/data 9router

Container defaults:

PORT=20128
HOSTNAME=0.0.0.0

Useful commands:

docker logs -f 9router
docker restart 9router
docker stop 9router && docker rm 9router
docker pull decolua/9router:latest   # update to latest

Data persistence: $HOME/.9router/db/data.sqlite on host ↔ /app/data/db/data.sqlite in container.

Environment Variables

Variable	Default	Description
`JWT_SECRET`	Auto-generated (`~/.9router/jwt-secret`)	JWT signing secret for dashboard auth cookie (override to share across instances)
`INITIAL_PASSWORD`	`123456`	First login password when no saved hash exists
`DATA_DIR`	`~/.9router`	Main app data location (SQLite at `$DATA_DIR/db/data.sqlite`)
`PORT`	framework default	Service port (`20128` in examples)
`HOSTNAME`	framework default	Bind host (Docker defaults to `0.0.0.0`)
`NODE_ENV`	runtime default	Set `production` for deploy
`BASE_URL`	`http://localhost:20128`	Server-side internal base URL used by cloud sync jobs
`CLOUD_URL`	`https://9router.com`	Server-side cloud sync endpoint base URL
`NEXT_PUBLIC_BASE_URL`	`http://localhost:3000`	Backward-compatible/public base URL (prefer `BASE_URL` for server runtime)
`NEXT_PUBLIC_CLOUD_URL`	`https://9router.com`	Backward-compatible/public cloud URL (prefer `CLOUD_URL` for server runtime)
`API_KEY_SECRET`	`endpoint-proxy-api-key-secret`	HMAC secret for generated API keys
`MACHINE_ID_SALT`	`endpoint-proxy-salt`	Salt for stable machine ID hashing
`ENABLE_REQUEST_LOGS`	`false`	Enables request/response logs under `logs/`
`AUTH_COOKIE_SECURE`	`false`	Force `Secure` auth cookie (set `true` behind HTTPS reverse proxy)
`REQUIRE_API_KEY`	`false`	Enforce Bearer API key on `/v1/*` routes (recommended for internet-exposed deploys)
`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY`	empty	Optional outbound proxy for upstream provider calls

Notes:

Lowercase proxy variables are also supported: http_proxy, https_proxy, all_proxy, no_proxy.
.env is not baked into Docker image (.dockerignore); inject runtime config with --env-file or -e.
On Windows, APPDATA can be used for local storage path resolution.
INSTANCE_NAME appears in older docs/env templates, but is currently not used at runtime.

Runtime Files and Storage

Main app state: ${DATA_DIR}/db/data.sqlite (SQLite — providers, combos, aliases, keys, settings, usage history)
Auto backups: ${DATA_DIR}/db/backups/
Optional request/translator logs: <repo>/logs/... when ENABLE_REQUEST_LOGS=true
Both ${DATA_DIR} and ~/.9router resolve to the same location in a Docker container — the symlink /root/.9router -> /app/data is created at build time.

📊 Available Models

View all available models

Claude Code (cc/) - Pro/Max:

cc/claude-opus-4-7
cc/claude-opus-4-6
cc/claude-sonnet-4-6
cc/claude-sonnet-4-5-20250929
cc/claude-haiku-4-5-20251001

Codex (cx/) - Plus/Pro:

cx/gpt-5.5
cx/gpt-5.4
cx/gpt-5.3-codex
cx/gpt-5.2-codex
cx/gpt-5.1-codex-max

GitHub Copilot (gh/):

gh/gpt-5.4
gh/claude-opus-4.7
gh/claude-sonnet-4.6
gh/gemini-3.1-pro-preview
gh/grok-code-fast-1

Cursor (cu/) - Subscription:

cu/claude-4.6-opus-max
cu/claude-4.5-sonnet-thinking
cu/gpt-5.3-codex
cu/kimi-k2.5

GLM (glm/) - $0.6/1M:

glm/glm-5.1
glm/glm-5
glm/glm-4.7

MiniMax (minimax/) - $0.2/1M:

minimax/MiniMax-M2.7
minimax/MiniMax-M2.5

Kimi (kimi/) - $9/mo flat:

kimi/kimi-k2.5
kimi/kimi-k2.5-thinking

Kiro (kr/) - FREE unlimited:

kr/claude-sonnet-4.5
kr/claude-haiku-4.5
kr/glm-5
kr/MiniMax-M2.5
kr/qwen3-coder-next
kr/deepseek-3.2

OpenCode Free (oc/) - FREE no-auth:

Auto-fetched from opencode.ai/zen/v1/models

Vertex AI (vertex/) - $300 free credits:

vertex/gemini-3.1-pro-preview
vertex/gemini-3-flash-preview
vertex/gemini-2.5-flash
vertex-partner/glm-5-maas
vertex-partner/deepseek-v3.2-maas

🐛 Troubleshooting

"Language model did not provide messages"

Provider quota exhausted → Check dashboard quota tracker
Solution: Use combo fallback or switch to cheaper tier

Rate limiting

Subscription quota out → Fallback to GLM/MiniMax
Add combo: cc/claude-opus-4-7 → glm/glm-5.1 → kr/claude-sonnet-4.5

OAuth token expired

Auto-refreshed by 9Router
If issues persist: Dashboard → Provider → Reconnect

High costs

Enable RTK in Dashboard → Endpoint settings (default ON, saves 20-40% tokens)
Check usage stats in Dashboard
Switch primary model to GLM/MiniMax
Use free tier (Kiro, OpenCode Free, Vertex) for non-critical tasks

Dashboard opens on wrong port

Set PORT=20128 and NEXT_PUBLIC_BASE_URL=http://localhost:20128

First login not working

Check INITIAL_PASSWORD in .env
If unset, fallback password is 123456

No request logs under logs/

Set ENABLE_REQUEST_LOGS=true

🛠️ Tech Stack

Runtime: Node.js 20+
Framework: Next.js 16
UI: React 19 + Tailwind CSS 4
Database: SQLite (better-sqlite3 / node:sqlite / sql.js fallback)
Streaming: Server-Sent Events (SSE)
Auth: OAuth 2.0 (PKCE) + JWT + API Keys

📝 API Reference

Chat Completions

POST http://localhost:20128/v1/chat/completions
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "cc/claude-opus-4-6",
  "messages": [
    {"role": "user", "content": "Write a function to..."}
  ],
  "stream": true
}

List Models

GET http://localhost:20128/v1/models
Authorization: Bearer your-api-key

→ Returns all models + combos in OpenAI format

📧 Support

Website: 9router.com
GitHub: github.com/decolua/9router
Issues: github.com/decolua/9router/issues

👥 Contributors

Thanks to all contributors who helped make 9Router better!

📊 Star Chart

🔀 Forks

OmniRoute — A full-featured TypeScript fork of 9Router. Adds 36+ providers, 4-tier auto-fallback, multi-modal APIs (images, embeddings, audio, TTS), circuit breaker, semantic cache, LLM evaluations, and a polished dashboard. 368+ unit tests. Available via npm and Docker.

🙏 Acknowledgments

Built on the shoulders of giants:

CLIProxyAPI(https://github.com/router-for-me/CLIProxyAPI) — original Go implementation that inspired this JavaScript port.
RTK — Rust token-saver. 9Router ports its compression pipeline to JS → −20-40% input tokens on every request.
Caveman by @JuliusBrussee — viral "why use many token when few token do trick". 9Router adapts its prompt → −65% output tokens.

Huge thanks to these authors — without their work, 9Router's token-saving features wouldn't exist. ⭐ them on GitHub!

📄 License

MIT License - see LICENSE for details.

_{Built with ❤️ for developers who code 24/7}

outsourc-e/hermes-workspace

Native web workspace for Hermes Agent — chat, terminal, memory, skills, inspector.

Hermes Workspace

Your AI agent's command center — chat, files, memory, skills, and terminal in one place.

Not a chat wrapper. A complete workspace — orchestrate agents, browse memory, manage skills, and control everything from one interface.

v2 — zero-fork. Clone, don't fork. Runs on vanilla NousResearch/hermes-agent installed via Nous's own installer. Chat, sessions, memory, skills, jobs, MCP, terminal, dashboard, Agent View, and Operations are all in vanilla parity. Conductor uses the dashboard mission API when available and falls back to Workspace-native Swarm dispatch (mode: native-swarm) when the dashboard endpoint is absent, preserving zero-fork behavior (#262).

Swarm Mode

Hermes Agent Swarm turns the workspace into a live control plane: unlimited Hermes Agents, 1 orchestrator, 0 humans manually dispatching. Persistent tmux workers keep context across tasks, rotate safely, and report proof-bearing checkpoints. Role-based dispatch routes builders, reviewers, docs, research, ops, triage, QA, and lab lanes without turning Eric into the task router. A byte-verified review gate protects release branches before PRs ship. Autonomous PR/issue lanes, lab experiments, and the repair playbook keep the machine moving while humans handle judgment.

Start here: docs/swarm/

Orchestrator Chat — ask the control plane for one task, a decomposed mission, or a full broadcast.
Multi-Agent Control Plane — see persistent Hermes Agents, roles, state, runtime, and routing wires in one surface.
Kanban TaskBoard — plan backlog, ready, running, review, blocked, and done lanes without leaving the workspace.
Reports + Inbox — review checkpoints, blockers, handoffs, and ready-for-human decisions.
TUI View built in — attach to tmux-backed workers or fall back to a live shell/log stream.

✨ What's inside

💬 Chat — Real-time SSE streaming, tool call rendering, multi-session, markdown + syntax highlighting
🧠 Memory — Browse, search, and edit agent memory; markdown live editor
🧩 Skills — Browse 2,000+ skills with origin badges, filters, source paths, marketplace
🔌 MCP — Full /mcp page (catalog + marketplace + sources), or fallback to local config CRUD
📁 Files + Terminal — Full workspace file browser with Monaco; cross-platform PTY terminal
🎮 Operations — Multi-agent dashboard with profile presets (Sage/Trader/Builder/Scribe/Ops) and 'Needs setup' detection
📡 Conductor — Mission dispatch + decomposition with dashboard-backed missions when available and Workspace-native Swarm fallback otherwise
👥 Agent View — Live agent panel in chat with avatar, queue, history, usage meter
🐝 Swarm Mode — Persistent tmux-backed Hermes Agent workers with role-based dispatch
🗄️ Dashboard — Aggregated overview: sessions, model mix, cost ledger, attention card, ops strip
🎨 Themes — Hermes, Nous, Bronze, Slate, Mono (light + dark)
🔒 Security — Auth middleware on every route, CSP, path-traversal guard, fail-closed remote bind
📱 PWA + Tailscale — Install as a native-feeling app; access from any device on your tailnet
⚙️ Capability gates — Features that need upstream endpoints (Conductor) show a clean placeholder instead of failing mid-action

📸 Screenshots

Chat	Conductor

Dashboard	Memory

Terminal	Settings

Tasks	Jobs

🚀 Quick Start

Three paths — pick the one that matches you:

Path	Best for	Time
🐳 Docker Compose	Self-hosters, home labs, "give me a compose gig"	~2 min
🌐 One-line install	Local dev on macOS/Linux	~3 min
🔌 Attach to existing `hermes-agent`	You already run Hermes Agent	~1 min

One-line install

curl -fsSL https://raw.githubusercontent.com/outsourc-e/hermes-workspace/main/install.sh | bash

This installs hermes-agent via Nous's official installer, clones this repo, sets up .env, and installs dependencies. Then:

hermes gateway run                  # terminal 1
cd ~/hermes-workspace && pnpm dev   # terminal 2

Open http://localhost:3000. That's it.

Already running `hermes-agent`? Attach the workspace to it

If you already have hermes-agent installed (via Nous's official installer, a source checkout, systemd, Docker, or another existing setup) and it's serving the gateway at http://<host>:8642, you don't need to reinstall anything — just point the workspace at it.

git clone https://github.com/outsourc-e/hermes-workspace.git
cd hermes-workspace
pnpm install
cp .env.example .env

# Point at your existing Hermes Agent services.
echo 'HERMES_API_URL=http://127.0.0.1:8642' >> .env
# Zero-fork installs also need the separate dashboard API for config/sessions/skills/jobs.
echo 'HERMES_DASHBOARD_URL=http://127.0.0.1:9119' >> .env

# If your gateway was started with API_SERVER_KEY (auth enabled), set the same value:
# echo 'HERMES_API_TOKEN=***' >> .env

pnpm dev                            # http://localhost:3000 (override with PORT=4000 pnpm dev)

Requirements on the agent side:

Gateway bound to an address the workspace can reach (typically API_SERVER_HOST=0.0.0.0 + the port exposed).
API_SERVER_ENABLED=true in ~/.hermes/.env (or the agent's env) so the gateway serves core APIs on :8642.
hermes dashboard running (default http://127.0.0.1:9119) for zero-fork installs. The dashboard provides config, sessions, skills, and jobs APIs.
If API_SERVER_KEY is set, the workspace must pass the same value via HERMES_API_TOKEN — otherwise leave both unset.

Verify both services before opening the workspace:

curl http://127.0.0.1:8642/health should return ok.
curl http://127.0.0.1:9119/api/status should return dashboard metadata.

Then start the workspace and complete onboarding — it should detect the gateway + dashboard pair and unlock the enhanced panes automatically.

Running on a remote host (Tailscale / VPN / LAN)

If the workspace and its browser live on different machines — e.g. the workspace runs on a Pi/Mac/home server and you access it from your phone over Tailscale — point HERMES_API_URL at the reachable backend address, not 127.0.0.1:

# On the server running the workspace + gateway:
echo 'HERMES_API_URL=http://100.x.y.z:8642' >> .env
echo 'HERMES_DASHBOARD_URL=http://100.x.y.z:9119' >> .env

# Also tell the gateway to listen on all interfaces so Tailscale peers can reach it.
# In ~/.hermes/.env (or wherever the gateway reads config):
echo 'API_SERVER_HOST=0.0.0.0' >> ~/.hermes/.env

Then restart the gateway, dashboard, and workspace. Hit the workspace from the remote device and the connection probe will use the Tailscale IP instead of localhost. Both HERMES_API_URL and HERMES_DASHBOARD_URL must be set to Tailscale/LAN-reachable URLs — setting only one will leave the other probing 127.0.0.1 and failing.

If you've already started the workspace, you can update both URLs from Settings → Connection without restarting. The values are persisted to ~/.hermes/workspace-overrides.json and take effect immediately (gateway capabilities are reprobed on save). Editing .env still works for pre-start config and for CI/containers.

Manual install

Hermes Workspace works with any OpenAI-compatible backend. If your backend also exposes Hermes Agent gateway APIs, enhanced features like sessions, memory, skills, and jobs unlock automatically.

Prerequisites

Node.js 22+ — nodejs.org
An OpenAI-compatible backend — local, self-hosted, or remote
Optional: Python 3.11+ if you want to run a Hermes Agent gateway locally

Step 1: Start your backend

Point Hermes Workspace at any backend that supports:

POST /v1/chat/completions
GET /v1/models recommended

Example Hermes Agent gateway setup (from scratch):

# Install hermes-agent via Nous's official installer
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# Configure a provider + start the gateway
hermes setup
hermes gateway run

Our one-liner installer (below) does both steps automatically. If you're using another OpenAI-compatible server, just note its base URL.

Step 2: Install & Run Hermes Workspace

# In a new terminal
git clone https://github.com/outsourc-e/hermes-workspace.git
cd hermes-workspace
pnpm install
cp .env.example .env
printf '\nHERMES_API_URL=http://127.0.0.1:8642\n' >> .env
pnpm dev                   # Starts on http://localhost:3000

Verify: Open http://localhost:3000 and complete the onboarding flow. First connect the backend, then verify chat works. If your gateway exposes Hermes Agent APIs, advanced features appear automatically.

Environment Variables

# OpenAI-compatible backend URL
HERMES_API_URL=http://127.0.0.1:8642

# Optional: provider keys the Hermes Agent gateway can read at runtime.
# You only need the key(s) for whichever provider(s) you actually use.
# OPENAI_API_KEY=sk-...                # GPT / o-series / OpenAI-compatible
# OPENROUTER_API_KEY=sk-or-v1-...      # OpenRouter (incl. free models)
# GOOGLE_API_KEY=AIza...               # Gemini
# (Ollama / LM Studio / local servers don't need a key)

# Optional: password-protect the web UI
# HERMES_PASSWORD=your_password

🧠 Local Models (Ollama, Atomic Chat, LM Studio, vLLM)

Hermes Workspace supports two modes with local models:

Portable Mode (Easiest)

Point the workspace directly at your local server — no Hermes Agent gateway needed.

Atomic Chat

# Start workspace pointed at Atomic Chat
HERMES_API_URL=http://127.0.0.1:1337/v1 pnpm dev

Download Atomic Chat, launch the desktop app, and make sure a model is loaded before starting Hermes Workspace.

Ollama

# Start Ollama
OLLAMA_ORIGINS=* ollama serve

# Start workspace pointed at Ollama
HERMES_API_URL=http://127.0.0.1:11434 pnpm dev

Chat works immediately. Sessions, memory, and skills show "Not Available" — that's expected in portable mode.

Enhanced Mode (Full Features)

Route through the Hermes Agent gateway for sessions, memory, skills, jobs, and tools.

Here are two explicit ~/.hermes/config.yaml examples for the local providers we support directly in the workspace:

Atomic Chat

provider: atomic-chat
model: your-model-name
custom_providers:
  - name: atomic-chat
    base_url: http://127.0.0.1:1337/v1
    api_key: atomic-chat
    api_mode: chat_completions

Ollama

provider: ollama
model: qwen3:32b
custom_providers:
  - name: ollama
    base_url: http://127.0.0.1:11434/v1
    api_key: ollama
    api_mode: chat_completions

You can adapt the same shape for other OpenAI-compatible local runners, but Atomic Chat and Ollama are the two built-in local paths documented in the workspace UI.

2. Enable the API server in ~/.hermes/.env:

API_SERVER_ENABLED=true

3. Start the gateway, dashboard, and workspace:

hermes gateway run          # Starts core APIs on :8642
hermes dashboard            # Starts dashboard APIs on :9119
HERMES_API_URL=http://127.0.0.1:8642 \
HERMES_DASHBOARD_URL=http://127.0.0.1:9119 \
pnpm dev

For authenticated gateways, also set HERMES_API_TOKEN in the workspace environment to the same value as API_SERVER_KEY.

All workspace features unlock automatically once both services are reachable — sessions persist, memory saves across chats, skills are available, and the dashboard shows real usage data.

Works with any OpenAI-compatible server — Atomic Chat, Ollama, LM Studio, vLLM, llama.cpp, LocalAI, etc. Just change the base_url and model in the config above.

🤝 Pair an Agent with the Workspace

Workspace is the UI. Hermes Agent is the brain. They talk over two HTTP services on localhost (or any reachable network).

┌───────────────┐         :8642 gateway          ┌────────────────┐
│   Workspace    │ ─────────────────────▶ │  Hermes Agent  │
│   :3000 (UI)   │ ◀───────────────────── │  CLI / brain   │
└───────────────┘         :9119 dashboard        └────────────────┘

Two services, three commands

hermes gateway run     # terminal 1 · :8642 · chat, models, streaming, jobs
hermes dashboard       # terminal 2 · :9119 · sessions, skills, config, MCP
cd ~/hermes-workspace && pnpm dev   # terminal 3 · :3000 · the UI

Tip: pnpm start:all starts gateway + dashboard + workspace in one shot if you've installed via the one-liner.

Windows (PowerShell + WSL) one-command startup

If you use Hermes Workspace from Windows with the agent running in WSL, use the helper script in this repo:

# from the repo root
.\scripts\start-hermes-workspace.ps1

To force a clean relaunch of the tmux session:

.\scripts\start-hermes-workspace.ps1 -Restart

Optional parameters:

-Distro <name> to target a non-default WSL distro
-WorkspacePath </path/in/wsl> if your clone is not at ~/hermes-workspace
-SessionName <name> to use a custom tmux session name

Verify the pairing

curl http://127.0.0.1:8642/health        # → {"status":"ok","platform":"hermes-agent"}
curl http://127.0.0.1:9119/api/status    # → {"status":"ok", ...}

Both must return 200. If either fails, the workspace will fall back to portable mode (chat works, sessions/skills/memory show "Not Available").

`.env` settings the workspace cares about

# Required: where the gateway is
HERMES_API_URL=http://127.0.0.1:8642

# Recommended: where the dashboard is (unlocks sessions/skills/config/MCP/jobs)
HERMES_DASHBOARD_URL=http://127.0.0.1:9119

# Only if your gateway was started with API_SERVER_KEY=... — paste the same value:
# HERMES_API_TOKEN=***

# Optional: password-protect the web UI itself
# HERMES_PASSWORD=***

Common pairing scenarios

Scenario	Set this
Workspace + gateway on the same machine	`HERMES_API_URL=http://127.0.0.1:8642`, `HERMES_DASHBOARD_URL=http://127.0.0.1:9119`
Gateway on a remote server (Tailscale / VPN)	Set both URLs to the reachable IP (e.g. `http://100.x.y.z:8642`) and add `API_SERVER_HOST=0.0.0.0` to the gateway's `~/.hermes/.env`
Already-running `hermes-agent` from upstream installer	Just set `HERMES_API_URL` + `HERMES_DASHBOARD_URL` and skip the one-liner installer
Multiple agent profiles	Profiles live under `~/.hermes/profiles/<name>` — the dashboard switches between them at runtime; workspace follows automatically

Live re-pairing (no restart)

If you've already started the workspace, change either URL from Settings → Connection without restarting. Values persist to ~/.hermes/workspace-overrides.json and gateway capabilities are reprobed on save.

Troubleshooting

Could not reach Hermes gateway on 8645, 8642, or 8643 — gateway isn't running, or HERMES_API_URL points somewhere unreachable. Run hermes gateway run and re-check.
Workspace shows "portable mode" / extended APIs missing — dashboard isn't running. Start hermes dashboard in another terminal and refresh.
Unauthorized on every API call — gateway has API_SERVER_KEY set but workspace is missing HERMES_API_TOKEN. Match them.
Could not connect from your phone over Tailscale — gateway is bound to loopback. Set API_SERVER_HOST=0.0.0.0 in ~/.hermes/.env and restart it.

🐳 Docker Quickstart

The Docker setup runs both the Hermes Agent gateway and Hermes Workspace together.

Prerequisites

Docker
Docker Compose
A configured Hermes Agent model provider — run hermes setup / hermes model, or provide a key for whichever provider you use. This workspace does not require Anthropic.

Step 1: Configure Environment

git clone https://github.com/outsourc-e/hermes-workspace.git
cd hermes-workspace
cp .env.example .env

Edit .env and add at least one LLM provider key — whichever provider you want hermes-agent to use:

# Pick one (or more). You do NOT need all of these.
# OPENAI_API_KEY=sk-...                # GPT / o-series / OpenAI-compatible
# OPENROUTER_API_KEY=sk-or-v1-...      # OpenRouter (free models available)
# GOOGLE_API_KEY=AIza...               # Gemini

Using Ollama, LM Studio, or another local server? No key needed — just point hermes-agent at your local endpoint via the onboarding flow.

Heads up: hermes-agent needs to be able to reach some model. If you don't configure any provider (API key or local server), chat will fail on first message.

Step 2: Start the Services

docker compose up

This pulls two pre-built images and starts them:

hermes-agent → nousresearch/hermes-agent:latest on port 8642
hermes-workspace → ghcr.io/outsourc-e/hermes-workspace:latest on port 3000

No local build. First run takes a minute to pull; subsequent starts are instant. Agent state (config, sessions, skills, memory, credentials) persists in the legacy-named claude-data Docker volume, so containers can be recreated without data loss.

Step 3: Access the Workspace

Open http://localhost:3000 and complete the onboarding.

Verify: Check the Docker logs for [gateway] Connected to Hermes Agent — this confirms the workspace successfully connected to the agent.

Building from source

Want to hack on the workspace and have local changes hot-built into the container? Use the dev overlay:

docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

The base docker-compose.yml stays untouched — the overlay adds a build: block for the hermes-workspace service so the local repo is compiled instead of pulled. The Hermes Agent service still uses the canonical nousresearch/hermes-agent:latest image; if you need a custom agent build, tag it locally and override image: in your own compose.override.yml.

Using a Pre-Built Image (Coolify / Easypanel / Dokploy / Unraid)

Deploying Hermes Workspace to a PaaS or home-lab stack? Pull the image directly from GitHub Container Registry:

ghcr.io/outsourc-e/hermes-workspace:latest

Available tags:

Tag	What it is
`latest`	Latest `main` commit (stable; recommended)
`v2.0.0`	Pinned semver tag
`main-<sha>`	Specific commit

Minimal Coolify / Easypanel config:

service: hermes-workspace
image: ghcr.io/outsourc-e/hermes-workspace:latest
port: 3000
env:
  HERMES_API_URL: http://hermes-agent:8642   # point at your gateway
  HERMES_API_TOKEN: ${API_SERVER_KEY}        # if gateway auth is enabled

The image is built for linux/amd64 and linux/arm64. Pair it with either a nousresearch/hermes-agent:latest container (what our docker-compose.yml does by default) or an existing gateway on another host.

📱 Install as App (Recommended)

Hermes Workspace is a Progressive Web App (PWA) — install it for the full native app experience with no browser chrome, keyboard shortcuts, and offline support.

🖥️ Desktop (macOS / Windows / Linux)

Open Hermes Workspace in Chrome or Edge at http://localhost:3000
Click the install icon (⊕) in the address bar
Click Install — Hermes Workspace opens as a standalone desktop app
Pin to Dock / Taskbar for quick access

macOS users: After installing, you can also add it to your Launchpad.

📱 iPhone / iPad (iOS Safari)

Open Hermes Workspace in Safari on your iPhone
Tap the Share button (□↑)
Scroll down and tap "Add to Home Screen"
Tap Add — the Hermes Workspace icon appears on your home screen
Launch from home screen for the full native app experience

🤖 Android

Open Hermes Workspace in Chrome on your Android device
Tap the three-dot menu (⋮) → "Add to Home screen"
Tap Add — Hermes Workspace is now a native-feeling app on your device

📡 Mobile Access via Tailscale

Access Hermes Workspace from anywhere on your devices — no port forwarding, no VPN complexity.

Setup

Install Tailscale on your Mac and mobile device:
- Mac: tailscale.com/download
- iPhone/Android: Search "Tailscale" in the App Store / Play Store
Sign in to the same Tailscale account on both devices

Find your Mac's Tailscale IP:

tailscale ip -4
# Example output: 100.x.x.x

Open Hermes Workspace on your phone:
```
http://100.x.x.x:3000
```
Add to Home Screen using the steps above for the full app experience

💡 Tailscale works over any network — home wifi, mobile data, even across countries. Your traffic stays end-to-end encrypted.

🖥️ Native Desktop App

Status: In Development — A native Electron-based desktop app is in active development.

The desktop app will offer:

Native window management and tray icon
System notifications for agent events and mission completions
Auto-launch on startup
Deep OS integration (macOS menu bar, Windows taskbar)

In the meantime: Install Hermes Workspace as a PWA (see above) for a near-native desktop experience — it works great.

☁️ Cloud & Hosted Setup

Status: Coming Soon

A fully managed cloud version of Hermes Workspace is in development:

One-click deploy — No self-hosting required
Multi-device sync — Access your agents from any device
Team collaboration — Shared mission control for your whole team
Automatic updates — Always on the latest version

Features pending cloud infrastructure:

Cross-device session sync
Team shared memory and workspaces
Cloud-hosted backend with managed uptime
Webhook integrations and external triggers

🔒 Security & deployment env vars

Key safeguards — most are on by default, the env vars below are for remote / Docker deployments where you opt out of the loopback default.

Built-in safeguards

Auth middleware on every API route
CSP headers via meta tags
Path-traversal prevention on file/memory routes (real-path boundary check, not string prefix)
Rate limiting on endpoints
Fail-closed startup guard: refuses to bind non-loopback without HERMES_PASSWORD
Session cookies: HttpOnly + SameSite=Strict + Secure (in production)
Optional password protection for the web UI

Env vars for remote / Docker deployments

HERMES_PASSWORD — required whenever HOST ≠ 127.0.0.1 (legacy CLAUDE_PASSWORD still honored as a fallback)
COOKIE_SECURE=1 — force the Secure cookie flag when terminating HTTPS at a proxy
COOKIE_SECURE=0 — disable the Secure flag for plain-HTTP LAN deployments (HOST=0.0.0.0 without HTTPS); without this, browsers silently drop session cookies and login fails (#149)
TRUST_PROXY=1 — trust x-forwarded-for / x-real-ip (only set behind a sanitizing reverse proxy)
HERMES_DASHBOARD_TOKEN — explicit bearer for dashboard API (preferred over the legacy HTML-scrape fallback)
HERMES_API_TOKEN — bearer for the Hermes Agent gateway when started with API_SERVER_KEY (legacy CLAUDE_API_TOKEN still honored)
HERMES_ALLOW_INSECURE_REMOTE=1 — bypass the fail-closed guard (not recommended)

See .env.example for the full list. Credits to @kiosvantra for the security audit surfacing #121–#125.

🔧 Troubleshooting

"Workspace loads but chat doesn't work"

The workspace auto-detects your gateway's capabilities on startup. Check your terminal for a line like:

[gateway] http://127.0.0.1:8642 available: health, models; missing: sessions, skills, memory, config, jobs
[gateway] Missing Hermes Agent APIs detected. Update hermes-agent to the latest version.

Fix: Upgrade to the latest stock hermes-agent, which ships the extended endpoints:

cd ~/hermes-agent && git pull && uv pip install -e .
hermes gateway run

(If you installed via a different path, follow your Nous installer's upgrade instructions.) If you were on the old outsourc-e/hermes-agent fork, it's no longer needed as of v2 — uninstall it and use upstream instead.

"Connection refused" or workspace hangs on load

Your Hermes Agent gateway isn't running. Start it:

hermes gateway run

First-time run? Do hermes setup first to pick a provider and model.

Ollama: chat returns empty or model shows "Offline"

Make sure your ~/.hermes/config.yaml has the custom_providers section and API_SERVER_ENABLED=true in ~/.hermes/.env. See Local Models above.

Also ensure Ollama is running with CORS enabled:

OLLAMA_ORIGINS=* ollama serve

Use http://127.0.0.1:11434/v1 (not localhost) as the base URL.

Verify: curl http://localhost:8642/health should return {"status": "ok"}.

"Using upstream NousResearch/hermes-agent"

v2+ runs on vanilla hermes-agent. No fork required. The upstream ships every endpoint the workspace needs for chat, sessions, memory, skills, config, jobs, MCP, terminal, and Agent View.

Conductor note: when the dashboard mission API is available, Workspace uses it directly. When that endpoint is absent, Workspace uses its native Swarm fallback and returns mode: native-swarm. The fallback dispatches through Workspace Swarm workers, keeps status available through /api/conductor-spawn?missionId=..., and cancels through /api/conductor-stop.

If you're pinned to an older hermes-agent version and missing core endpoints, the workspace will degrade gracefully to portable mode with basic chat — upgrade upstream to restore full features.

Docker: "Unauthorized" or "Connection refused" to hermes-agent

If using Docker Compose and getting auth errors:

Check at least one provider key is set:

grep -E '_API_KEY' .env
# Should show one of: OPENAI_API_KEY, OPENROUTER_API_KEY, GOOGLE_API_KEY, or another provider key you intentionally use.

(hermes-agent reads whichever key matches the provider configured in ~/.hermes/config.yaml.)

View the agent container logs:
```
docker compose logs hermes-agent
```
Look for startup errors or missing API key warnings.

Verify the agent health endpoint:

curl http://localhost:8642/health
# Should return: {"status": "ok"}

Restart with fresh containers:

docker compose down
docker compose up --build

Check workspace logs for gateway status:
```
docker compose logs hermes-workspace
```
Look for: [gateway] http://hermes-agent:8642 mode=... — if it shows mode=disconnected, the agent isn't running correctly.

Docker: older `claude webapi` docs are wrong

The claude webapi command referenced in some pre-rename docs doesn't exist. The correct commands are:

hermes gateway run    # FastAPI gateway on :8642
hermes dashboard      # dashboard plugin on :9119 (sessions/skills/jobs/config)

The Docker setup runs both automatically — no action needed if using docker compose up.

🗺️ Roadmap

Shipped ✅

Feature	What it does
Chat + SSE streaming	Live agent output with tool call rendering
Files + Terminal	Full workspace file browser + cross-platform PTY
Memory + Skills browsers	Edit memory, browse 2,000+ skills with marketplace
Dashboard	Sessions, model mix, cost ledger, attention card
Operations	Multi-agent management with preset personas
Agent View	Live agent panel in chat
Swarm Mode	Persistent tmux-backed worker pool with role dispatch
MCP page	Full catalog + marketplace + sources
Mobile PWA + Tailscale	Install as native-feeling app on any device
Themes	Hermes / Nous / Bronze / Slate / Mono (light + dark)
Capability gates	Graceful 'upstream not ready' placeholders
Multi-provider	OpenAI/OpenAI-compatible, OpenRouter, Google, Ollama, LM Studio, vLLM, Atomic Chat, and other Hermes-supported providers

In progress 🔨

Feature	Status
Conductor missions	Workspace UI is shipped; uses dashboard mission API when available and Workspace-native Swarm fallback otherwise (see #262)
Native Desktop App (Electron)	Spec'd; PWA install path works today

Coming 🔜

Feature	Status
Cloud / Hosted version	Pending infra
Team collaboration	Pending cloud + multi-tenant work

⭐ Star History

💛 Support the Project

Hermes Workspace is free and open source. If it's saving you time and powering your workflow, consider supporting development:

ETH: 0xB332D4C60f6FBd94913e3Fd40d77e3FE901FAe22

Every contribution helps keep this project moving. Thank you 🙏

🤝 Contributing

PRs are welcome! See CONTRIBUTING.md for guidelines.

Bug fixes → open a PR directly
New features → open an issue first to discuss
Security issues → see SECURITY.md for responsible disclosure

📄 License

MIT — see LICENSE for details.

_{Built with ⚡ by @outsourc-e and the Hermes Workspace community}

jo-inc/camofox-browser

Stealth headless browser for AI agents — bypass Cloudflare, bot detection, and anti-scraping. Drop-in Puppeteer/Playwright replacement.

camofox-browser

Anti-detection browser server for AI agents, powered by Camoufox

Standing on the mighty shoulders of Camoufox - a Firefox fork with fingerprint spoofing at the C++ level.

Built by the team behind jo, a personal AI agent that runs half on your Mac, half on a dedicated cloud machine just for you -- with zero maintenance needed. Available on macOS, Telegram, WhatsApp, and email. Try the beta free ->

git clone https://github.com/jo-inc/camofox-browser && cd camofox-browser
npm install && npm start
# -> http://localhost:9377

Why

AI agents need to browse the real web. Playwright gets blocked. Headless Chrome gets fingerprinted. Stealth plugins become the fingerprint.

Camoufox patches Firefox at the C++ implementation level - navigator.hardwareConcurrency, WebGL renderers, AudioContext, screen geometry, WebRTC - all spoofed before JavaScript ever sees them. No shims, no wrappers, no tells.

This project wraps that engine in a REST API built for agents: accessibility snapshots instead of bloated HTML, stable element refs for clicking, and search macros for common sites.

Features

C++ Anti-Detection - bypasses Google, Cloudflare, and most bot detection
Element Refs - stable e1, e2, e3 identifiers for reliable interaction
Token-Efficient - accessibility snapshots are ~90% smaller than raw HTML
Runs on Anything - lazy browser launch + idle shutdown keeps memory at ~40MB when idle. Designed to share a box with the rest of your stack -- Raspberry Pi, $5 VPS, shared infra.
Session Isolation - separate cookies/storage per user
Cookie Import - inject Netscape-format cookie files for authenticated browsing
Proxy + GeoIP - route traffic through residential proxies with automatic locale/timezone
Structured Logging - JSON log lines with request IDs for production observability
YouTube Transcripts - extract captions from any YouTube video via yt-dlp, no API key needed
Search Macros - @google_search, @youtube_search, @amazon_search, @reddit_subreddit, and 10 more
Snapshot Screenshots - include a base64 PNG screenshot alongside the accessibility snapshot
Large Page Handling - automatic snapshot truncation with offset-based pagination
Download Capture - capture browser downloads and fetch them via API (optional inline base64)
DOM Image Extraction - list <img> src/alt and optionally return inline data URLs
Deploy Anywhere - Docker, Fly.io, Railway
VNC Interactive Login - log into sites visually via noVNC, export storage state for agent reuse
OpenAPI Docs - auto-generated spec at /openapi.json and interactive docs at /docs
Structured Extract - POST /tabs/:tabId/extract with a JSON Schema that maps properties to snapshot refs via x-ref
Session Tracing - opt-in per-session Playwright trace capture (screenshots + DOM snapshots + network) with API endpoints to list, fetch, and delete trace zips
Telemetry - automatic anonymized crash/hang telemetry via GitHub Issues. Identifies which sites cause failures and common failure patterns. Private domains are HMAC-hashed, paths/params stripped, tokens/IPs redacted. Opt-out with CAMOFOX_CRASH_REPORT_ENABLED=false.

Optional Dependencies

Dependency	Purpose	Install
yt-dlp	YouTube transcript extraction (fast path)	`pip install yt-dlp` or `brew install yt-dlp`

The Docker image includes yt-dlp. For local dev, install it for the /youtube/transcript endpoint. Without it, the endpoint falls back to a slower browser-based method.

Quick Start

OpenClaw Plugin

openclaw plugins install @askjo/camofox-browser

Standalone

git clone https://github.com/jo-inc/camofox-browser
cd camofox-browser
npm install
npm start  # downloads Camoufox on first run (~300MB)

Default port is 9377. See Environment Variables for all options.

Note: the postinstall script unsets PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD for itself before fetching the Camoufox binary. Without that override, an exported PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 (common when Playwright is configured to use system Chrome) would silently skip the binary download and crash the server at runtime.

External Camoufox executable: set CAMOUFOX_EXECUTABLE=/path/to/camoufox-bin before npm install and when starting the server to skip the bundled download and launch that executable. Compatibility aliases are CAMOUFOX_EXECUTABLE_PATH and CAMOFOX_EXECUTABLE_PATH. This is useful for NixOS paths such as /nix/store/.../camoufox-bin; the executable must come from a Camoufox bundle that includes properties.json, version.json, and fontconfig/.

Air-gapped or custom binary management: prefer CAMOUFOX_EXECUTABLE when you already have a Camoufox bundle. Otherwise disable the auto-fetch with npm install --ignore-scripts (skips lifecycle scripts for every dependency -- bluntest option) or, more surgically, npm install --omit=optional plus a manual npx camoufox-js fetch step against your mirror. Note that PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm install no longer skips the Camoufox download (the postinstall sanitizes the env locally); use --ignore-scripts or CAMOUFOX_EXECUTABLE for that.

Docker

The included Makefile auto-detects your CPU architecture and pre-downloads Camoufox + yt-dlp binaries outside the Docker build, so rebuilds are fast (~30s vs ~3min).

# Build and start (auto-detects arch: aarch64 on M1/M2, x86_64 on Intel)
make up

# Stop and remove the container
make down

# Force a clean rebuild (e.g. after upgrading VERSION/RELEASE)
make reset

# Just download binaries (without building)
make fetch

# Override arch or version explicitly
make up ARCH=x86_64
make up VERSION=135.0.1 RELEASE=beta.24

WARNING: Do not run docker build directly. The Dockerfile uses bind mounts to pull pre-downloaded binaries from dist/. Always use make up (or make fetch then make build) -- it downloads the binaries first.

Fly.io

For Fly.io or other remote CI, you'll need a Dockerfile that downloads binaries at build time instead of using bind mounts.

Railway

A railway.toml is included. It uses Dockerfile.ci (which downloads binaries at build time) and maps Railway's PORT env var to CAMOFOX_PORT automatically.

# Install Railway CLI, then:
railway link
railway up

Set secrets via the Railway dashboard or CLI:

railway variables set CAMOFOX_API_KEY="your-generated-key"

Usage

Cookie Import

Import cookies from your browser into Camoufox to skip interactive login on sites like LinkedIn, Amazon, etc.

Setup

1. Generate a secret key:

# macOS / Linux
openssl rand -hex 32

2. Set the environment variable before starting OpenClaw:

export CAMOFOX_API_KEY="your-generated-key"
openclaw start

The same key is used by both the plugin (to authenticate requests) and the server (to verify them). Both run from the same environment -- set it once.

Why an env var? The key is a secret. Plugin config in openclaw.json is stored in plaintext, so secrets don't belong there. Set CAMOFOX_API_KEY in your shell profile, systemd unit, Docker env, or Fly.io secrets.

Cookie import is disabled by default. If CAMOFOX_API_KEY is not set, the server rejects all cookie requests with 403.

3. Export cookies from your browser:

Install a browser extension that exports Netscape-format cookie files (e.g., "cookies.txt" for Chrome/Firefox). Export the cookies for the site you want to authenticate.

4. Place the cookie file:

mkdir -p ~/.camofox/cookies
cp ~/Downloads/linkedin_cookies.txt ~/.camofox/cookies/linkedin.txt

The default directory is ~/.camofox/cookies/. Override with CAMOFOX_COOKIES_DIR.

5. Ask your agent to import them:

Import my LinkedIn cookies from linkedin.txt

The agent calls camofox_import_cookies -> reads the file -> POSTs to the server with the Bearer token -> cookies are injected into the browser session. Subsequent camofox_create_tab calls to linkedin.com will be authenticated.

How it works

~/.camofox/cookies/linkedin.txt          (Netscape format, on disk)
        |
        v
camofox_import_cookies tool              (parses file, filters by domain)
        |
        v  POST /sessions/:userId/cookies
        |  Authorization: Bearer <CAMOFOX_API_KEY>
        |  Body: { cookies: [Playwright cookie objects] }
        v
camofox server                           (validates, sanitizes, injects)
        |
        v  context.addCookies(...)
        |
Camoufox browser session                 (authenticated browsing)

cookiesPath is resolved relative to the cookies directory -- path traversal outside it is blocked
Max 500 cookies per request, 5MB file size limit
Cookie objects are sanitized to an allowlist of Playwright fields

Session Persistence

By default, camofox persists each user's cookies and localStorage to ~/.camofox/profiles/. Sessions survive browser restarts -- log in once (via cookies or VNC), and subsequent sessions restore the authenticated state automatically.

~/.camofox/
|-- cookies/          # Bootstrap cookie files (Netscape format)
\-- profiles/         # Persisted session state (auto-managed)
    \-- <hashed-userId>/
        \-- storage_state.json

Override the directory with CAMOFOX_PROFILE_DIR or set "profileDir" in the persistence plugin config. To disable persistence, set "persistence": { "enabled": false } in camofox.config.json.

Session Tracing

Capture a Playwright trace of every action in a session: page screenshots, DOM snapshots, network requests, and console output. Output is a single .zip file you can open in Playwright's built-in Trace Viewer.

Opt-in per session by passing trace: true when opening the first tab:

curl -X POST http://localhost:9377/tabs \
  -H 'Content-Type: application/json' \
  -d '{"userId":"agent1","sessionKey":"task1","url":"https://example.com","trace":true}'

The trace is written when the session closes. Close the session to flush it, then list, fetch, and view:

# Close the session to flush the trace
curl -X DELETE http://localhost:9377/sessions/agent1

# List trace files
curl http://localhost:9377/sessions/agent1/traces
# {"traces":[{"filename":"trace-2026-04-18T04-05-00-...zip","sizeBytes":42810,"createdAt":...}]}

# Download (Content-Type: application/zip)
curl http://localhost:9377/sessions/agent1/traces/trace-2026-04-18T04-05-00-abc.zip > session.zip

# View it in Playwright's Trace Viewer
npx playwright show-trace session.zip

# Delete
curl -X DELETE http://localhost:9377/sessions/agent1/traces/trace-2026-04-18T04-05-00-abc.zip

Why traces instead of video: Camoufox is Firefox-based, and Playwright's recordVideo is Chromium-only. Traces work on Firefox and give you more than video (network + DOM + console + screenshots).

Tracing cannot be toggled on an existing session. DELETE /sessions/:userId first if you need to change the flag.

Storage defaults to ~/.camofox/traces/<hashed-userId>/ and is swept on server startup:

CAMOFOX_TRACES_DIR - base directory (default: ~/.camofox/traces)
CAMOFOX_TRACES_MAX_BYTES - max size per trace, removed at next startup if exceeded (default: 50MB)
CAMOFOX_TRACES_TTL_HOURS - traces older than this are removed at next startup (default: 24)

Standalone server usage

curl -X POST http://localhost:9377/sessions/agent1/cookies \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_CAMOFOX_API_KEY' \
  -d '{"cookies":[{"name":"foo","value":"bar","domain":"example.com","path":"/","expires":-1,"httpOnly":false,"secure":false}]}'

Docker / Fly.io / Railway

docker run -p 9377:9377 \
  -e CAMOFOX_API_KEY="your-generated-key" \
  -v ~/.camofox/cookies:/home/node/.camofox/cookies:ro \
  camofox-browser

For Fly.io:

fly secrets set CAMOFOX_API_KEY="your-generated-key"

For Railway:

railway variables set CAMOFOX_API_KEY="your-generated-key"

Proxy + GeoIP

Route all browser traffic through a proxy with automatic locale, timezone, and geolocation derived from the proxy's IP address via Camoufox's built-in GeoIP.

Simple proxy (single endpoint):

export PROXY_HOST=166.88.179.132
export PROXY_PORT=46040
export PROXY_USERNAME=myuser
export PROXY_PASSWORD=mypass
npm start

Backconnect proxy (rotating sticky sessions):

For providers like Decodo, Bright Data, or Oxylabs that offer a single gateway endpoint with session-based sticky IPs:

export PROXY_STRATEGY=backconnect
export PROXY_BACKCONNECT_HOST=gate.provider.com
export PROXY_BACKCONNECT_PORT=7000
export PROXY_USERNAME=myuser
export PROXY_PASSWORD=mypass
npm start

Each browser context gets a unique sticky session, so different users get different IP addresses. Sessions rotate automatically on proxy errors or Google blocks.

Or in Docker:

docker run -p 9377:9377 \
  -e PROXY_HOST=166.88.179.132 \
  -e PROXY_PORT=46040 \
  -e PROXY_USERNAME=myuser \
  -e PROXY_PASSWORD=mypass \
  camofox-browser

When a proxy is configured:

All traffic routes through the proxy
Camoufox's GeoIP automatically sets locale, timezone, and geolocation to match the proxy's exit IP
Browser fingerprint (language, timezone, coordinates) is consistent with the proxy location
Without a proxy, defaults to en-US, America/Los_Angeles, San Francisco coordinates

Telemetry

Browser automation fails in ways that are hard to predict -- Cloudflare challenges, site redesigns breaking selectors, redirect loops, dialog storms, renderer crashes. The scope is wide and the failure modes are diverse. Without telemetry, the only signal is "it didn't work."

Telemetry gives us structured data on which sites fail, how they fail, and how often, so we can prioritize fixes for the patterns that actually affect users. It files GitHub Issues automatically when:

Uncaught exceptions crash the process
Event loop stalls exceed 5 seconds (watchdog detection)
Frustration patterns -- 3+ consecutive failures (timeout, dead context, navigation abort) on the same tab

Each report includes the failure type, stack trace, tab health counters (HTTP status histogram, console errors, request failures, redirect depth), and the target URL -- all anonymized.

How it works

Telemetry is sent to a lightweight Cloudflare Worker endpoint at https://camofox-telemetry.askjo.workers.dev. The endpoint holds the GitHub App credentials as environment secrets -- no secrets are shipped in this package.

lib/reporter.js (client, no secrets)
    |  anonymize -> POST https://camofox-telemetry.askjo.workers.dev/report
    v
Cloudflare Worker (holds GitHub App key)
    |  validate -> rate-limit -> dedup -> create GitHub Issue
    v
GitHub Issue created

The endpoint source code is in this repo at workers/crash-reporter/index.ts.

Verification

You don't have to trust us -- verify what the live endpoint is running:

# 1. Ask the endpoint what code it's running
curl https://camofox-telemetry.askjo.workers.dev/source
# -> { "commit": "abc1234", "sha256": "e3b0c44...", "source": "https://github.com/..." }

# 2. Compare the sha256 against the source in this repo
sha256sum workers/crash-reporter/index.ts

# 3. Check the commit matches what CI deployed
#    https://github.com/jo-inc/camofox-browser/actions/workflows/telemetry-deploy.yml
git log --oneline workers/crash-reporter/index.ts | head -1

If the hashes don't match, the endpoint is running different code than what's in the repo. The deploy workflow (.github/workflows/telemetry-deploy.yml) injects the commit and source hash at deploy time -- every deploy is auditable in GitHub Actions.

Or skip verification entirely: CAMOFOX_CRASH_REPORT_ENABLED=false disables all telemetry, or point to your own endpoint with CAMOFOX_CRASH_REPORT_URL.

Privacy

All reported data goes through paranoid anonymization (lib/reporter.js L28-290) before leaving the process:

URLs -- well-known public domains (Google, Amazon, Reddit, Cloudflare, etc.) are shown verbatim so we can identify which sites cause problems. Private/unknown domains are replaced with a stable HMAC hash (site-a1b2c3d4) -- same hash across reports for correlation, but not reversible to the original domain. Path segments become */*/* (depth only). Query params become ?[3] (count only). No keys, values, or path content is ever included.
File paths -> stripped to filename only (<path>/server.js)
Tokens, secrets, API keys -> <token>
IPs, emails, env vars -> redacted
Docker/Fly machine IDs -> <id>
Tab health -- pure counters (crash count, error count, status code histogram). No page content, no URLs, no user data.

Duplicate issues are detected by stack signature and get a +1 comment instead of a new issue.

# Disable telemetry
export CAMOFOX_CRASH_REPORT_ENABLED=false

# Point to your own endpoint (see below)
export CAMOFOX_CRASH_REPORT_URL=https://your-endpoint.example.com/report

# Adjust rate limit (default: 10 per hour)
export CAMOFOX_CRASH_REPORT_RATE_LIMIT=5

Self-hosted telemetry endpoint

To file telemetry reports in your own GitHub repo instead of jo-inc/camofox-browser:

Create a GitHub App -- Settings -> Developer settings -> GitHub Apps -> New
- Permissions: Repository -> Issues -> Read & Write
- Uncheck Webhook -> Active (not needed)
- Click Generate a key -- downloads a .pem file
- Install the app on your target repo (Install App -> select repo)
- Note your App ID (number on the app's General page) and Installation ID (from the URL after installing: github.com/settings/installations/{id})
Deploy the endpoint -- clone this repo and deploy the worker:
```
cd workers/crash-reporter
# Edit wrangler.toml: set account_id to your Cloudflare account ID
npx wrangler deploy
```
The worker is a single TypeScript file with zero npm dependencies. It also runs on Deno, Bun, or any runtime with the Web Crypto API.

Set worker secrets:

cd workers/crash-reporter
echo "YOUR_APP_ID" | npx wrangler secret put GH_APP_ID
echo "YOUR_INSTALL_ID" | npx wrangler secret put GH_INSTALL_ID
# Key must be PKCS#8 DER base64 (not raw PEM)
openssl pkcs8 -topk8 -inform PEM -outform DER -nocrypt -in your-app.pem | \
  base64 | tr -d '\n' | npx wrangler secret put GH_PRIVATE_KEY
# File issues in your repo
echo "your-org/your-repo" | npx wrangler secret put GH_REPO

Point camofox-browser to your endpoint:

export CAMOFOX_CRASH_REPORT_URL=https://your-worker.your-subdomain.workers.dev/report

Verify:

curl https://your-worker.your-subdomain.workers.dev/health
# -> {"status":"ok"}

Structured Logging

All log output is JSON (one object per line) for easy parsing by log aggregators:

{"ts":"2026-02-11T23:45:01.234Z","level":"info","msg":"req","reqId":"a1b2c3d4","method":"POST","path":"/tabs","userId":"agent1"}
{"ts":"2026-02-11T23:45:01.567Z","level":"info","msg":"res","reqId":"a1b2c3d4","status":200,"ms":333}

Health check requests (/health) are excluded from request logging to reduce noise.

Basic Browsing

# Create a tab
curl -X POST http://localhost:9377/tabs \
  -H 'Content-Type: application/json' \
  -d '{"userId": "agent1", "sessionKey": "task1", "url": "https://example.com"}'

# Get accessibility snapshot with element refs
curl "http://localhost:9377/tabs/TAB_ID/snapshot?userId=agent1"
# -> { "snapshot": "[button e1] Submit  [link e2] Learn more", ... }

# Click by ref
curl -X POST http://localhost:9377/tabs/TAB_ID/click \
  -H 'Content-Type: application/json' \
  -d '{"userId": "agent1", "ref": "e1"}'

# Type into an element
curl -X POST http://localhost:9377/tabs/TAB_ID/type \
  -H 'Content-Type: application/json' \
  -d '{"userId": "agent1", "ref": "e2", "text": "hello", "pressEnter": true}'

# Navigate with a search macro
curl -X POST http://localhost:9377/tabs/TAB_ID/navigate \
  -H 'Content-Type: application/json' \
  -d '{"userId": "agent1", "macro": "@google_search", "query": "best coffee beans"}'

API

Tab Lifecycle

Method	Endpoint	Description
`POST`	`/tabs`	Create tab with initial URL
`GET`	`/tabs?userId=X`	List open tabs
`GET`	`/tabs/:id/stats`	Tab stats (tool calls, visited URLs)
`DELETE`	`/tabs/:id`	Close tab
`DELETE`	`/tabs/group/:groupId`	Close all tabs in a group
`DELETE`	`/sessions/:userId`	Close all tabs for a user

Page Interaction

Method	Endpoint	Description
`GET`	`/tabs/:id/snapshot`	Accessibility snapshot with element refs. Query params: `includeScreenshot=true` (add base64 PNG), `offset=N` (paginate large snapshots)
`POST`	`/tabs/:id/click`	Click element by ref or CSS selector
`POST`	`/tabs/:id/type`	Type text into element
`POST`	`/tabs/:id/press`	Press a keyboard key
`POST`	`/tabs/:id/scroll`	Scroll page (up/down/left/right)
`POST`	`/tabs/:id/navigate`	Navigate to URL or search macro
`POST`	`/tabs/:id/wait`	Wait for selector or timeout
`GET`	`/tabs/:id/links`	Extract all links on page
`GET`	`/tabs/:id/images`	List `<img>` elements. Query params: `includeData=true` (return inline data URLs), `maxBytes=N`, `limit=N`
`GET`	`/tabs/:id/downloads`	List captured downloads. Query params: `includeData=true` (base64 file data), `consume=true` (clear after read), `maxBytes=N`
`GET`	`/tabs/:id/screenshot`	Take screenshot
`POST`	`/tabs/:id/back`	Go back
`POST`	`/tabs/:id/forward`	Go forward
`POST`	`/tabs/:id/refresh`	Refresh page

YouTube Transcript

Method	Endpoint	Description
`POST`	`/youtube/transcript`	Extract captions from a YouTube video

curl -X POST http://localhost:9377/youtube/transcript \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "languages": ["en"]}'
# -> { "status": "ok", "transcript": "[00:18] [music] We're no strangers to love [music]\n...", "video_title": "...", "total_words": 548 }

Uses yt-dlp when available (fast, no browser needed). Falls back to a browser-based intercept method if yt-dlp is not installed -- this is slower and less reliable due to YouTube ad pre-rolls.

Server

Method	Endpoint	Description
`GET`	`/health`	Health check
`POST`	`/start`	Start browser engine
`POST`	`/stop`	Stop browser engine

Sessions

Method	Endpoint	Description
`POST`	`/sessions/:userId/cookies`	Add cookies to a user session (Playwright cookie objects)
`GET`	`/sessions/:userId/storage_state`	Export cookies + localStorage (VNC plugin)

Search Macros

Reddit macros return JSON directly (no HTML parsing needed):

@reddit_search - search all of Reddit, returns JSON with 25 results
@reddit_subreddit - browse a subreddit (e.g., query "programming" -> /r/programming.json)

Environment Variables

Variable	Description	Default
`CAMOFOX_PORT`	Server port	`9377`
`PORT`	Server port (fallback, for platforms like Fly.io, Railway)	`9377`
`CAMOFOX_API_KEY`	Enable cookie import endpoint (disabled if unset)	-
`CAMOFOX_ADMIN_KEY`	Required for `POST /stop`	-
`CAMOFOX_ACCESS_KEY`	If set, all routes (except `/health`, cookie import, and `/stop`) require `Authorization: Bearer <key>`. Lets you safely expose the server beyond loopback.	-
`CAMOUFOX_EXECUTABLE`	External Camoufox executable to use instead of downloading/launching the bundled cache. Must point to a Camoufox bundle with sibling resources.	-
`CAMOUFOX_EXECUTABLE_PATH`	Compatibility alias for `CAMOUFOX_EXECUTABLE`	-
`CAMOFOX_EXECUTABLE_PATH`	Compatibility alias for `CAMOUFOX_EXECUTABLE`	-
`CAMOFOX_COOKIES_DIR`	Directory for cookie files	`~/.camofox/cookies`
`CAMOFOX_PROFILE_DIR`	Directory for persisted session profiles	`~/.camofox/profiles`
`CAMOFOX_TRACES_DIR`	Directory for session trace zips	`~/.camofox/traces`
`CAMOFOX_TRACES_MAX_BYTES`	Max size per trace, removed on next startup if exceeded	`52428800` (50MB)
`CAMOFOX_TRACES_TTL_HOURS`	Traces older than this are swept on startup	`24`
`MAX_SESSIONS`	Max concurrent browser sessions	`50`
`MAX_TABS_PER_SESSION`	Max tabs per session	`10`
`SESSION_TIMEOUT_MS`	Session inactivity timeout	`1800000` (30min)
`BROWSER_IDLE_TIMEOUT_MS`	Kill browser when idle (0 = never)	`300000` (5min)
`HANDLER_TIMEOUT_MS`	Max time for any handler	`30000` (30s)
`MAX_CONCURRENT_PER_USER`	Concurrent request cap per user	`3`
`MAX_OLD_SPACE_SIZE`	Node.js V8 heap limit (MB)	`128`
`PROXY_STRATEGY`	Proxy mode: `backconnect` (rotating sticky sessions) or blank (single endpoint)	-
`PROXY_PROVIDER`	Provider name for session format (e.g. `decodo`)	`decodo`
`PROXY_HOST`	Proxy hostname or IP (simple mode)	-
`PROXY_PORT`	Proxy port (simple mode)	-
`PROXY_USERNAME`	Proxy auth username	-
`PROXY_PASSWORD`	Proxy auth password	-
`PROXY_BACKCONNECT_HOST`	Backconnect gateway hostname	-
`PROXY_BACKCONNECT_PORT`	Backconnect gateway port	`7000`
`PROXY_COUNTRY`	Target country for proxy geo-targeting	-
`PROXY_STATE`	Target state/region for proxy geo-targeting	-
`TAB_INACTIVITY_MS`	Close tabs idle longer than this	`300000` (5min)
`CAMOFOX_CRASH_REPORT_ENABLED`	Enable anonymized crash/hang telemetry (`false` to disable)	`true`
`CAMOFOX_CRASH_REPORT_URL`	Telemetry endpoint (self-hosted endpoint)	`https://camofox-telemetry.askjo.workers.dev/report`
`CAMOFOX_CRASH_REPORT_REPO`	GitHub repo for telemetry issues	`jo-inc/camofox-browser`
`CAMOFOX_CRASH_REPORT_RATE_LIMIT`	Max telemetry reports per hour	`10`
`ENABLE_VNC`	Enable VNC plugin for interactive browser access (`1`)	-
`VNC_PASSWORD`	Password for VNC access (recommended in production)	-
`NOVNC_PORT`	noVNC web UI port	`6080`

Architecture

Browser Instance (Camoufox)
\-- User Session (BrowserContext) - isolated cookies/storage
    |-- Tab Group (sessionKey: "conv1")
    |   |-- Tab (google.com)
    |   \-- Tab (github.com)
    \-- Tab Group (sessionKey: "conv2")
        \-- Tab (amazon.com)

Sessions auto-expire after 30 minutes of inactivity. The browser itself shuts down after 5 minutes with no active sessions, and relaunches on the next request.

When a session's tab limit is reached, the oldest/least-used tab is automatically recycled instead of returning an error -- so long-running agent sessions don't hit dead ends.

Security Model

This section documents the security boundaries of camofox-browser for users and automated security reviewers.

Code isolation

All process.env reads are centralized in lib/config.js. All child_process usage is in lib/launcher.js (server subprocess) and plugins/youtube/youtube.js (yt-dlp). The main server.js has route handlers but zero process.env reads and zero child_process imports. No single file combines environment/credential access with network sends.

No embedded secrets

Zero credentials, private keys, API tokens, or signing keys ship in this package. All secrets are provided at runtime via environment variables (CAMOFOX_API_KEY, CAMOFOX_ACCESS_KEY) or are Cloudflare Worker environment secrets (telemetry endpoint GitHub App key).

Cookie import is disabled by default

The cookie import endpoint (POST /sessions/:userId/cookies) is gated behind CAMOFOX_API_KEY. If this env var is not set, the server rejects all cookie import requests with HTTP 403. Cookie files are read from a sandboxed directory (~/.camofox/cookies/) with path traversal protection -- attempts to escape the directory are blocked. Max 500 cookies per request, 5MB file size limit.

Access control

CAMOFOX_ACCESS_KEY provides global bearer token authentication for all routes (except /health). When set, every request must include Authorization: Bearer <key>. Recommended for any deployment beyond localhost.

Binary download

The Camoufox browser engine (~300MB) is downloaded at npm install time by camoufox-js, an npm package maintained by the Camoufox project. It downloads from official GitHub releases with integrity verification handled by camoufox-js. No custom download URLs, no URL shorteners, no raw IP addresses.

Telemetry

Anonymized crash/hang telemetry is sent to a Cloudflare Worker endpoint. The endpoint source is in this repo and auditable. Verification: GET /source on the endpoint returns the deployed commit hash and sha256 so you can compare against the repo. The reporter (lib/reporter.js L28-290) applies paranoid anonymization: private domains are HMAC-hashed (not reversible), paths are stripped, tokens/IPs/emails are redacted. No page content, cookies, or user data is ever sent. Disable with CAMOFOX_CRASH_REPORT_ENABLED=false or point to your own endpoint with CAMOFOX_CRASH_REPORT_URL.

Session persistence

The persistence plugin saves cookies and localStorage to ~/.camofox/profiles/<hashed-userId>/ so authenticated sessions survive browser restarts. UserIds are hashed for directory names. Disable via camofox.config.json by removing persistence from the plugins array.

Network access

Outbound connections are made to: (1) URLs the agent navigates to (core functionality), (2) the telemetry endpoint (anonymized, opt-out available). Inbound: the REST API on localhost:9377 (default), optionally protected by CAMOFOX_ACCESS_KEY.

Subprocess usage

Two subprocesses may be spawned: (1) the Camoufox browser engine (core functionality, lib/launcher.js), (2) yt-dlp for YouTube transcript extraction (optional, plugins/youtube/youtube.js). Both are isolated in dedicated files separate from route handlers.

Testing

npm test              # all tests
npm run test:e2e      # e2e tests only
npm run test:live     # live site tests (Google, macros)
npm run test:debug    # with server output

npm

npm install @askjo/camofox-browser

Credits

Camoufox - Firefox-based browser with C++ anti-detection
Donate to Camoufox's original creator daijro
OpenClaw - Open-source AI agent framework

Crypto Scam Warning

Sketchy people are doing sketchy things with crypto tokens named "Camofox" now that this project is getting attention. Camofox is not a crypto project and will never be one. Any token, coin, or NFT using the Camofox name has nothing to do with us.

License

MIT

coreyhaines31/marketingskills

Marketing skills for Claude Code and AI agents. CRO, copywriting, SEO, analytics, and growth engineering.

Marketing Skills for AI Agents

A collection of AI agent skills focused on marketing tasks. Built for technical marketers and founders who want AI coding agents to help with conversion optimization, copywriting, SEO, analytics, and growth engineering. Works with Claude Code, OpenAI Codex, Cursor, Windsurf, and any agent that supports the Agent Skills spec.

Built by Corey Haines. Need hands-on help? Check out Conversion Factory — Corey's agency for conversion optimization, landing pages, and growth strategy. Want to learn more about marketing? Subscribe to Swipe Files. Want an autonomous AI agent that uses these skills to be your CMO? Try Magister.

New to the terminal and coding agents? Check out the companion guide Coding for Marketers.

Contributions welcome! Found a way to improve a skill or have a new one to add? Open a PR.

Run into a problem or have a question? Open an issue — we're happy to help.

What are Skills?

Skills are markdown files that give AI agents specialized knowledge and workflows for specific tasks. When you add these to your project, your agent can recognize when you're working on a marketing task and apply the right frameworks and best practices.

How Skills Work Together

Skills reference each other and build on shared context. The product-marketing skill is the foundation — every other skill checks it first to understand your product, audience, and positioning before doing anything.

                            ┌──────────────────────────────────────┐
                            │          product-marketing           │
                            │    (read by all other skills first)  │
                            └──────────────────┬───────────────────┘
                                               │
    ┌──────────────┬─────────────┬─────────────┼─────────────┬──────────────┬──────────────┐
    ▼              ▼             ▼             ▼             ▼              ▼              ▼
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐ ┌──────────┐ ┌─────────────┐ ┌───────────┐
│  SEO &   │ │   CRO    │ │Content & │ │  Paid &    │ │ Growth & │ │  Sales &    │ │ Strategy  │
│ Content  │ │          │ │   Copy   │ │Measurement │ │Retention │ │    GTM      │ │           │
├──────────┤ ├──────────┤ ├──────────┤ ├────────────┤ ├──────────┤ ├─────────────┤ ├───────────┤
│seo-audit │ │cro       │ │copywritng│ │ads         │ │referrals │ │revops       │ │mktg-ideas │
│ai-seo    │ │signup    │ │copy-edit │ │ad-creative │ │free-tools│ │sales-enable │ │mktg-psych │
│site-arch │ │onboarding│ │cold-email│ │ab-testing  │ │churn-    │ │launch       │ │customer-  │
│programm  │ │popups    │ │emails    │ │analytics   │ │ prevent  │ │pricing      │ │ research  │
│schema    │ │paywalls  │ │social    │ │            │ │community │ │competitors  │ │           │
│content   │ │          │ │video     │ │            │ │lead-magnt│ │comp-profile │ │           │
│aso       │ │          │ │image     │ │            │ │co-mktg   │ │directory    │ │           │
└────┬─────┘ └────┬─────┘ └────┬─────┘ └─────┬──────┘ └────┬─────┘ └──────┬──────┘ └─────┬─────┘
     │            │            │              │             │              │              │
     └────────────┴─────┬──────┴──────────────┴─────────────┴──────────────┴──────────────┘
                        │
         Skills cross-reference each other:
           copywriting ↔ cro ↔ ab-testing
           revops ↔ sales-enablement ↔ cold-email
           seo-audit ↔ schema ↔ ai-seo
           customer-research → copywriting, cro, competitors

See each skill's Related Skills section for the full dependency map.

Available Skills

Skill	Description
ab-testing	When the user wants to plan, design, or implement an A/B test or experiment, or build a growth experimentation program....
ad-creative	When the user wants to generate, iterate, or scale ad creative — headlines, descriptions, primary text, or full ad...
ads	When the user wants help with paid advertising campaigns on Google Ads, Meta (Facebook/Instagram), LinkedIn, Twitter/X,...
ai-seo	When the user wants to optimize content for AI search engines, get cited by LLMs, or appear in AI-generated answers....
analytics	When the user wants to set up, improve, or audit analytics tracking and measurement. Also use when the user mentions...
aso	When the user wants to audit or optimize an App Store or Google Play listing. Also use when the user mentions 'ASO...
churn-prevention	When the user wants to reduce churn, build cancellation flows, set up save offers, recover failed payments, or...
co-marketing	When the user wants to find co-marketing partners, plan joint campaigns, or brainstorm partnership opportunities. Use...
cold-email	Write B2B cold emails and follow-up sequences that get replies. Use when the user wants to write cold outreach emails,...
community-marketing	Build and leverage online communities to drive product growth and brand loyalty. Use when the user wants to create a...
competitor-profiling	When the user wants to research, profile, or analyze competitors from their URLs. Also use when the user mentions...
competitors	When the user wants to create competitor comparison or alternative pages for SEO and sales enablement. Also use when...
content-strategy	When the user wants to plan a content strategy, decide what content to create, or figure out what topics to cover. Also...
copy-editing	When the user wants to edit, review, or improve existing marketing copy, or refresh outdated content. Also use when the...
copywriting	When the user wants to write, rewrite, or improve marketing copy for any page — including homepage, landing pages,...
cro	When the user wants to optimize, improve, or increase conversions on any marketing page or form — including homepage,...
customer-research	When the user wants to conduct, analyze, or synthesize customer research. Use when the user mentions "customer...
directory-submissions	When the user wants to submit their product to startup, SaaS, AI, agent, MCP, no-code, or review directories for...
emails	When the user wants to create or optimize an email sequence, drip campaign, automated email flow, or lifecycle email...
free-tools	When the user wants to plan, evaluate, or build a free tool for marketing purposes — lead generation, SEO value, or...
image	When the user wants to create, generate, edit, or optimize images for marketing — blog heroes, social graphics, product...
launch	When the user wants to plan a product launch, feature announcement, or release strategy. Also use when the user...
lead-magnets	When the user wants to create, plan, or optimize a lead magnet for email capture or lead generation. Also use when the...
marketing-ideas	When the user needs marketing ideas, inspiration, or strategies for their SaaS or software product. Also use when the...
marketing-psychology	When the user wants to apply psychological principles, mental models, or behavioral science to marketing. Also use when...
onboarding	When the user wants to optimize post-signup onboarding, user activation, first-run experience, or time-to-value. Also...
paywalls	When the user wants to create or optimize in-app paywalls, upgrade screens, upsell modals, or feature gates. Also use...
popups	When the user wants to create or optimize popups, modals, overlays, slide-ins, or banners for conversion purposes. Also...
pricing	When the user wants help with pricing decisions, packaging, or monetization strategy. Also use when the user mentions...
product-marketing	When the user wants to create or update their product marketing context document. Also use when the user mentions...
programmatic-seo	When the user wants to create SEO-driven pages at scale using templates and data. Also use when the user mentions...
referrals	When the user wants to create, optimize, or analyze a referral program, affiliate program, or word-of-mouth strategy....
revops	When the user wants help with revenue operations, lead lifecycle management, or marketing-to-sales handoff processes....
sales-enablement	When the user wants to create sales collateral, pitch decks, one-pagers, objection handling docs, or demo scripts. Also...
schema	When the user wants to add, fix, or optimize schema markup and structured data on their site. Also use when the user...
seo-audit	When the user wants to audit, review, or diagnose SEO issues on their site. Also use when the user mentions "SEO...
signup	When the user wants to optimize signup, registration, account creation, or trial activation flows. Also use when the...
site-architecture	When the user wants to plan, map, or restructure their website's page hierarchy, navigation, URL structure, or internal...
social	When the user wants help creating, scheduling, or optimizing social media content for LinkedIn, Twitter/X, Instagram,...
video	When the user wants to create, generate, or produce video content using AI tools or programmatic frameworks. Also use...

Installation

Option 1: CLI Install (Recommended)

Use npx skills to install skills directly:

# Install all skills
npx skills add coreyhaines31/marketingskills

# Install specific skills
npx skills add coreyhaines31/marketingskills --skill cro copywriting

# List available skills
npx skills add coreyhaines31/marketingskills --list

This automatically installs to your .agents/skills/ directory (and symlinks into .claude/skills/ for Claude Code compatibility).

Option 2: Claude Code Plugin

Install via Claude Code's built-in plugin system:

# Add the marketplace
/plugin marketplace add coreyhaines31/marketingskills

# Install all marketing skills
/plugin install marketing-skills

Option 3: Clone and Copy

Clone the entire repo and copy the skills folder:

git clone https://github.com/coreyhaines31/marketingskills.git
cp -r marketingskills/skills/* .agents/skills/

Option 4: Git Submodule

Add as a submodule for easy updates:

git submodule add https://github.com/coreyhaines31/marketingskills.git .agents/marketingskills

Then reference skills from .agents/marketingskills/skills/.

Option 5: Fork and Customize

Fork this repository
Customize skills for your specific needs
Clone your fork into your projects

Option 6: SkillKit (Multi-Agent)

Use SkillKit to install skills across multiple AI agents (Claude Code, Cursor, Copilot, etc.):

# Install all skills
npx skillkit install coreyhaines31/marketingskills

# Install specific skills
npx skillkit install coreyhaines31/marketingskills --skill cro copywriting

# List available skills
npx skillkit install coreyhaines31/marketingskills --list

Upgrading from v1.x to v2.0

v2.0 renames 17 skills and consolidates page-cro + form-cro into a single cro skill. If you installed the v1.x skills, you'll have stale old-name folders in your install directory after upgrading — the new skills install alongside the old ones, so you'll see both skills/page-cro/ and skills/cro/, etc. Clean them up:

# From the directory where you installed the skills (e.g., .agents/skills/ or .claude/skills/)
rm -rf page-cro form-cro \
       ab-test-setup analytics-tracking aso-audit competitor-alternatives \
       email-sequence free-tool-strategy launch-strategy onboarding-cro \
       paid-ads paywall-upgrade-cro popup-cro pricing-strategy \
       product-marketing-context referral-program schema-markup \
       signup-flow-cro social-content

Then reinstall the v2.0 skills via your usual method (e.g., npx skills add coreyhaines31/marketingskills).

Migrate the product marketing context file

In v2.0 the context file moved from .claude/ to .agents/ and was renamed from product-marketing-context.md to product-marketing.md. Move your existing context file:

mkdir -p .agents
# v2.0 file (or pre-v2.0 file with new name)
mv .claude/product-marketing.md .agents/product-marketing.md 2>/dev/null
# pre-v2.0 file with legacy name
mv .claude/product-marketing-context.md .agents/product-marketing.md 2>/dev/null

Skills will still check .claude/ and the legacy product-marketing-context.md filename as fallbacks, so nothing breaks if you don't migrate.

Full rename map

Old	New
`ab-test-setup`	`ab-testing`
`analytics-tracking`	`analytics`
`aso-audit`	`aso`
`competitor-alternatives`	`competitors`
`email-sequence`	`emails`
`form-cro`	merged into `cro`
`free-tool-strategy`	`free-tools`
`launch-strategy`	`launch`
`onboarding-cro`	`onboarding`
`page-cro`	`cro`
`paid-ads`	`ads`
`paywall-upgrade-cro`	`paywalls`
`popup-cro`	`popups`
`pricing-strategy`	`pricing`
`product-marketing-context`	`product-marketing`
`referral-program`	`referrals`
`schema-markup`	`schema`
`signup-flow-cro`	`signup`
`social-content`	`social`

Usage

Once installed, just ask your agent to help with marketing tasks:

"Help me optimize this landing page for conversions"
→ Uses cro skill

"Write homepage copy for my SaaS"
→ Uses copywriting skill

"Set up GA4 tracking for signups"
→ Uses analytics skill

"Create a 5-email welcome sequence"
→ Uses emails skill

You can also invoke skills directly:

/cro
/emails
/seo-audit

Skill Categories

Conversion Optimization

cro - Pages and forms
signup - Registration flows
onboarding - Post-signup activation
popups - Modals and overlays
paywalls - In-app upgrade moments

Content & Copy

copywriting - Marketing page copy
copy-editing - Edit and polish existing copy
cold-email - B2B cold outreach emails and sequences
emails - Automated email flows
social - Social media content
image - AI image generation, design tools, and optimization

SEO & Discovery

seo-audit - Technical and on-page SEO
ai-seo - AI search optimization (AEO, GEO, LLMO)
programmatic-seo - Scaled page generation
site-architecture - Page hierarchy, navigation, URL structure
competitors - Comparison and alternative pages
schema - Structured data

Paid & Distribution

ads - Google, Meta, LinkedIn ad campaigns
ad-creative - Bulk ad creative generation and iteration
social - Social media scheduling and strategy

Measurement & Testing

analytics - Event tracking setup
ab-testing - Experiment design

Retention

churn-prevention - Cancel flows, save offers, dunning, payment recovery

Growth Engineering

co-marketing - Partner identification and joint campaigns
free-tools - Marketing tools and calculators
referrals - Referral and affiliate programs

Strategy & Monetization

marketing-ideas - 140 SaaS marketing ideas
marketing-psychology - Mental models and psychology
launch - Product launches and announcements
pricing - Pricing, packaging, and monetization

Sales & RevOps

revops - Lead lifecycle, scoring, routing, pipeline management
sales-enablement - Sales decks, one-pagers, objection docs, demo scripts

Contributing

Found a way to improve a skill? Have a new skill to suggest? PRs and issues welcome!

See CONTRIBUTING.md for guidelines on adding or improving skills.

License

MIT - Use these however you want.

zarazhangrui/follow-builders

AI builders digest — monitors top AI builders on X and YouTube podcasts, remixes their content into digestible summaries. Follow builders, not influencers.

English | 中文

Follow Builders, Not Influencers

An AI-powered digest that tracks the top builders in AI — researchers, founders, PMs, and engineers who are actually building things — and delivers curated summaries of what they're saying.

Philosophy: Follow people who build products and have original opinions, not influencers who regurgitate information.

What You Get

A daily or weekly digest delivered to your preferred messaging app (Telegram, Discord, WhatsApp, etc.) with:

Summaries of new podcast episodes from top AI podcasts
Key posts and insights from 25 curated AI builders on X/Twitter
Full articles from official AI company blogs (Anthropic Engineering, Claude Blog)
Links to all original content
Available in English, Chinese, or bilingual

Quick Start

Install the skill in your agent (OpenClaw or Claude Code)
Say "set up follow builders" or invoke /follow-builders
The agent walks you through setup conversationally — no config files to edit

The agent will ask you:

How often you want your digest (daily or weekly) and what time
What language you prefer
How you want it delivered (Telegram, email, or in-chat)

No API keys needed — all content is fetched centrally. Your first digest arrives immediately after setup.

Changing Settings

Your delivery preferences are configurable through conversation. Just tell your agent:

"Switch to weekly digests on Monday mornings"
"Change language to Chinese"
"Make the summaries shorter"
"Show me my current settings"

The source list (builders and podcasts) is curated centrally and updates automatically — you always get the latest sources without doing anything.

Customizing the Summaries

The skill uses plain-English prompt files to control how content is summarized. You can customize them two ways:

Through conversation (recommended): Tell your agent what you want — "Make summaries more concise," "Focus on actionable insights," "Use a more casual tone." The agent updates the prompts for you.

Direct editing (power users): Edit the files in the prompts/ folder:

summarize-podcast.md — how podcast episodes are summarized
summarize-tweets.md — how X/Twitter posts are summarized
summarize-blogs.md — how blog posts are summarized
digest-intro.md — the overall digest format and tone
translate.md — how English content is translated to Chinese

These are plain English instructions, not code. Changes take effect on the next digest.

Default Sources

Podcasts (6)

AI Builders on X (25)

Andrej Karpathy, Swyx, Josh Woodward, Kevin Weil, Peter Yang, Nan Yu, Madhu Guru, Amanda Askell, Cat Wu, Thariq, Google Labs, Amjad Masad, Guillermo Rauch, Alex Albert, Aaron Levie, Ryo Lu, Garry Tan, Matt Turck, Zara Zhang, Nikunj Kothari, Peter Steinberger, Dan Shipper, Aditya Agarwal, Sam Altman, Claude

Official Blogs (2)

Anthropic Engineering — technical deep-dives from the Anthropic team
Claude Blog — product announcements and updates from Claude

Installation

OpenClaw

# From ClawhHub (coming soon)
clawhub install follow-builders

# Or manually
git clone https://github.com/zarazhangrui/follow-builders.git ~/skills/follow-builders
cd ~/skills/follow-builders/scripts && npm install

Claude Code

git clone https://github.com/zarazhangrui/follow-builders.git ~/.claude/skills/follow-builders
cd ~/.claude/skills/follow-builders/scripts && npm install

Requirements

An AI agent (OpenClaw, Claude Code, or similar)
Internet connection (to fetch the central feed)

That's it. No API keys needed. All content (blog articles + YouTube transcripts + X/Twitter posts) is fetched centrally and updated daily.

How It Works

A central feed is updated daily with the latest content from all sources (blog articles via web scraping, YouTube transcripts via Supadata, X/Twitter via official API)
Your agent fetches the feed — one HTTP request, no API keys
Your agent remixes the raw content into a digestible summary using your preferences
The digest is delivered to your messaging app (or shown in-chat)

See examples/sample-digest.md for what the output looks like.

Privacy

No API keys are sent anywhere — all content is fetched centrally
If you use Telegram/email delivery, those keys are stored locally in ~/.follow-builders/.env
The skill only reads public content (public blog posts, public YouTube videos, public X posts)
Your configuration, preferences, and reading history stay on your machine

License

MIT

microsoft/power-platform-skills

A plugin marketplace for Claude Code/GitHub Copilot that provides Power Platform development plugins, including reusable skills, agents, and commands for building and deploying solutions.

Power Platform Skills

Official agent skills/plugins for Power Platform development by Microsoft.

Overview

This repository is a plugin marketplace containing Claude Code/GitHub Copilot plugins for Power Platform services. Each plugin provides skills, agents, and commands to help developers build on the Power Platform.

Installation

Quick Install (Recommended)

Run the installer to set up all plugins with auto-update enabled:

Windows (PowerShell):

iwr https://raw.githubusercontent.com/microsoft/power-platform-skills/main/scripts/install.js -OutFile install.js; node install.js; del install.js

Mac OS/Linux/Windows (cmd):

curl -fsSL https://raw.githubusercontent.com/microsoft/power-platform-skills/main/scripts/install.js | node

The installer automatically:

Installs pac CLI if not already installed
Detects available tools (Claude Code, GitHub Copilot CLI)
Registers the plugin marketplace and installs all listed plugins
Enables auto-update so plugins stay current

Manual Installation

If you prefer to install manually, run these commands inside a Claude Code or GitHub Copilot CLI session:

Add the marketplace

/plugin marketplace add microsoft/power-platform-skills

Install the desired plugin

/plugin install power-pages@power-platform-skills
/plugin install model-apps@power-platform-skills
/plugin install code-apps@power-platform-skills
/plugin install canvas-apps@power-platform-skills

Available Plugins

Power Pages (`plugins/power-pages`)

Create and deploy Power Pages sites using modern development approaches.

Currently supported: Code Sites (SPAs) with React, Angular, Vue, or Astro

Model Apps (`plugins/model-apps`)

Build and deploy Power Apps generative pages for model-driven apps.

Stack: React + TypeScript + Fluent, deployed via PAC CLI

Code Apps (`plugins/code-apps`)

Build and deploy Power Apps code apps connected to Power Platform via connectors.

Stack: React + Vite + TypeScript, deployed via PAC CLI

Canvas Apps (`plugins/canvas-apps`)

Author Power Apps Canvas Apps using the Canvas Authoring MCP server.

Stack: PA YAML (.pa.yaml) authored via CanvasAuthoringMcpServer, requires .NET 10 SDK

Local Development

To develop and test plugins locally, follow these steps:

Clone this repository

Launch Claude Code with plugin path:

claude --plugin-dir /path/to/power-platform-skills/plugins/power-pages
claude --plugin-dir /path/to/power-platform-skills/plugins/model-apps
claude --plugin-dir /path/to/power-platform-skills/plugins/code-apps
claude --plugin-dir /path/to/power-platform-skills/plugins/canvas-apps

Running Without Interruption

Plugins in this repo may invoke multiple tools (file edits, shell commands, MCP servers) during a session, which can result in frequent approval prompts. Use the options below to reduce or eliminate these interruptions.

Warning: Auto-approval options give the agent the same access you have on your machine. Only use these in trusted or sandboxed environments.

Claude Code

Option 1 — Permission mode (recommended)

Set the acceptEdits mode to auto-approve file edits while still prompting for shell commands:

// .claude/settings.json (project-level) or ~/.claude/settings.json (user-level)
{
  "defaultMode": "acceptEdits",
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git *)",
      "Bash(pac *)"
      // add other commands your workflow needs
    ]
  }
}

Option 2 — Allow all tools

Press Shift+Tab during a session to cycle to auto-accept mode, or launch with:

claude --dangerously-skip-permissions

See the Claude Code permissions docs for the full reference.

GitHub Copilot CLI

Option 1 — Allow specific tools (recommended)

Pre-approve only the tools your workflow needs:

copilot --allow-tool 'write' --allow-tool 'shell(npm run build)' --allow-tool 'shell(pac *)'

Option 2 — Allow all tools in Copilot

copilot --allow-all-tools

To allow everything except dangerous commands:

copilot --allow-all-tools --deny-tool 'shell(rm)' --deny-tool 'shell(git push)'

See the Copilot CLI docs for the full reference.

Repository Structure

power-platform-skills/
├── .claude-plugin/
│   └── marketplace.json      # Marketplace manifest (lists all plugins)
├── .claude/
│   └── settings.json         # Auto-allowed tools (pac, node, dotnet, etc.)
├── plugins/
│   ├── power-pages/          # Power Pages plugin
│   │   ├── .claude-plugin/
│   │   │   └── plugin.json
│   │   ├── commands/
│   │   ├── shared/
│   │   └── skills/
│   ├── model-apps/           # Model Apps plugin
│   |   ├── .claude-plugin/
│   │   └── plugin.json
│   |   ├── commands/
│   |   ├── skills/
│   |   ├── shared/           # Shared references + samples
│   |   └── github/           # GitHub Copilot instructions
│   ├── code-apps/            # Code Apps plugin
│   │   ├── .claude-plugin/
│   │   │   └── plugin.json
│   │   ├── agents/
│   │   ├── skills/
│   │   └── shared/           # Shared instructions + references
│   └── canvas-apps/          # Canvas Apps plugin
│       ├── .claude-plugin/
│       │   └── plugin.json
│       ├── references/       # Technical + design guides
│       └── skills/
├── AGENTS.md                 # Development guidelines
└── README.md

Documentation

Contributing

See CONTRIBUTING.md for contribution guide.

License

The code in this repo is licensed under the MIT license.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

HeyPuter/puter

🌐 The Internet Computer! Free, Open-Source, and Self-Hostable.

The Open-Source Internet Computer!

« LIVE DEMO »

Puter.com · App Store · Developers · Discord · Reddit · X

Puter

Puter is an advanced, open-source, self-hostable internet computer designed to be feature-rich, fast, and highly extensible.

For Users

Puter's goal is to provide you with every app and feature you need to work, create, and play under one roof. From a simple Notepad and Voice Recorder to Spreadsheet and Camera, Puter wants to be the all-in-one solution for your digital life.

For Developers

Puter provides everything you need to build and publish web apps and games. From AI to Cloud Storage and Database to Serverless Workers, Puter has you covered. Puter also helps you get users! Once you build your app, you can publish it on our App Store to reach and monetize users.

Getting Started

💻 Local Development

git clone https://github.com/HeyPuter/puter
cd puter
npm install
npm start

→ This should launch Puter at http://puter.localhost:4100

🚀 Self-Hosting

Linux/macOS

curl -fsSL https://puter.com/selfhost | sh

Windows

irm https://puter.com/selfhost?os=windows | iex

→ For more details, see Self-Hosting Puter.

☁️ Puter.com

Puter is available as a hosted service at puter.com.

Support

Connect with the maintainers and community through these channels:

Bug report or feature request? Please open an issue.
Discord: discord.com/invite/PQcx7Teh8u
X (Twitter): x.com/HeyPuter
Reddit: reddit.com/r/puter/
Mastodon: mastodon.social/@puter
Security issues or abuse reports? security@puter.com
Email maintainers at hi@puter.com

We are always happy to help you with any questions you may have. Don't hesitate to ask!

License

This repository, including all its contents, sub-projects, modules, and components, is licensed under AGPL-3.0 unless explicitly stated otherwise. Third-party libraries included in this repository may be subject to their own licenses.

Translations

fspecii/ace-step-ui

🎵 The Ultimate Open Source Suno Alternative - Professional UI for ACE-Step 1.5 AI Music Generation. Free, local, unlimited. Stop paying for Suno!

ACE-Step UI

The Ultimate Open Source Suno Alternative
Seamless integration with ACE-Step 1.5 - The Open Source AI Music Generation Model

Demo • Why ACE-Step • Features • Installation • Usage • Contributing

🎬 Demo

Generate professional AI music with a Spotify-like interface - 100% free and local

🚀 Why ACE-Step UI?

Tired of paying $10+/month for Suno or Udio? ACE-Step 1.5 is the open source Suno killer that runs locally on your own GPU - and ACE-Step UI gives you a beautiful, professional interface to harness its full power.

Feature	Suno/Udio	ACE-Step UI
Cost	$10-50/month	FREE forever
Privacy	Cloud-based	100% local
Ownership	Licensed	You own everything
Customization	Limited	Full control
Queue Limits	Restricted	Unlimited
Commercial Use	Expensive tiers	No restrictions

What Makes ACE-Step 1.5 Special?

State-of-the-art quality rivaling commercial services
Full song generation up to 4+ minutes with vocals
Runs locally - no internet required after setup
Open source - inspect, modify, improve
Active development - constant improvements

✨ Features

🎵 AI Music Generation

Feature	Description
Full Song Generation	Create complete songs with vocals and lyrics up to 4+ minutes
Instrumental Mode	Generate instrumental tracks without vocals
Custom Mode	Fine-tune BPM, key, time signature, and duration
Style Tags	Define genre, mood, tempo, and instrumentation
Batch Generation	Generate multiple variations at once
AI Enhance	Enrich genre tags into detailed captions with proper BPM/key/time
Thinking Mode	Let AI reason about structure and generate audio codes

🎨 Advanced Parameters

Feature	Description
Reference Audio	Use any audio file as a style reference
Audio Cover	Transform existing audio with new styles
Repainting	Regenerate specific sections of a track
Seed Control	Reproduce exact generations for consistency
Inference Steps	Control quality vs speed tradeoff

🎤 Lyrics & Prompts

Feature	Description
Lyrics Editor	Write and format lyrics with structure tags
Format Assistant	AI-powered caption and lyrics formatting
Prompt Templates	Quick-start with genre presets
Reuse Prompts	Clone settings from any previous generation

🎧 Professional Interface

Feature	Description
Spotify-Inspired UI	Clean, modern design with dark/light mode
Bottom Player	Full-featured player with waveform and progress
Library Management	Browse, search, and organize all your tracks
Likes & Playlists	Organize favorites into custom playlists
Real-time Progress	Live generation progress with queue position
LAN Access	Use from any device on your local network

🛠️ Built-in Tools

Feature	Description
Audio Editor	Trim, fade, and apply effects with AudioMass
Stem Extraction	Separate vocals, drums, bass, and other with Demucs
Video Generator	Create music videos with Pexels backgrounds
Gradient Covers	Beautiful procedural album art (no internet needed)

💻 Tech Stack

Layer	Technologies
Frontend	React 18, TypeScript, TailwindCSS, Vite
Backend	Express.js, SQLite, better-sqlite3
AI Engine	ACE-Step 1.5 (Gradio API)
Audio Tools	AudioMass, Demucs, FFmpeg

📋 Requirements

Requirement	Specification
Node.js	18 or higher
Python	3.10+ (3.11 recommended) OR Windows Portable Package
NVIDIA GPU	4GB+ VRAM (works without LLM), 12GB+ recommended (with LLM)
CUDA	12.8 (for Windows Portable Package)
FFmpeg	For audio processing
uv	Python package manager (recommended for standard install)

⚡ Quick Start

🎯 Pinokio - 1-Click Install (Recommended for All Users!)

The easiest way to get ACE-Step UI up and running on any platform — no terminal, no manual setup:

Pinokio handles everything automatically: Python, Node.js, dependencies, model downloads, and launching. Just click install and start making music.

🪟 Windows - One-Click Start (Easiest!)

cd ace-step-ui
start-all.bat

That's it! This starts everything: API + Backend + Frontend in one command.

Note: By default, it looks for ACE-Step in ..\ACE-Step-1.5. If yours is elsewhere, set ACESTEP_PATH first:
set ACESTEP_PATH=C:\path\to\ACE-Step-1.5
start-all.bat

🪟 Windows - Manual Start

REM 1. Start ACE-Step Gradio (with API endpoints)
cd C:\ACE-Step-1.5
python_embeded\python -m acestep --port 8001 --enable-api --backend pt --server-name 127.0.0.1

REM 2. Start ACE-Step UI (in another terminal)
cd ace-step-ui
start.bat

Linux / macOS - One-Click Start (Easiest!)

cd ace-step-ui
./start-all.sh

That's it! This starts everything: Gradio + Backend + Frontend in one command.

Note: By default, it looks for ACE-Step in ../ACE-Step-1.5. If yours is elsewhere, set ACESTEP_PATH first:
export ACESTEP_PATH=/path/to/ACE-Step-1.5
./start-all.sh
To stop: ./stop-all.sh

Linux / macOS - Manual Start

# 1. Start ACE-Step Gradio with API (in ACE-Step-1.5 directory)
cd /path/to/ACE-Step-1.5
uv run acestep --port 8001 --enable-api --backend pt --server-name 127.0.0.1

# 2. Start ACE-Step UI (in another terminal)
cd ace-step-ui
./start.sh

Windows (Standard Installation)

REM 1. Start ACE-Step Gradio with API (in ACE-Step-1.5 directory)
cd C:\path\to\ACE-Step-1.5
uv run acestep --port 8001 --enable-api --backend pt --server-name 127.0.0.1

REM 2. Start ACE-Step UI (in another terminal)
cd ace-step-ui
start.bat

Open http://localhost:3000 and start creating!

📦 Installation

1. Install ACE-Step (The AI Engine)

🪟 Windows Portable Package (Recommended for Windows)

The easiest way to get started on Windows! This package includes everything pre-configured:

Download ACE-Step-1.5.7z (~5GB)
Extract to C:\ACE-Step-1.5 (or your preferred location)
Done! The package includes python_embeded with all dependencies

✅ Works with 4GB GPU - No LLM installation required ✅ CUDA 12.8 included ✅ Zero setup hassle

Note: Thinking Mode (LLM features) is automatically disabled on GPUs with <12GB VRAM. You can still enable it manually if you have 12GB+.

Standard Installation (All Platforms)

# Clone ACE-Step 1.5 - the open source Suno alternative
git clone https://github.com/ace-step/ACE-Step-1.5
cd ACE-Step-1.5

# Create virtual environment and install
uv venv
uv pip install -e .

# Models download automatically on first run (~5GB)
cd ..

2. Install ACE-Step UI (This Repository)

Linux / macOS

# Clone the UI
git clone https://github.com/fspecii/ace-step-ui
cd ace-step-ui

# Run setup script (installs all dependencies)
./setup.sh

Windows

REM Clone the UI
git clone https://github.com/fspecii/ace-step-ui
cd ace-step-ui

REM Run setup script (installs all dependencies)
setup.bat

Manual Installation (All Platforms)

# Install frontend dependencies
npm install

# Install server dependencies
cd server
npm install
cd ..

# Copy environment file
# Linux/macOS:
cp server/.env.example server/.env
# Windows:
copy server\.env.example server\.env

🎮 Usage

Step 1: Start ACE-Step Gradio Server

🪟 Windows Portable Package:

cd C:\ACE-Step-1.5
python_embeded\python -m acestep --port 8001 --enable-api --backend pt --server-name 127.0.0.1

Linux / macOS:

cd /path/to/ACE-Step-1.5
uv run acestep --port 8001 --enable-api --backend pt --server-name 127.0.0.1

Windows (Standard Installation):

cd C:\path\to\ACE-Step-1.5
uv run acestep --port 8001 --enable-api --backend pt --server-name 127.0.0.1

Wait for "API endpoints enabled" before proceeding.

Step 2: Start ACE-Step UI

Linux / macOS:

cd ace-step-ui
./start.sh

Windows:

cd ace-step-ui
start.bat

Step 3: Create Music!

Access	URL
Local	http://localhost:3000
LAN (other devices)	http://YOUR_IP:3000

⚙️ Configuration

Edit server/.env:

# Server
PORT=3001

# ACE-Step Gradio URL (must match --port used when starting ACE-Step)
ACESTEP_API_URL=http://localhost:8001

# Database (local-first, no cloud)
DATABASE_PATH=./data/acestep.db

# Optional: Pexels API for video backgrounds
PEXELS_API_KEY=your_key_here

🎼 Generation Modes

Simple Mode

Just describe what you want. ACE-Step handles the rest.

"An upbeat pop song about summer adventures with catchy hooks"

Custom Mode

Full control over every parameter:

Parameter	Description
Lyrics	Full lyrics with `[Verse]`, `[Chorus]` tags
Style	Genre, mood, instruments, tempo
Duration	30-240 seconds
BPM	60-200 beats per minute
Key	Musical key (C major, A minor, etc.)

AI Enhance & Thinking Mode

Mode	What it does	Speed impact
AI Enhance OFF	Sends your style tags directly to the model	Fastest
AI Enhance ON	LLM enriches your tags into a detailed caption and generates proper BPM, key, time signature	+10-20s
Thinking Mode	Full LLM reasoning with audio code generation	Slowest, best quality

Tip: If your genre tags (e.g. "pop, rock") produce ballad-like output, turn on AI Enhance for much better genre accuracy. No extra VRAM needed — the LLM runs on CPU with the PT backend.

Batch Size & Bulk Generation

Setting	Description
Batch Size	Number of variations generated per job (1-4). Default is 1 for broad GPU compatibility. Higher values generate more variations but use more VRAM. 8GB GPU users should keep this at 1.
Bulk Generate	Queue multiple independent generation jobs (1-10). Each job runs sequentially, so this is safe for any GPU.
LM Backend	Choose between PT (~1.6 GB VRAM) and VLLM (~9.2 GB VRAM). PT is the default and works on most GPUs.

Tip: Both batch size and bulk count are remembered in your browser — set them once and they stick for future sessions.

🔧 Built-in Tools

Tool	Description
🎚️ Audio Editor	Cut, trim, fade, and apply effects
🎤 Stem Extraction	Separate vocals, drums, bass, other
🎬 Video Generator	Create music videos with stock footage
🎨 Album Art	Auto-generated gradient covers

🐛 Troubleshooting

Issue	Solution
ACE-Step not reachable	Ensure Gradio server is running with `--enable-api` flag (see Usage section)
CUDA out of memory	Use `--backend pt` (default), set batch size to 1, reduce duration, or disable Thinking Mode
4GB GPU - Out of memory	Use PT backend (default), batch size 1, and keep Thinking Mode OFF. LLM features require 12GB+
Genre always sounds like ballad	Enable AI Enhance toggle in the Style section — it enriches your tags with proper metadata
AttributeError: 'NoneType'	Update to latest ACE-Step-1.5 (fix merged in PR #109)
Songs show 0:00 duration	Install FFmpeg: `sudo apt install ffmpeg` (Linux) or download from ffmpeg.org (Windows)
LAN access not working	Check firewall allows ports 3000 and 3001

🤝 Contributing

We need your help to make ACE-Step UI even better!

This is a community-driven project and contributions are what make open source amazing. Whether you're fixing bugs, adding features, improving documentation, or sharing ideas - every contribution counts!

Ways to Contribute

🐛 Report bugs - Found an issue? Open a GitHub issue
💡 Suggest features - Have an idea? We'd love to hear it
🔧 Submit PRs - Code contributions are always welcome
📖 Improve docs - Help others get started
⭐ Star the repo - Show your support!

How to Contribute

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📣 Stay Connected

Subscribe and follow for:
🎥 Video tutorials and demos
🚀 New feature announcements
💡 Tips and tricks
🎵 AI music generation news

🙏 Credits

ACE-Step - The revolutionary open source AI music generation model
AudioMass - Web audio editor
Demucs - Audio source separation
Pexels - Stock video backgrounds

📄 License

This project is open source under the MIT License.

⭐ If ACE-Step UI helps you create amazing music, please star this repo! ⭐

Made with ❤️ for the open-source AI music community

Stop paying for Suno. Start creating with ACE-Step.

datawhalechina/easy-vibe

💻 vibe coding 2026 | Your first modern Coding course for beginners to master step by step.

Jump right in and vibe together — if you can talk, you can build apps.
直接上手，一起 vibe！会说话就会做应用。

🚀 Start Exploring · ✨ Interactive Tutorial · 🦞 Learn OpenClaw · 📖 Table of Contents
🚀 开始体验 · ✨ 交互式教程 · 🦞 学习 OpenClaw · 📖 查看目录

Read Online · Learning Map
开始阅读 · 学习地图

A beginner-friendly learning map _{Clear guidance from zero, so you can stop "learning and forgetting"}	Step-by-step visual tutorials _{Detailed walkthroughs that feel like learning with a private tutor}
Immersive simulated coding _{Virtual mouse guidance helps you quickly learn the core IDE workflow}	Visible AI principles _{Animated explanations make it easy to see how AI generates images}
Learn RAG like a game _{Interactive components let you click through the full RAG data flow}	Visual terminal concepts _{Command-line behavior becomes intuitive when the underlying logic is visualized}

⭐ Star the repo here to help accelerate updates ❤️

📝 Have your own vibe coding story? Submit it here and inspire others!

Why Easy-Vibe

Want an expense tracker? Say it.

Need a booking system with WeChat login? Say it.

Want a blog with comments? Say it.

In the AI era, programming starts by describing what you want.

Easy-Vibe teaches you how to turn that into a real product.

🔥 News

[2026-03-29] ✨ Vibe Stories launched and upgraded with real user journeys: Added a new homepage Vibe Stories section with an interactive carousel and dedicated story pages, then replaced placeholder content with four real user stories featuring a rural primary school teacher, a college student, a high school IT teacher, and a truck driver who built real products with AI. 👉 View the stories
[2026-03-26] 🚀 Major Stage 2 practice update: Completed the SaaS capstone project "Your First SaaS Full-Stack App: Copywriting Generator Website" and substantially expanded the "How to integrate Stripe and payment systems" section, plus key content around multi-product UI and WeChat Mini Program backend workflows.
[2026-03-25] 📚 New appendix: User Research and Requirement Validation: Added four new articles covering idea sourcing, the Double Diamond model, Jobs to Be Done, and The Mom Test to help beginners discover and validate product ideas. 👉 Read the appendix
[2026-03-25] 📚 English documentation fully updated: Stage 2 (Full-stack Development) and Stage 3 (Advanced Development) are now fully available in English. 👉 Start learning

Past News

[2026-03-02] 🦞 OpenClaw and AI Agent friendly support: Added llms.txt so OpenClaw, Claude, Cursor, Trae, and other AI agents can quickly understand the repository structure and find the right tutorial content.
[2026-03-01] The Advanced Development section has been comprehensively upgraded with deep guides for Claude Code, including MCP, Skills, Agent Teams, and more, along with eight cross-platform project tutorials.
[2026-02-25] Updated the Appendix Knowledge Base, now covering 9 knowledge areas and 80+ interactive topics.
[2026-01-27] Added Android and iOS app development tutorials.
[2026-01-19] Released interactive demos for Prompt Engineering, AI history, authentication design, Git principles, and more.
[2026-01-16] Reorganized the project structure and formally established a beginner entry path.
[2026-01-14] Completed a large update to the Stage 1 product prototyping docs.
[2026-01-13] Refactored the documentation architecture and fully enabled multi-language support.
[2026-01-01] Released the core learning map for the project.

Who This Is For

Complete beginners: Build your first project first, then understand how it works
Product managers / founders: Validate ideas fast and build MVPs at low cost
Students: Develop practical skills for the AI era
Junior developers: Learn the full path from idea to launch
Mid-level and senior developers: Upgrade your AI collaboration workflow for complex projects

Your Learning Paths

🎮 I want a fast first win

Best for: Everyone What you will learn: What AI coding actually feels like through a simple, concrete hands-on example What you will get: A clear first impression of vibe coding and how to work with AI by conversation

Start here

💡 I want to turn an idea into a product prototype

Best for: Beginners / product managers / founders What you will learn: Learning roadmap, AI IDE tools, idea validation, prototyping, AI capability integration, and full demo iteration What you will get: A demoable AI product prototype you can actually show to users or teammates

Start learning

🚀 I want to build full-stack products end to end

Best for: Junior developers / indie hackers / advanced learners What you will learn: Frontend workflows, design-to-code, databases, backend APIs, deployment, billing, and major projects What you will get: The ability to independently ship modern AI-enabled web applications

Start learning

AI-Native: I want advanced Claude Code and agent workflows

Best for: Developers interested in AI-native engineering What you will learn: Claude Code, MCP, Skills, Agent Teams, long-running tasks, Spec Coding, and cross-platform app delivery What you will get: A stronger workflow for complex AI-assisted development and automation

Go to advanced development

📚 I want reference material and fundamentals

Best for: Everyone What you will learn: Computer fundamentals, frontend/backend basics, infrastructure, AI principles, and engineering practices What you will get: A long-term reference knowledge base covering 9 major knowledge areas

Browse the knowledge base

Study Suggestions

If you are a beginner, product manager, or founder, start with Stage 1
If you want to move from prototypes to full-stack delivery, start with Stage 2
If you want advanced Claude Code workflows or cross-platform projects, go to Stage 3
If you get blocked by concepts or missing background knowledge, use the Appendix Knowledge Base

📖 Content Navigation

I. Beginner Entry

Section	Key Content
Learning Map	A guided overview of the full learning journey
AI Era: If You Can Speak, You Can Code	Get your first feel for AI coding through examples like Snake
Master AI Programming Tools	Learn how AI IDE tools work and build simple local projects with them
Find Great Ideas	Learn how to discover and validate product ideas worth building
Build Product Prototypes	Move from requirements to single-page and multi-page product prototypes
Integrate AI Capabilities	Integrate text, image, and video AI features
Complete project practice	Simulate real scenarios, collect user feedback, and iterate on a full project

Appendix: Product and Business Thinking

Section	Key Content
Product Thinking and Solution Design	Core frameworks for going from zero to one with a product
AI Industry Application Scenarios (B-end)	Understand how AI is applied across industries
AI Consumer Scenarios Inspiration (C-end)	Explore product opportunities in consumer AI

Appendix: User Research and Requirement Validation

Section	Key Content
Where to find ideas: 3 reference sources that work best for beginners	Build a reliable pipeline for finding concrete product opportunities
Double Diamond: first do the right thing, then do it right	Use a structured process to move from scattered inspiration to a workable direction
Use Jobs to Be Done to find what users really want done	Analyze user goals through real tasks instead of surface-level feature requests
The Mom Test: a user interview method for validating demand	Learn how to ask better questions and avoid false-positive feedback

Appendix: Technical Solutions

Section	Key Content
What to do if you encounter errors	Common vibe coding issues and how to troubleshoot them
Comparison of Seven AI Programming Tools	Compare major AI coding platforms through hands-on testing
Design Websites with Agents	Learn multi-agent collaboration in practice

II. Junior and Mid-Level Developers

Frontend

Section	Key Content
Frontend 0: Build Your Own Asset-Production Agent with Lovart	Use Nanobanana and Lovart to batch-generate visual assets and build a drawing agent with intent recognition
Frontend 1: Figma & MasterGo Basics	Learn the workflow from design drafts to implementation-ready UI thinking
Frontend 2: Build Your First Modern App - UI Design	Learn the UI design foundations behind modern application interfaces
Frontend 3: UI Guidelines and Multi-Product Design	Improve consistency and aesthetics across multiple products with shared UI rules
Frontend 4: Make Interfaces Beautiful with LLMs and Skills	Use prompts and plugins to make AI generate more polished, distinctive interfaces
Frontend 4: Let's Build Hogwarts Portraits	Build an interactive AI-image frontend project from scratch
Frontend 6: From Design Prototype to Project Code	Turn design prototypes into frontend code that can really run in the browser
Frontend 7: Upgrade Your UI with Modern Component Libraries	Use component libraries to build professional interfaces faster

Backend

Section	Key Content
Backend 1: Learn Git and GitHub	Master core version control operations and collaboration workflows with Git
Backend 2: From Database to Supabase	Learn relational database basics and use Supabase as a modern BaaS platform
Backend 3: Backend API Design and Development	Use AI to assist API design, backend code generation, and API documentation
Backend 4: Ship Your Product Prototype	Quickly deploy full-stack applications to the cloud with Zeabur
Backend 5: From IDEs to CLI AI Coding Tools	Explore terminal-first AI coding workflows for modern development
Backend 6: Integrate Stripe and Other Billing Systems	Add monetization with payment and billing capabilities

Major Projects

Section	Key Content
Major Project 1: Your First SaaS Full-Stack App - AI Copywriting Website	Build an AI marketing copy workspace with login, generation, billing, and admin management
Major Project 2: Online Exam and Management System	Build an online exam system with question generation, test-taking flows, and admin tools

AI Capabilities Appendix

Section	Key Content
AI 1: Dify Basics & Knowledge Base Integration	Learn to build AI applications with Dify and integrate private knowledge bases

III. Advanced Developers

Claude Code Core Skills

Section	Key Content
Getting started with Claude Code	Installation, setup, fundamentals, and useful commands
Claude Code MCP guide	Connect Claude Code to GitHub, databases, APIs, and other services through MCP
Claude Code Skills guide	Package expertise into reusable skills you can use again and again
How to keep Claude Code working for long-running tasks	Design long-running tasks so coding tools can keep working until the job is done
Claude Agent Teams guide	Coordinate multiple AI instances like a real development team
Claude Code Superpowers for engineering-grade development	Help AI produce engineering-grade code with TDD and best practices
Claude Code workflow best practices	Best practices for refactoring, code review, and daily development
Claude Code remote development on mobile	Use Claude Code beyond the desktop and build a productive remote workflow on mobile devices
Claude Agent SDK complete guide	Build custom agent workflows and integrate Claude into your own tools with the SDK
From vibe coding to spec coding	Move from ad-hoc prompting to a more structured, specification-driven AI development workflow

Cross-Platform Development

Section	Key Content
How to choose the right platform for your app	Compare app forms and choose the right platform based on users, scenarios, and delivery goals
Build a WeChat Mini Program	Understand the ecosystem and ship a frontend mini program from template to launch
Build a WeChat Mini Program with backend	Add backend logic and databases to complete the full business loop
Build an Android app	Learn Android app development with a modern native workflow
Build an iOS app	Learn iOS app development and the conventions of the Apple ecosystem
Build a local PWA app	Turn a website into a real app with offline support, push, and installation
Build a browser AI assistant extension	Create a Chrome extension that summarizes any page with either cloud APIs or built-in AI
Build an Electron desktop app	Build a voice-to-text desktop app with Electron for three platforms
Rapidly build and mint an NFT	Write a smart contract from scratch, deploy it, and mint your own NFT
Build a VS Code extension	Build an AI project assistant with templates, code chat, and multi-file Q&A
Build an industrial-grade Qt desktop app	Create a real-time Qt HMI system with trends, alerts, and monitoring

AI Capabilities Appendix

Section	Key Content
What is RAG and how does it work	Build a systematic understanding of RAG principles and common architectures
Intermediate and advanced RAG workflows with LangGraph	Design multi-step workflows and more advanced RAG systems

📚 Appendix Knowledge Base

Covering 9 major knowledge areas and 80+ interactive topics, this appendix uses animation and visual components to help you intuitively understand core concepts from computer fundamentals to the AI frontier.

👉 View the full appendix

🎓 Other Courses

🛠️ How To Learn

Read and practice the sections that match your current level. If you get stuck, feel free to open an issue.

💻 Run Locally

Modern approach

In an AI IDE chat window such as VS Code, Cursor, or Trae, you can simply say:

Please help me run this project locally.

Traditional approach

npm install
npm run dev
Open http://localhost:3000 in your browser.

Other Courses

Our team has also created other courses! Check them out:

Hands-on Modern RL: An open-source, hands-on curriculum bridging the gap from basic RL concepts to LLM alignment, RLVR, and advanced Agentic systems.

Learn Harness Engineering: A comprehensive guide to harness engineering.

🤝 Contributing & Contributors

If you find an issue or see something that can be improved, feel free to open an issue. If nobody replies, you can also contact the Datawhale support team.
If you want to contribute, open a pull request. If nobody replies, you can also contact the Datawhale support team.
If you want to start a new Datawhale open-source project, please follow the Datawhale Open Source Project Guide.

🙏 Contributors

Sanbu - Project Lead (Datawhale member)
Fang Ke - Mentor (Datawhale member, Tsinghua University)
Yerim Kang (Practice projects, Tsinghua University)
Zhilin Zhao (Practice projects, Tsinghua University)
Yixuan Li (Visual design, Tsinghua University)
Siyi Liu (Practice projects, Tsinghua University)
Lixin Liu (Practice projects, Tsinghua University)
Everyone in the AI Vibe Coding 101 internal testing group who shared suggestions and feedback

Special Thanks

Thanks to @Sm1les for the help and support on this project
Thanks to every contributor and everyone who supported the project with feedback and stars ❤️

📄 LICENSE

This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License .

Star History

SillyTavern/SillyTavern

LLM Frontend for Power Users.

English | German | 中文 | 繁體中文 | 日本語 | Русский | 한국어

SillyTavern provides a single unified interface for many LLM APIs (KoboldAI/CPP, Horde, NovelAI, Ooba, Tabby, OpenAI, OpenRouter, Claude, Mistral and more), a mobile-friendly layout, Visual Novel Mode, Automatic1111 & ComfyUI API image generation integration, TTS, WorldInfo (lorebooks), customizable UI, auto-translate, more prompt options than you'd ever want or need, and endless growth potential via third-party extensions.

We have a Documentation website to answer most of your questions and help you get started.

What is SillyTavern?

SillyTavern (or ST for short) is a locally installed user interface that allows you to interact with text generation LLMs, image generation engines, and TTS voice models.

Beginning in February 2023 as a fork of TavernAI 1.2.8, SillyTavern now has over 300 contributors and 3 years of independent development under its belt, and continues to serve as a leading software for savvy AI hobbyists.

Our Vision

We aim to empower users with as much utility and control over their LLM prompts as possible. The steep learning curve is part of the fun!
We do not provide any online or hosted services, nor programmatically track any user data.
SillyTavern is a passion project brought to you by a dedicated community of LLM enthusiasts, and will always be free and open sourced.

Do I need a powerful PC to run SillyTavern?

The hardware requirements are minimal: it will run on anything that can run NodeJS 20 or higher. If you intend to do LLM inference on your local machine, we recommend a 3000-series NVIDIA graphics card with at least 6GB of VRAM, but actual requirements may vary depending on the model and backend you choose to use.

Questions or suggestions?

Discord server

	Join our Discord community! Get support, share favorite characters and prompts.

Or get in touch with the developers directly:

Discord: cohee, rossascends, wolfsblvt
Reddit: /u/RossAscends, /u/sillylossy, u/Wolfsblvt
Post a GitHub issue

I like your project! How do I contribute?

Send pull requests. Learn how to contribute: CONTRIBUTING.md
Send feature suggestions and issue reports using the provided templates.
Read this entire readme file and check the documentation website first, to avoid sending duplicate issues.

Screenshots

Installation

For detailed installation instructions, please visit our documentation:

License and credits

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

TavernAI 1.2.8 by Humi: MIT License
Portions of CncAnon's TavernAITurbo mod used with permission
Visual Novel Mode inspired by the work of PepperTaco (https://github.com/peppertaco/Tavern/)
Noto Sans font by Google (OFL license)
Lexer/Parser by Chevrotain (Apache-2.0 license) https://github.com/chevrotain/chevrotain
Icon theme by Font Awesome https://fontawesome.com (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License)
Default content by @OtisAlejandro (Seraphina character and lorebook) and @kallmeflocc (10K Discord Users Celebratory Background)
Docker guide by @mrguymiah and @Bronya-Rand
kokoro-js library by @hexgrad (Apache-2.0 License)

Top Contributors

juliangarnier/anime

JavaScript animation engine

Anime.js

Anime.js is a fast, multipurpose and lightweight JavaScript animation library with a simple, yet powerful API.
It works with CSS properties, SVG, DOM attributes and JavaScript Objects.

Usage

Anime.js V4 works by importing ES modules like so:

import {
  animate,
  stagger,
} from 'animejs';

animate('.square', {
  x: 320,
  rotate: { from: -180 },
  duration: 1250,
  delay: stagger(65, { from: 'center' }),
  ease: 'inOutQuint',
  loop: true,
  alternate: true
});

V4 Documentation

The full documentation is available here.

V3 Migration guide

You can find the v3 to v4 migration guide here.

NPM development scripts

First, run npm i to install all the necessary packages. Then, execute the following scripts with npm run <script>.

script	action
`dev`	Watches for changes in `src/*/.js`, bundles the ESM version to `lib/` and creates type declarations in `types/`
`dev:test`	Runs `dev` and `test:browser` concurrently
`build`	Bundles ESM / UMD / CJS / IIFE versions to `lib/` and creates type declarations in `types/`
`test:browser`	Starts a local server and runs all browser-related tests
`test:node`	Starts Node-related tests
`open:examples`	Starts a local server to browse the examples locally

gorhill/uBlock

uBlock Origin - An efficient blocker for Chromium and Firefox. Fast and lean.

uBlock Origin (uBO)

Browser	Install from ...	Status
	Firefox Add-ons	uBO works best on Firefox
	Edge Add-ons
	Opera Add-ons
	Chrome Web Store	About Google Chrome's "This extension may soon no longer be supported" End of support on Chrome 139
	Thunderbird Add-ons	No longer updated and stuck at 1.49.2. Later versions require "GitHub - Releases".
	GitHub - Releases	Stable and development versions on Firefox, Chromium MV2, and Thunderbird. Must be placed manually into web browsers; the Chromium and Thunderbird versions usually won't auto-update.

uBlock Origin (uBO) is a CPU and memory-efficient wide-spectrum content blocker for Chromium and Firefox. It blocks ads, trackers, coin miners, popups, annoying anti-blockers, malware sites, etc., by default using EasyList, EasyPrivacy, Peter Lowe's Blocklist, Online Malicious URL Blocklist, and uBO filter lists. There are many other lists available to block even more. Hosts files are also supported. uBO uses the EasyList filter syntax and extends the syntax to work with custom rules and filters.

You may easily unselect any preselected filter lists if you think uBO blocks too much. For reference, Adblock Plus installs with only EasyList, ABP filters, and Acceptable Ads enabled by default.

It is important to note that using a blocker is NOT theft. Do not fall for this creepy idea. The ultimate logical consequence of blocking = theft is the criminalization of the inalienable right to privacy.

Ads, "unintrusive" or not, are just the visible portion of the privacy-invading means entering your browser when you visit most sites. uBO's primary goal is to help users neutralize these privacy-invading methods in a way that welcomes those users who do not wish to use more technical means.

Documentation

Basic Mode	Advanced Mode
The simple popup user interface for an install-it-and-forget-it type of installation that is configured optimally by default.	The advanced popup user interface includes a point-and-click firewall that is configurable on a per-site basis.

Visit the Wiki for documentation.

For support, questions, or help, visit /r/uBlockOrigin.

Installation

Required Permissions

Firefox

Firefox Add-ons

Development Builds

uBO works best on Firefox and is available for desktop and Android versions.

Thunderbird

Thunderbird Add-ons

In Thunderbird, uBlock Origin does not affect emails, just feeds.

Chromium

Chrome Web Store

Microsoft Edge Add-ons (Published by Nicole Rolls until version 1.62. Ownership transfer at version 1.64.)

Opera Add-ons

Development Builds

uBO should be compatible with any Chromium-based browser.

All Programs

Do NOT use uBO with any other content blocker. uBO performs as well as or better than most popular blockers. Other blockers can prevent uBO's privacy or anti-blocker-defusing features from working correctly.

Manual Installation

Enterprise Deployment

Deploying uBO

Release History

Releases Page

Translations

Help translate uBO via Crowdin.

About

Manifesto

GPLv3 License

Free. Open-source. For users by users. No donations sought.

If you ever want to contribute something, think about the people working hard to maintain the filter lists you are using, which are available to use by all for free.