Maskin Workspace

An open-source workspace where AI agents run product development autonomously. Humans set direction, agents execute.

What is this?

• Open-source workspace where AI agents run product development end-to-end
• Core pipeline: Insights (signals from users, data, market) -> Bets (hypotheses to validate) -> Tasks (concrete work items) -> Feedback Loop
• Agents are first-class citizens -- they create insights, propose bets, break down tasks, and execute. Humans course-correct
• Everything is an API -- UI and agents use the same endpoints. No special agent interface, no separate human interface
• Unified object model -- insights, bets, and tasks are all "objects" with the same schema, connected by relationships

Prerequisites

• Node.js ≥ 20
• pnpm 9.15.0 (npm install -g [email protected])
• Docker + Docker Compose — must be installed and running. pnpm dev / pnpm dev:win boot PostgreSQL + SeaweedFS via docker-compose, so the app cannot start without Docker. Docker Desktop (macOS/Windows) bundles Compose; on Linux install docker-compose-plugin.

Quick Start

🚀 Zero-click setup (from Claude Code)

Paste this single prompt into Claude Code (or any MCP-compatible agent) to have it bootstrap the whole thing for you:

Clone https://github.com/sindre-ai/maskin, cd into it, follow the "Onboarding a new user from Claude Code" section of CLAUDE.md, and hand off to the get_started MCP tool.

Claude will clone, pnpm install, start the dev stack in the background, wait for the startup banner, wire the MCP server into your Claude Code config using the auto-provisioned API key + workspace, run /reload-plugins so the Maskin tools are immediately available in the same session, and then ask you which template to set up (development / growth / custom). From clone to a running pipeline in one message, no session restart.

Manual setup

# Clone and install
git clone https://github.com/sindre-ai/maskin.git && cd maskin
pnpm install

# Start everything (Docker + migrations + backend + frontend)
pnpm dev          # macOS / Linux
pnpm dev:win      # Windows (cmd / PowerShell)

pnpm dev boots PostgreSQL + SeaweedFS via Docker, runs migrations, then starts the backend (http://localhost:3000) and frontend (http://localhost:5173). When the backend prints its startup banner, pick one of the two paths below.

① Get started from the browser

1. Open http://localhost:5173 and create an account.
2. Create your first workspace from the UI.
3. (Optional) Connect MCP from Settings → MCP later if you want agents to drive the workspace.

② Get started from Claude Code (no UI)

On a fresh database, pnpm dev automatically creates a default actor + workspace and prints a ready-to-run claude mcp add command in the startup banner — including the API key. Two steps from there:

1. Connect MCP — copy the claude mcp add maskin … line from the dev banner and run it. (Disable this auto-bootstrap with MASKIN_AUTO_BOOTSTRAP=false if you want to create credentials yourself.)

2. Configure the workspace. In Claude Code, paste one of:

   Configure my Maskin workspace with the "development" template.
   

   Configure my Maskin workspace with the "growth" template.
   

   Configure my Maskin workspace with a custom template.
   

   The first two apply pre-built templates (object types, statuses, custom fields, seed objects). The third walks you through a short questionnaire and tailors the workspace to whatever you're working on. Claude will ask a couple of light tailoring questions (workspace name, what you're building, near-term goal) — answer any, all, or none. Total time: under 3 minutes.

Rename the default actor and workspace whenever you're ready — from the UI (Settings → Profile / Workspace) or via MCP (update_actor, update_workspace). Run get_started again any time on a different workspace by passing workspace_id.

Want demo data instead? Run pnpm db:seed for a pre-populated example workspace.

Architecture

