Self-hosted workspace that runs coding agents in sandboxes, on workflows you can see, with clarification up front and human approval before anything ships.
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.
## Two ways to work
| | **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.
## Why Grasp
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.html` mock 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.
## Quick start
Requirements: a **Linux** host with Git, Docker and Docker Compose (services use host networking).
```bash
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 | |
| API health | |
| Gateway health | |
| 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.
### What you need
| 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 |
### Your first run
1. **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.
2. **Start a run** from the home page with a single prompt, or switch to **Solo**.
3. **Answer the clarify cards** and check the spec and page mock.
4. **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.**
```bash
./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`](.env.example).
- **Bundled role agents.** `agents/` contains `ClarifyAgent`, `ImplementAgent`, `TestReviewAgent` and `DeliverAgent`. Run `./agents/pack.sh` (or `./agents/pack.sh ClarifyAgent`) to build ZIPs in `agents/dist/`, then import them in Agent Studio. ZIP import defaults `acpBackend` to `cursor`; change the backend in the UI if needed.
## How workflows work
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:
```mermaid
flowchart LR
R([Request]) --> C[Clarify]
C --> SR{{Spec review gate}}
SR -- approve --> I[Implement]
SR -. rollback .-> C
I --> T[Test & review]
T -- failure --> I
T -- success --> H{{Human confirm 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.
## Features
| 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. |
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.