Start hereSource-generated

Documentation home

System overview, topology, implemented capabilities, and recommended reading order.

Source Generated from current repository sourcesWords 295Reading 2 minSections 5

Touchgrass documentation#

Touchgrass is a self-hosted autonomous developer-agent execution and observability platform. ChatGPT or another MCP client is the conversational control surface; Touchgrass supplies isolated workspaces, tools, durable state, browser and terminal execution, checkpoints, evidence, and an operator dashboard.

Current project at a glance#

Area	Current implementation
Applications	4 independently built services
Shared packages	4 workspace packages
MCP tools	84 source-discovered tools
HTTP routes	158 source-discovered Fastify routes
Durable tables	12 source-discovered PostgreSQL tables
Runtime	Node.js 22+, pnpm 11, Docker, PostgreSQL 17, Nuxt 5, Fastify 5
Safety model	Reversible isolated execution; external and irreversible effects denied by default

System topology#

text

MCP client / ChatGPT
        |
        v
MCP server :4311
        |
        v
Control API :4310 ---- PostgreSQL :55432
        |                    |
        |                    +-- workspaces, tasks, processes, leases, events
        v
Runner :4312
  |       |        |
  |       |        +-- isolated Chromium / Playwright
  |       +----------- detached Docker PTY processes and previews
  +------------------- isolated workspaces, files, Git, shell, checkpoints

Nuxt dashboard :3000 ---- same-origin control and preview proxy

What is implemented#

Isolated Git worktrees or filtered snapshot workspaces.
Repository analysis and command detection.
Durable dependency-aware task plans.
Bounded file reads, search, exact edits, writes, and atomic multi-file patches.
Git status and bounded diffs.
Automatic validation loops with side-effect restoration.
One-shot Docker shell execution with internet access and resource limits.
Detached PTY processes with retained output, stdin, resize, cancellation, port detection, restart recovery, and exclusive expiring control leases.
Isolated HTTP/HTTPS process previews without publishing Docker ports.
Playwright browser contexts, accessibility snapshots, refs, actions, screenshots, console/network telemetry, and adaptive frame streaming.
Content-addressed browser artifacts and immutable retrieval.
Ordered durable events, session projections, usage/cost reporting, and analytics.
Responsive task, process, browser, analytics, login, and documentation interfaces.