Repository avatar
AI Tools
v0.1.0
active

maskin

io.github.sindre-ai/maskin

Open-source workspace where AI agents do the work and humans set direction. Apache 2.0.

Documentation

Maskin

License: Apache 2.0 CI GitHub Stars TypeScript Node

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 pnpm@9.15.0)
  • 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 list_marketplace 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 list_marketplace 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)
│   └── openrouter-conformance.mjs  # Tool-use + reply-language check of a model on the funded OpenRouter route (spends credit; see header)
ā”œā”€ā”€ packages/
│   ā”œā”€ā”€ db/                     # Drizzle ORM schema + migrations
│   ā”œā”€ā”€ auth/                   # API key auth (keys stored as issued; hashing planned)
│   ā”œā”€ā”€ 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

LayerChoiceWhy
RuntimeNode.js >= 20Native fetch, stable ESM
LanguageTypeScript 5.7+Type safety across monorepo
API FrameworkHono.js + OpenAPIHonoFast, lightweight, edge-ready
ORMDrizzle ORMType-safe SQL, zero overhead
DatabasePostgreSQL 16JSONB for metadata, NOTIFY for real-time
ValidationZodShared schemas between API, frontend, and MCP
AuthAPI keys (stored as issued, hashing planned)Simple, agent-friendly. No cookies or sessions
Real-timePG NOTIFY -> SSENo extra infra (no Redis, no WebSocket server)
Agent ProtocolMCP (Model Context Protocol)Standard protocol for external AI agents
FrontendReact 19 + TanStack Router + TanStack QueryFile-based routing, server state caching
StylingTailwind CSS 4 + shadcn/uiUtility-first CSS with Radix UI primitives
Object StorageS3-compatible (SeaweedFS for dev)Agent file persistence (skills, learnings, memory)
ContainersDocker + dockerodeEphemeral agent execution environments
BuildTurborepoParallel builds, dependency-aware caching
LintingBiomeFast, replaces ESLint + Prettier

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

TablePurpose
actorsHumans and AI agents. Both are first-class. Stores type, name, API key (stored as issued, hashing planned), system prompt, LLM config, and memory
workspacesIsolated environments. Each workspace has its own settings including valid statuses per object type
workspace_membersMany-to-many join between actors and workspaces with roles (owner, member)
objectsThe core table. Every insight, bet, and task is an object with: type, title, content, status, metadata (JSONB), and owner
relationshipsTyped edges between objects: informs, breaks_into, blocks, relates_to, duplicates
eventsAppend-only activity log. Every mutation is recorded with actor, action, entity reference, and data payload
triggersAutomation rules. Either cron-based or event-based. Each trigger targets an actor and includes an action prompt
integrationsExternal service connections per workspace (OAuth-based)
sessionsContainer-based agent execution sessions. Tracks lifecycle: pending -> running -> completed/paused/failed/timeout
session_logsAppend-only log output from container sessions (stdout/stderr/system), used for SSE streaming
agent_filesMetadata index for agent files stored in S3 (skills, learnings, memory)

API Endpoints

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

Health and Metadata

MethodPathDescription
GET/api/healthLiveness check (no auth, no database)
GET/api/health/dbDatabase readiness check (no auth)
GET/api/openapi.jsonOpenAPI spec (no auth)

Objects (Insights, Bets, Tasks)

MethodPathDescription
POST/api/objectsCreate an object
GET/api/objectsList objects (filter by type, status, owner)
GET/api/objects/searchSearch objects by text in title/content
GET/api/objects/:idGet object by ID
GET/api/objects/:id/graphGet object with all relationships and connected objects
PATCH/api/objects/:idUpdate object (title, content, status, metadata)
DELETE/api/objects/:idDelete object

Actors

MethodPathDescription
POST/api/actorsCreate actor and get API key (no auth for humans; an agent needs the caller's API key and a workspace_id the caller belongs to)
GET/api/actorsList actors (optionally filtered by workspace)
GET/api/actors/:idGet actor details
PATCH/api/actors/:idUpdate actor
POST/api/actors/:id/api-keysRegenerate API key

Workspaces

MethodPathDescription
POST/api/workspacesCreate workspace
GET/api/workspacesList workspaces for current actor
PATCH/api/workspaces/:idUpdate workspace (name, settings)
POST/api/workspaces/:id/membersAdd member to workspace
GET/api/workspaces/:id/membersList workspace members

Relationships

MethodPathDescription
POST/api/relationshipsCreate relationship between objects
GET/api/relationshipsList relationships (filter by source, target, type)
DELETE/api/relationships/:idDelete relationship

Triggers

MethodPathDescription
POST/api/triggersCreate automation trigger
GET/api/triggersList triggers in workspace
PATCH/api/triggers/:idUpdate trigger
DELETE/api/triggers/:idDelete trigger

Events

MethodPathDescription
GET/api/eventsSSE stream of real-time events (supports Last-Event-ID for replay)
GET/api/events/historyPaginated event history (filter by entity_type, action, since)

Sessions (Container-based Agent Execution)

MethodPathDescription
POST/api/sessionsCreate a container session
GET/api/sessionsList sessions
GET/api/sessions/:idGet session details
POST/api/sessions/:id/stopStop a running session
POST/api/sessions/:id/pausePause and snapshot a session
POST/api/sessions/:id/resumeResume a paused session
GET/api/sessions/:id/logsPaginated log history
GET/api/sessions/:id/logs/streamSSE stream of live logs

Graph (Batch Operations)

MethodPathDescription
POST/api/graphAtomic batch create (objects + relationships in one transaction)

Integrations

MethodPathDescription
GET/api/integrationsList integrations for workspace
GET/api/integrations/providersList available providers
POST/api/integrations/:provider/connectStart OAuth/connection flow
GET/api/integrations/:provider/callbackOAuth callback (no auth)
DELETE/api/integrations/:idDisconnect integration

Webhooks

MethodPathDescription
POST/api/webhooks/:providerIncoming webhook handler (no auth)

MCP HTTP Transport

MethodPathDescription
POST/mcpStreamable HTTP transport for MCP clients

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 73 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 list_marketplace — it lists the available marketplace loops, and install_loop installs the one the user picks.

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

VariableRequiredDefaultDescription
DATABASE_URLYes--PostgreSQL connection string
PORTNo3000Server port
S3_ENDPOINTNohttp://localhost:8333S3-compatible storage endpoint (SeaweedFS for dev)
S3_BUCKETNoagent-filesStorage bucket name
S3_ACCESS_KEYNoadminS3 access key
S3_SECRET_KEYNoadminS3 secret key
S3_REGIONNous-east-1S3 region
S3_PUBLIC_ENDPOINTNoS3_ENDPOINTAddress browsers use to reach storage for presigned uploads/downloads of large files. Set it when S3_ENDPOINT is an internal host. The bucket needs CORS: see docs/runbooks/large-file-uploads.md

License

Apache 2.0 — see LICENSE for details.

No installation packages available.

Remote

streamable-http
https://maskin.io/mcp