Tinymanus

Tinymanus is a TypeScript monorepo for a Manus-like agent product. It includes three main runtime pieces:

• a Fastify API
• a background worker
• a React web client

The backend persists state in PostgreSQL through Prisma and executes runs through a queue-backed worker. Agent execution can call llm_gateway, workspace, js_runner, and browser_tools.

What This Repo Does

Current product surface:

• email-password authentication with server-side sessions
• agent CRUD
• credit balance, ledger, and top-up flows
• queued agent runs
• run detail APIs for events, plan items, traces, tool invocations, artifacts, and SSE
• web UI under apps/web

High-level runtime flow:

1. the API accepts authenticated user actions
2. creating a run persists a Run and a queue ticket
3. the worker claims queued runs and executes them
4. execution emits persisted events, traces, plan items, tool invocations, and artifacts
5. the web app reads run state via polling and SSE

Quick Start

Requirements:

• Node.js >= 18
• pnpm >= 10
• PostgreSQL
• Prisma >= 6.0.0 < 7.0.0

Install dependencies:

pnpm install

Create local environment config:

cp .env.example .env

Minimum required .env value:

DATABASE_URL="postgresql://username:password@localhost:5432/tinymanus?schema=public"

Common optional values:

REDIS_URL="redis://127.0.0.1:6379"
RUN_LIVE_EVENT_CHANNEL="tinymanus_run_live_events"
SESSION_TTL_MS="604800000"
SIGNUP_BONUS_CREDITS="1000"
RUN_START_CREDITS="1"
OPENAI_BASEURL="https://your-openai-compatible-endpoint"
OPENAI_KEY="your-api-key"
OPENAI_MODEL="your-model-name"

Prepare Prisma:

pnpm prisma generate
pnpm prisma migrate dev

Start local development:

pnpm dev:api
pnpm dev:worker
pnpm dev:web

Verify The Setup

Useful checks:

pnpm typecheck
pnpm test
pnpm test:application:run
pnpm test:http
pnpm test:web:e2e

Basic happy path:

1. open the web app started by pnpm dev:web
2. register or log in
3. create one agent
4. start one run
5. inspect the run detail view or call GET /v1/runs/:runId

Repository Layout

tinymanus/
  apps/web/              React + Vite frontend
  docs/                  Focused technical documents
  prisma/                Prisma schema, migrations, and data-flow docs
  src/modules/           Stateless capability modules
  src/application/       Use-case orchestration
  src/infrastructure/    Persistence, execution, logging, and adapters
  src/interfaces/http/   Fastify routes and HTTP mapping
  src/app/               API app assembly
  src/bin/               Process entrypoints

Layering rule of thumb:

• src/modules/ stays stateless
• src/application/ owns business flows
• src/infrastructure/ owns external integrations and persistence
• src/interfaces/http/ owns HTTP transport concerns

Core modules:

• llm_gateway: OpenAI-compatible LLM adapter
• workspace: dual-root virtual filesystem boundary
• js_runner: local child-process execution behind a controlled interface
• browser_session: Playwright-backed browser session abstraction
• browser_tools: agent-facing browser tool dispatch

Key Commands

pnpm dev
pnpm dev:api
pnpm dev:worker
pnpm dev:web
pnpm build
pnpm lint
pnpm lint:fix
pnpm typecheck
pnpm test
pnpm prisma validate
pnpm prisma generate
pnpm prisma migrate dev

Documentation Map

Read these based on what you need:

• API route index: ROUTES.md
• Docs index: docs/README.md
• Run status sync and SSE behavior: docs/architecture/run-status-sync.md
• Auth flow design: docs/architecture/user-flows.md
• Failure taxonomy: docs/agent-runtime/failure-taxonomy.md
• Failure state machine: docs/agent-runtime/exception-state-machine.md
• Failure follow-up work: docs/agent-runtime/failure-follow-up.md
• Prisma schema overview: prisma/README.md
• Data flow across persisted entities: prisma/DATA_FLOWS.md
• Frontend overview: apps/web/README.md

Module-level READMEs exist under:

• src/application/*/README.md
• src/infrastructure/*/README.md

Current Boundaries

Important current constraints:

• the database remains the source of truth for run recovery; SSE is for live updates, not durable replay
• run execution is sequential; there is no parallel plan execution or dependency graph
• the system can resume WAITING_FOR_USER and BLOCKED runs, but richer resume semantics are still limited
• provider-specific continuation state is preserved, but the repo still lacks strong provider-matrix end-to-end coverage
• multilingual behavior is strongest on the LLM-backed path and weaker in heuristic fallback paths