Smoke Monkey Canvas 🐒

The visual, spatial multi-agent workspace for Smoke Monkey Harness. Deploy, schedule, and chat with unlimited autonomous AI agents on an infinite canvas — all running locally with zero cloud lock-in.

    

---

🚀 Download Desktop App (1-Click Install)

Download the standalone native desktop application for offline privacy and local execution:

Platform	Download Link	Type	Status
🍏 macOS (Apple Silicon M1/M2/M3/M4)	⬇️ Download .dmg	Drag-and-Drop Disk Image (~11 MB)	Latest v1.3.2
🍏 macOS (Portable Archive)	⬇️ Download .zip	Standalone Application (~10 MB)	Latest v1.3.2
🪟 Windows (10 / 11 64-bit)	⬇️ Download .exe / Install Script	NSIS Installer & PowerShell	Available
🐧 Linux (Universal x86_64)	⬇️ Download .AppImage / Install Script	AppImage & DEB	Available

🌐 Prefer the web browser or full download portal? Visit the Desktop Download Portal or run instant NPX: npx smoke-monkey-canvas

What is Smoke Monkey Canvas?

Smoke Monkey Canvas is a standalone, portable visual workspace that lets you create, configure, and run multiple AI agents simultaneously on an infinite drag-and-drop canvas. Each agent has its own system prompt, model provider, cron schedule, MCP server integrations, skills library, working directory, and persistent multi-turn chat history.

It is built on top of smoke-monkey-harness — the open-source TypeScript AI agent runtime — and adds a production-grade local UI to orchestrate it visually.

Why Canvas?

Problem	Canvas Solution
Running agents one at a time in a terminal	Parallel agents on an infinite spatial canvas
Losing chat history on page refresh	Persistent multi-turn sessions per agent in SQLite
Cron jobs polluting interactive chat threads	Separate cron execution history with ⏰ badge
No visual feedback during agent execution	Live streaming via WebSocket with tool call timeline
Hard-coded model providers	Swap providers (NVIDIA, OpenAI, Anthropic, Groq, etc.) per agent

---

Features

• 🗺️ Infinite Canvas — drag, zoom, and organize agents spatially
• 🤖 Multi-Agent Orchestration — run dozens of agents simultaneously, each fully isolated
• 💬 Persistent Chat Sessions — multi-turn conversations survive page refreshes
• ⏰ Cron Scheduling — schedule agents to run automatically on any cron expression
• 🔌 MCP Server Integration — attach any MCP server (Firecrawl, GitHub, Slack, Tavily, etc.) per agent
• 📚 Skills Library — attach reusable skill documents to give agents domain expertise
• 🌊 Live Streaming — real-time text deltas, tool calls, and reasoning via WebSocket
• 🔑 Multi-Provider Support — NVIDIA, OpenAI, Anthropic, Gemini, Groq, DeepSeek, Ollama, and more
• 🗄️ Zero-Native-Deps SQLite — uses Node.js built-in node:sqlite (no native compile steps)
• 📦 Fully Portable — copy the directory into any project and run it

---

Architecture

smoke-monkey-canvas/
├── server/                    # Express + WebSocket backend (TypeScript)
│   ├── app.server.ts          # Entry point, mounts all routers
│   └── features/
│       ├── agent/             # Agent CRUD, runner, chat sessions, cron
│       │   ├── agent.server.ts    # REST API routes
│       │   ├── agent.runner.ts    # Harness execution engine
│       │   ├── agent.db.ts        # SQLite queries (runs, sessions, messages)
│       │   ├── agent.cron.ts      # Cron scheduler
│       │   └── agent.types.ts     # Shared type definitions
│       ├── core/
│       │   ├── database.db.ts     # Bootstrap, migrations, SQLite singleton
│       │   └── ws.server.ts       # WebSocket broadcast server
│       ├── mcp/               # MCP server registry & stock MCPs
│       ├── settings/          # API key management
│       ├── skill/             # Skills library management
│       └── space/             # Canvas node positions
└── web/                       # React + Vite frontend
    └── src/features/
        ├── agent/             # Agent drawer, chat UI, history tabs
        ├── space/             # Canvas renderer, node components
        └── mcp/               # MCP configuration UI

Data flow:

1. User interacts with Canvas UI (React/Vite)
2. REST calls → Express server → SQLite (agent config, chat history)
3. Agent run → AgentRunner → smoke-monkey-harness → LLM provider
4. Events stream back → WebSocket → UI live updates

---

Quick Start

📦 Fresh Local Installation (macOS, Linux & Windows)

Clone the repository and run the one-command installer for your platform:

🍎 macOS:

git clone https://github.com/RajdeepDevelopment/smoke-monkey-canvas.git
cd smoke-monkey-canvas
./install-mac.sh

Validates Node.js & Rust, installs workspace dependencies, compiles the frontend bundle, packages the native macOS desktop app with signed permissions, and installs it directly into /Applications/Smoke Monkey Canvas.app.