maskin/
├── apps/
│   ├── dev/                    # Backend API server (Hono.js)
│   │   ├── src/
│   │   │   ├── index.ts        # App entry, middleware, route mounting
│   │   │   ├── routes/         # REST endpoints
│   │   │   │   ├── objects.ts
│   │   │   │   ├── actors.ts
│   │   │   │   ├── workspaces.ts
│   │   │   │   ├── relationships.ts
│   │   │   │   ├── triggers.ts
│   │   │   │   ├── events.ts
│   │   │   │   ├── sessions.ts
│   │   │   │   ├── integrations.ts
│   │   │   │   └── graph.ts
│   │   │   ├── services/
│   │   │   │   ├── trigger-runner.ts     # Cron + event-based automation
│   │   │   │   ├── session-manager.ts    # Container-based agent sessions
│   │   │   │   ├── container-manager.ts  # Docker container lifecycle
│   │   │   │   └── agent-storage.ts      # S3 agent file pull/push
│   │   │   └── lib/
│   │   │       └── llm/        # LLM provider adapters
│   │   │           ├── openai.ts
│   │   │           └── anthropic.ts
│   │   └── Dockerfile
│   ├── web/                    # Frontend (React + TanStack)
│   │   └── src/
│   │       ├── routes/         # File-based routing (TanStack Router)
│   │       ├── components/     # UI primitives, shared, and feature components
│   │       ├── hooks/          # TanStack Query hooks per resource
│   │       └── lib/            # API client, auth, SSE, utilities
│   └── e2e/                    # E2E tests (Playwright)
│       └── src/
│           ├── tests/          # Test specs (auth, CRUD, navigation)
│           ├── fixtures/       # Auth fixtures
│           └── helpers/        # API test helpers
├── scripts/
│   ├── dev.sh                  # Dev startup script (bash/macOS/Linux)
│   └── dev.mjs                 # Dev startup script (Windows cmd/PowerShell)
├── packages/
│   ├── db/                     # Drizzle ORM schema + migrations
│   ├── auth/                   # API key auth (SHA-256 hashed)
│   ├── shared/                 # Zod schemas for validation
│   ├── realtime/               # PG NOTIFY -> SSE bridge
│   ├── storage/                # Abstract StorageProvider with S3 implementation
│   └── mcp/                    # MCP server (39 tools, stdio + HTTP transport)
├── docker-compose.yml
├── turbo.json
└── package.json

Key design decisions:

• Modular monorepo -- pnpm workspaces + Turborepo for builds. Each package is independently importable
• Event-sourced activity -- every mutation logs an event. Agents and humans see the same audit trail
• Container-based agent execution -- Docker container sessions (SessionManager) for running Claude Code, Codex, or custom CLIs

Tech Stack

Data Model

All product work is represented as unified objects -- insights, bets, and tasks share the same table with a type discriminator. This keeps the schema flat and lets agents reason across object types uniformly.

Tables

API Endpoints

All endpoints are under /api. Most require Authorization: Bearer <api-key> and X-Workspace-Id headers.

Health and Metadata

Objects (Insights, Bets, Tasks)

Actors

Workspaces

Relationships

Triggers

Events

Sessions (Container-based Agent Execution)

Graph (Batch Operations)

Integrations

Webhooks

MCP HTTP Transport

Agent System

Agents run as container sessions — ephemeral Docker containers running CLI agents (Claude Code, Codex, custom CLIs).

• Triggered by events or cron -- the TriggerRunner watches for matching events or schedules and spawns container sessions

• All actions logged as events -- every agent action appears in the event stream, attributed to the agent actor

• Configurable per agent -- each agent has its own system prompt, tools list, and persistent memory

• Full lifecycle management -- create, run, stop, pause (snapshot), resume

• Live log streaming -- stdout/stderr streamed via SSE in real-time

• Persistent agent files -- skills, learnings, and memory stored in S3-compatible storage, pulled into containers on start and pushed back on completion

• Configurable -- custom images, environment variables, timeouts, working directories

External Agents (MCP)

External agents connect via the Model Context Protocol (39 tools available), supporting both stdio and HTTP transport.

• Full workspace access -- CRUD for objects, relationships, actors, workspaces, triggers, sessions, integrations
• Works with any MCP-compatible client -- Claude Code, Claude Desktop, OpenAI agents, custom implementations
• Authenticated via API key -- same auth as any other actor

MCP Reference

Maskin exposes 39 MCP tools over both stdio and HTTP. See Quick Start → Get started from Claude Code above for the one-command setup. Other clients (Claude Desktop, OpenAI agents, custom implementations) use the same env vars (API_BASE_URL, API_KEY, WORKSPACE_ID) — point them at pnpm --filter @maskin/mcp start for stdio, or POST http://localhost:3000/mcp for HTTP.

The first tool a new agent should call is get_started — it previews and applies a workspace template, or walks the user through a custom setup.

Docker

# Full stack (PostgreSQL + SeaweedFS + dev server)
docker-compose up

# Just the database and storage
docker-compose up postgres seaweedfs -d

The dev server container runs migrations on startup and serves at http://localhost:3000.

Development

# Start everything (Docker + migrations + dev servers)
pnpm dev

# On Windows (cmd/PowerShell):
pnpm dev:win

# Build all packages
pnpm build

# Run tests
pnpm test

# Run E2E tests (requires running dev server)
pnpm test:e2e

# Lint (Biome)
pnpm lint

# Lint and auto-fix
pnpm lint:fix

# Format
pnpm format

# Type checking
pnpm type-check

# Database: generate migration from schema changes
pnpm db:generate

# Database: run pending migrations (automatically run by pnpm dev)
pnpm db:migrate

# Database: seed demo data
pnpm db:seed

Environment Variables

License

Apache 2.0 — see LICENSE for details.