Self-hosted workspace that runs coding agents in sandboxes, on workflows you can see,
with clarification up front and human approval before anything ships.
English · 简体中文
Website · Two ways to work · Quick start · Workflows · Features · FAQ · Docs
Product tour (1:06, 1080p 60 fps, no sound): one sentence in; a workflow that clarifies, implements, rolls back on failing tests and waits for your approval; any coding agent in its own sandbox; Solo, artifacts and token cost.
Grasp is a self-hosted workspace for shipping software with coding agents. Describe a task in one sentence and run it as a workflow (a multi-step pipeline on a finite-state-machine canvas, with clarification, implementation, tests and human gates) or as a Solo session (one agent in its own sandbox). Either way, agents ask questions as clickable cards and hand back structured artifacts and live page previews instead of walls of text.
Coding-agent CLIs do the work: Cursor, Claude Code, Codex, CodeBuddy, Trae, OpenCode, DeepSeek Harness and Kimi Code. Grasp adds the canvas, sandboxes (Docker, Kubernetes or E2B), approvals and history around them, on your own infrastructure under the MIT license.
The home page. Type a request, pick a workflow or switch to Solo, and choose the model. Every session stays in the sidebar, so you always know what is running and where it stopped.
| Run a workflow | Start a Solo session | |
|---|---|---|
| Best for | Repeatable delivery with fixed stages, tests and sign-off | Exploring, debugging, one-off changes |
| How it runs | The FSM engine walks agent, branch and human-gate nodes along explicit success / failure / rollback edges; the nodes of a run share one sandbox |
One agent in its own sandbox with an IDE, terminal and browser; idle sandboxes are saved and resumed on your next message |
| You stay in control by | Answering clarification cards, approving at gates or sending work back, sharing a one-time review link with people who have no account | Answering the agent's question cards and steering the chat |
| Delivers | Spec, plan, page mock, test results, review and a PR / MR | Code changes, artifacts and previews in the side panel |
Both modes share the same agents, credentials, artifact panel and token accounting.
Over the past two years I built 150+ personal projects with coding agents, and two problems kept slowing me down: switching between projects (which IDE is running what, and where did it stop?) and reviewing agent output (the actual changes and open questions buried in long chat logs). Grasp is the workspace I wanted:
- Clarify before coding. A clarify agent asks one question at a time, with a recommended answer, then writes a spec, a plan and a clickable
page.htmlmock you can annotate. - Explicit, versioned workflows. Every step and transition is on the canvas. A failed test goes back to implementation because an edge says so, not because the model remembered to.
- Human in the loop. Gates pause the run until someone reads the artifacts and approves or sends the work back.
- Structured output, not prose. Specs, plans, test results, reviews and HTML previews are versioned artifacts. A node can't finish until it submits the ones it declares as required.
- Your stack, your servers. Eight agent CLIs, per-repository Git credentials, and Docker, Kubernetes or E2B sandboxes. Credentials are stored in the workspace and injected per run.
Requirements: a Linux host with Git, Docker and Docker Compose (services use host networking).
git clone https://github.com/cocofhu/grasp.git
cd grasp
./start.sh -d./start.sh pulls the published GHCR images, so nothing is built locally. Once it is up:
| Web UI / API | http://localhost:8080 |
| API health | http://localhost:8080/api/health |
| Gateway health | http://localhost:8899/healthz |
| Default login | admin / demo1234 (local evaluation only) |
The sandbox runtime image is pulled when the first sandbox is created, or ahead of time with ./start.sh pull.
Important
This release requires a fresh install: an empty database and an empty data directory.
| I want to… | You need |
|---|---|
| Look around the workspace and the canvas | Nothing beyond the quick start |
| Run a workflow or a Solo session | A credential for one coding tool: an API key, a model service key, or a ChatGPT ~/.codex/auth.json for Codex |
| Have agents push branches and open PRs / MRs | A Git repository plus a credential for gh, glab or SSH |
-
Sign in. The first visit opens the setup wizard: preferences, credentials, coding tool and model, Git (optional), and the agent team. It previews the default workflow,
Clarify → Implement → Test & review → Deliver, before publishing it.
-
Start a run from the home page with a single prompt, or switch to Solo.
-
Answer the clarify cards and check the spec and page mock.
-
Review at the gate: read the test results, review and diff, then approve or send it back.
More setup details: credentials, commands, bundled roles
-
Credentials and models. In Settings → Credentials, save a tool platform credential or a model service key with a preset or custom API base. In the Models tab, save a named combination of coding tool, credential and model, then pick it in Agent Studio. Third-party protocols are filtered by what each tool supports; Codex accepts a ChatGPT login file or a Responses connection.
-
Common commands.
./start.sh logs # follow logs ./start.sh gw-logs # gateway logs only ./start.sh restart # restart in background ./start.sh down # stop and remove containers ./start.sh pull # update service images and pre-pull sandbox runtime ./start.sh dev -d # run source stack (Go + Vite HMR)
Image tags and digests can be overridden in
.env; see.env.example. -
Bundled role agents.
agents/containsClarifyAgent,ImplementAgent,TestReviewAgentandDeliverAgent. Run./agents/pack.sh(or./agents/pack.sh ClarifyAgent) to build ZIPs inagents/dist/, then import them in Agent Studio. ZIP import defaultsacpBackendtocursor; change the backend in the UI if needed.
A workflow is a finite-state machine. Agents and people take part in the same run, and every transition is an edge you can see:
flowchart LR
R([Request]) --> C[Clarify]
C --> SR{{Spec review<br/>gate}}
SR -- approve --> I[Implement]
SR -. rollback .-> C
I --> T[Test & review]
T -- failure --> I
T -- success --> H{{Human confirm<br/>gate}}
H -. rollback .-> I
H -- approve --> D[Deliver]
D --> PR([PR / MR])
The same workflow on the canvas. Each agent node picks a role; failure and rollback edges send work back to an earlier step.
| Node | What it does |
|---|---|
| Input / Output | Where the request enters and the result leaves the workflow. |
| Agent | Runs a role (backend, model, AGENTS.md rules and skills) in a sandbox to clarify, implement, test, review or deliver. |
| Human gate | Pauses the run until someone checks the artifacts and approves, or sends the work back. |
| Branch | Routes on a condition over run variables. |
| Set variable | Writes values that later when guards and prompts can read. |
Edges are success, failure or rollback, optionally guarded by when expressions. A rollback restores the run variables saved at a checkpoint node, carries the error context back, and counts against an attempt cap. All nodes of a run share one sandbox, so the workspace and uncommitted changes carry over. Workflows are versioned and published from the canvas.
| Area | What you get |
|---|---|
| Visual clarification | One question at a time as option cards with a recommended answer; a structured spec and plan; a clickable page.html mock for desktop and mobile, with element annotations sent back as feedback. |
| FSM canvas | Input, output, set-variable, branch, agent and human-gate nodes; success / failure / rollback edges, when guards, checkpoints, version history and publishing. |
| Solo sessions | A one-off agent chat with its own sandbox, IDE, terminal and browser, sharing the question cards and artifact panel with workflows. |
| Structured artifacts | Specs, plans, test results, reviews and HTML previews submitted through Artifact MCP and versioned per run; required artifacts gate node completion. |
| Human gates | Approve or rework from the run page; reviewers without an account can use a one-time share link. |
| Git delivery | Agents push branches and open PRs / MRs via gh, glab or SSH, with a credential per repository. |
| Agent Studio | Reusable roles with a backend, model, rules and skills, grouped into teams and shared across workflows. |
| Observability & cost | State timeline, node handoff notes, sandbox logs, and token / cost tracking by workflow, source and model. |
| Sandboxes | Docker, Kubernetes or E2B through one gateway; idle sandboxes are saved and released automatically. |
Type / in an Agent conversation to open the command menu. Select a command with the mouse or arrow keys, then send it.
/newor/new chatstarts a fresh conversation context in the current workspace. Earlier messages stay visible./compactstarts a fresh context with a bounded excerpt of the recent conversation. Workflow turns also carry the current node's task and delivery requirements./skill <name> [task]selects a configured skill for the next turn. When the skill list is available, choose a name from the menu.
Clarification: the agent asks with a recommended answer while the page mock updates beside the chat.
A Solo session: the agent profiles a slow page, shows its tool calls, and asks how to fix it.
![]() |
![]() |
| Artifact library with live HTML preview | Token usage and cost by model |
flowchart LR
UI["Web UI<br/>Vue 3 + Vue Flow"] <--> S["Go server<br/>FSM engine · API · MCP · SQLite"]
S <--> G["sandbox-gateway<br/>sandbox control plane"]
G --> B["Sandbox (Docker / Kubernetes / E2B)<br/>ACP bridge + agent CLI"]
B -- "artifacts (Artifact MCP)" --> S
| Directory | Contents |
|---|---|
web/ |
Vue 3 + Vue Flow frontend: home, canvas, clarification, run details, Solo, artifacts, Agent Studio |
server/ |
Go backend: FSM engine, HTTP API, SQLite, Artifact MCP, audit |
sandbox-gateway/ |
Sandbox lifecycle control plane (gateway/) and the universal sandbox image and runtime (sandbox/) |
agents/ |
Importable role agent workspaces |
docs/ |
Project website and bilingual help docs |
Configuration precedence is environment variables > mounted config file > code defaults. Runtime secrets (agent API keys, Git tokens, SSH keys) live only in the workspace credentials settings and are injected per run, never read from the server's process environment.
| Target | Guide |
|---|---|
| Docker | Docker deployment: production Compose overrides, authentication, sandbox callbacks, backups |
| Kubernetes | Kubernetes guide and manifests: namespaces, RBAC, Secrets, PVCs, services, ingress. Uses gateway transport with ClusterIP sandboxes; a per-sandbox LoadBalancer is optional |
| E2B | E2B deployment with compose.e2b.yaml, for E2B Cloud or a compatible self-hosted control plane. Needs prepared environment templates and persistent gateway state |
Production checklist
- Store API keys and Git credentials only in the workspace credentials settings; never commit them.
- Pin images by digest; see Release images and smoke.
- Behind a reverse proxy, preserve the original
Hostheader including a non-default port (nginx:proxy_set_header Host $http_host). Share links and the origin check for signed-in requests depend on it. See SECURITY.md. - Workspace pages refuse iframe embedding. To embed them in a portal, list its origin in
GRASP_FRAME_ANCESTORS; see server/CONFIGURATION.md. - Back up SQLite (
./.localdata/db), attachments (./.localdata/app-data), gateway state (./.localdata/gateway) and the originalGRASP_SECRETS_KEYand deployment configuration together. Forstart.shdeployments the key is in.env. Sandbox workspaces are not in these directories and need separate backups.
Do I need an API key? Yes, for anything an agent does: one credential for the coding tool you pick (Codex can use a ChatGPT login file instead). Model usage is not included; you bring your own credentials.
Do I need a Git repository? No. Skip the Git step in the wizard and agents work inside the sandbox. Add a repository and credential when you want them to push branches and open PRs / MRs.
Workflow or Solo? Use Solo to explore, debug or make a quick change. When you want every task to follow the same stages, with clarification, tests and sign-off, put it in a workflow.
How is this different from using Cursor, Claude Code or Codex directly? Grasp doesn't replace them; it runs them. Each agent node and each Solo turn is one of those CLIs in a sandbox. Grasp adds what surrounds it: which role does what, in which order, with which checks, who signs off, and a record of every artifact.
How is this different from Dify, n8n or Flowise? Those are general-purpose AI and automation builders. Grasp is built for software delivery with coding agents: sandboxes with real repositories, clarification with page mocks, test-and-review loops, human gates and Git delivery.
Is it safe to expose on the internet? Not with the defaults. Replace the demo account, put HTTPS in front, and read SECURITY.md first. Report vulnerabilities privately through the security policy.
| I want to… | Start here |
|---|---|
| Understand the concepts and get running | Concepts · Quick start |
| Configure Grasp and sandboxes | Configuration and defaults (中文) · Environment reference |
| Understand the sandbox lifecycle and gateway | Sandbox lifecycle · Gateway contract |
| Work on the server | Server README |
| Get help or follow releases | Support · Changelog · Security |
Issues and pull requests are welcome: share a use case, report a bug, or improve workflows, agents and the UI. Read CONTRIBUTING.md, AGENTS.md and the Code of Conduct for lint, test and E2E commands before submitting changes.
MIT © 2026 cocofhu