🐧 Linux:

git clone https://github.com/RajdeepDevelopment/smoke-monkey-canvas.git
cd smoke-monkey-canvas
./install-linux.sh

Checks WebKitGTK/GUI dependencies, installs all packages, builds the web distribution, and compiles the native desktop binary.

🪟 Windows (PowerShell or Command Prompt):

git clone https://github.com/RajdeepDevelopment/smoke-monkey-canvas.git
cd smoke-monkey-canvas
powershell -ExecutionPolicy Bypass -File .\install-windows.ps1

Or double-click install-windows.bat directly from File Explorer.

🌐 Universal Auto-Detector:

./install.sh

Automatically detects your host OS (macOS, Linux, or Windows) and executes the matching platform installer.

---

🚀 Option 1: Global CLI & Background Daemon (Recommended)

Install globally once, then control your background Canvas from any terminal directory:

# 1. Install globally
npm install -g @smoke-monkey/canvas

# 2. Start Canvas as a background daemon (warp-cli style)
smoke-monkey start

# 3. Check status, port, and PID
smoke-monkey status

# 4. View live logs anytime
smoke-monkey logs -f

# 5. Open Web UI in browser
smoke-monkey open

# 6. Stop the background daemon
smoke-monkey stop

(You can also use canvas or smoke-monkey-canvas as command aliases).

---

⚡ Option 2: Instant Zero-Install with NPX

Run directly without installing:

# Start background daemon
npx @smoke-monkey/canvas start

# Check status
npx @smoke-monkey/canvas status

# Stop background daemon
npx @smoke-monkey/canvas stop

---

🐳 Option 2: Docker — Official Image (All Platforms)

Pre-built multi-arch image available on Docker Hub. Works on Mac (Intel & Apple Silicon), Linux, and Windows — no build step needed.

🐳 hub.docker.com/r/rajdeepsadhu/smoke-monkey-canvas

Quickest way — one command:

docker run -d \
  --name smoke-monkey-canvas \
  -p 3333:3333 \
  -v smoke_canvas_data:/app/data \
  rajdeepsadhu/smoke-monkey-canvas:latest

Then open http://localhost:3333 🚀

Using Docker Compose (Canvas + PostgreSQL)

Includes the Canvas server and an optional dedicated PostgreSQL instance running on a unique port (15432) to ensure zero conflicts with existing local databases:

# 1. Start all services in the background
docker compose up -d

# 2. View running services and health status
docker compose ps

# 3. View live server logs
docker compose logs -f canvas

# 4. Stop all services
docker compose down

The Web UI is accessible at http://localhost:3333, and SQLite database data is persisted automatically in the smoke_canvas_data volume.

Useful Docker commands

# Pull the latest image manually
docker pull rajdeepsadhu/smoke-monkey-canvas:latest

# Run with a custom port
docker run -d -p 8080:3333 -v smoke_canvas_data:/app/data rajdeepsadhu/smoke-monkey-canvas:latest

# View logs
docker logs -f smoke-monkey-canvas

# Stop & remove
docker stop smoke-monkey-canvas && docker rm smoke-monkey-canvas

# Available tags
# latest  — always the most recent stable build
# 1.0.0   — pinned release

Supported platforms: linux/amd64 · linux/arm64 (Apple Silicon native)

---

💻 Option 3: Local Development from Source

Prerequisites

• Node.js ≥ 22.0.0 (required for node:sqlite built-in)
• An API key for at least one LLM provider (e.g., NVIDIA_API_KEY, OPENAI_API_KEY)

1. Clone & Install

git clone https://github.com/RajdeepDevelopment/smoke-monkey-canvas.git
cd smoke-monkey-canvas

# Install dependencies and build web client
npm install
npm run build

2. Launch

npm start

Canvas is now running at http://localhost:3333 🚀

Development Mode (hot-reload UI)

# Terminal 1 — start backend
npm start

# Terminal 2 — start frontend dev server
npm run dev:web

Frontend dev server runs at http://localhost:5173 and proxies API/WS calls to the backend.

---

☁️ 1-Click Cloud Deployment

Deploy your personal, persistent multi-agent canvas to the cloud in under 60 seconds with verified 1-click templates:

Cloud Provider	1-Click Deployment Button	Configuration Blueprint	Database Persistence
DigitalOcean App Platform Container runtime with zero-ops management		.do/deploy.template.yaml	Official Docker Hub Image
Render Managed web service with attached persistent SSD		render.yaml	Persistent Disk (/app/data)
Koyeb Serverless containers with worldwide edge routing		Docker Hub Official	Port 3333 HTTP
Railway Full infrastructure canvas with unmetered WebSockets		.railway/railway.ts	5 GB Persistent Volume

📖 Need a complete walkthrough or custom VPS deployment?
Check our full interactive guide: docs/deploy.html

