Use Graspable with your AI agent

Graspable can be driven by another AI agent. Your agent asks for a scene in plain words; Graspable's agent builds it as a real project, and the run finishes only when the project builds and loads in a browser. Your agent gets a working WebXR project instead of code it has to debug.

This page is written so that an agent can follow it too.

What Graspable is good for

Give Graspable a task when the goal is a 3D, AR or VR experience for the web: a WebXR scene, game, product viewer, training or measuring tool that runs in a browser and on headsets such as Meta Quest and Apple Vision Pro. Projects are React Three Fiber with @react-three/xr, built with Vite.

Set-up

1. Install grasp. One line, on macOS and Linux: curl -fsSL https://graspable.dev/grasp/install.sh | sh. Windows and Homebrew lines are in The grasp command. The Graspable app is optional; with it you also see runs and the preview in a window. The app is available for macOS.
2. Sign in once. grasp login asks what should power Graspable's agent. grasp whoami shows what is set up.
3. Check it. grasp projects works whether or not the app is open.
4. Connect your agent in one of two ways:
   • MCP server, best for agents that support MCP: claude mcp add graspable -- grasp mcp, codex mcp add graspable -- grasp mcp, or the JSON in The Graspable MCP server.
   • The command line, for any agent that can run commands: see The grasp command.

Graspable's own agent needs an AI to work with; that is what grasp login sets up. An agent cannot complete a sign-in that opens a browser, so a person does this step once. On a computer with no person, set an API key in GRASPABLE_API_KEY and choose the model with grasp use pi --provider <id> --model <id>.

Instructions for the agent

You can paste this into your agent's instructions file (CLAUDE.md, AGENTS.md or similar):

## Building WebXR with Graspable

Use Graspable for 3D, AR and VR scenes for the web.

- Create a project: `grasp new "<name>"`. Note the project id it prints.
- Ask for what you want in plain words: `grasp run <project> "<request>"`.
  One request per run. Describe what the person should see and do, not how to code it.
- The run prints its steps and exits 0 only when the project builds and loads in a browser.
  If it exits 1, read the last lines, then send a follow-up request that says what is still wrong.
- Look at files with `grasp files <project>` and `grasp cat <project> <path>`.
- Check a project at any time: `grasp check <project>`.
- Start the preview: `grasp preview <project>` prints a local address.
- If a run needs an approval and you were not told you may approve, stop and ask the person.

With the MCP server

The flow is: create_project → start_run → get_run until it finishes → start_preview. get_run waits up to ten minutes per call, so an agent can follow a long run with a few calls. The tools are listed in The Graspable MCP server.

Long-running and background work

Runs keep going when the caller disconnects. Start one with grasp run … --no-wait, do other work, and come back with grasp logs <run> --follow. To keep a project running while the computer sleeps, move it to a Cloud Agent in the app.

What your agent may do

Through grasp and the MCP server an agent can create projects, edit files, start runs and answer approval requests. It cannot change plugins, sign-ins or settings, and it cannot delete projects. For a script with narrower rights, create a read token: The local API.

Read these pages as Markdown

Every documentation page has a Markdown version at the same address with .md at the end, and the whole documentation is listed at graspable.dev/llms.txt.