Production stack on any Linux VM with Docker (Caddy handles automatic TLS and the WebSocket upgrade):

cd deploy
cp .env.example .env      # set SMOKE_DOMAIN to your hostname
docker compose -f docker-compose.vps.yml up -d

Every provider mounts a persistent volume at /app/data, which is where the SQLite database lives. Without it, agents and chat history are lost on every deploy.

---

Configuration

Setting API Keys

API keys can be set two ways:

1. Via the UI: Open any agent → Settings → Provider → paste key
2. Via environment variables: Set before starting the server

# Supported environment variable names
export NVIDIA_API_KEY=nvapi-...
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export GEMINI_API_KEY=AIza...
export GROQ_API_KEY=gsk_...
export OPENROUTER_API_KEY=sk-or-...
export DEEPSEEK_API_KEY=sk-...

Keys set in the UI are stored encrypted in SQLite at ~/.smoke-monkey/canvas.db.

Supported Providers

Provider	Env Variable	Models
NVIDIA NIM	NVIDIA_API_KEY	nvidia/nemotron-3-super-120b, meta/llama-3.3-70b-instruct, etc.
OpenAI	OPENAI_API_KEY	gpt-4o, gpt-4o-mini, etc.
Anthropic	ANTHROPIC_API_KEY	claude-3-5-sonnet, claude-opus-4, etc.
Google Gemini	GEMINI_API_KEY	gemini-2.0-flash, gemini-2.5-pro, etc.
Groq	GROQ_API_KEY	llama-3.1-70b-versatile, etc.
DeepSeek	DEEPSEEK_API_KEY	deepseek-chat, deepseek-reasoner
Ollama	(no key)	Any local model

---

Creating Your First Agent

1. Click + New Agent on the canvas toolbar
2. Name your agent and select a model/provider
3. Write a system prompt describing the agent's role
4. (Optional) Attach MCP servers (e.g., Firecrawl for web research)
5. (Optional) Attach skills from the library
6. (Optional) Set a cron schedule (e.g., 0 9 * * 1-5 for weekday morning runs)
7. Click Run or type in the chat to start an interactive session

---

Chat Sessions & History

Each agent maintains:

• Multi-turn chat sessions — conversations persist across page refreshes
• Cron execution history — isolated from interactive chats, shown with ⏰ Cron Job badge
• History tab filters — view All, 💬 Chats, or ⏰ Cron Jobs separately

The Session system uses SQLite (chat_sessions, chat_messages tables) so conversations are never lost, even if the server restarts.

---

REST API

The server exposes a REST API at http://localhost:3333/api:

Method	Path	Description
GET	/api/agents	List all agents
POST	/api/agents	Create agent
GET	/api/agents/:id	Get agent details
PATCH	/api/agents/:id	Update agent config
DELETE	/api/agents/:id	Delete agent
POST	/api/agents/:id/run	Trigger manual run
POST	/api/agents/:id/stop	Stop running agent
GET	/api/agents/:id/runs	List runs (filterable by trigger_type)
GET	/api/agents/runs/:runId	Get run details + events
GET	/api/agents/:id/sessions	List chat sessions
POST	/api/agents/:id/sessions	Create new session
GET	/api/agents/:id/sessions/:sessionId/messages	Get session messages
DELETE	/api/agents/:id/sessions/:sessionId	Delete session
POST	/api/agents/:id/mcps	Attach MCP server
DELETE	/api/agents/:id/mcps/:mcpId	Detach MCP server
POST	/api/agents/:id/skills	Attach skill
DELETE	/api/agents/:id/skills/:skillId	Detach skill

WebSocket: Connect to ws://localhost:3333/ws for live agent events.

---

Standalone / Embedded Use

Canvas is fully portable. You can embed it inside another project:

# Copy or pull the canvas directory into your project
cp -r smoke-monkey-canvas ./my-project/canvas
cd ./my-project/canvas
npm install && npm --prefix web install && npm run build:web
npm start

It runs completely independently with its own SQLite database, web UI, and WebSocket server.

---

License

Smoke Monkey Canvas is released under the Sustainable Use License (SUL).

Summary:

• ✅ Free to use for personal projects, research, and internal business tooling
• ✅ Free to modify and redistribute non-commercially
• ❌ You may not offer Canvas as a commercial hosted service or SaaS product without a commercial license
• ❌ You may not remove or obscure license notices

For commercial licensing, contact: rajdeep@smokemonkey.dev

---

Contributing

We welcome contributions! Please read CONTRIBUTING.md before submitting a pull request.

• 🐛 Found a bug? → Open an issue
• 💡 Have an idea? → Request a feature
• 🔒 Security issue? → See SECURITY.md

---

Related Projects

Project	Description
smoke-monkey-harness	The underlying AI agent runtime this is built on
@smoke-monkey/ui	The streaming chat UI component library

---

Built with ❤️ by RajdeepDevelopment