# Build with Virtual Matter

Virtual Matter hosts live multiplayer voxel worlds. You build a world by prompting the
built-in agent or by editing its SDK Lua directly - the world runs on Virtual Matter
servers, hot-reloads as you edit, and has a shareable URL from minute one. The
`virtualmatter` CLI connects external coding agents - Claude Code, Cursor, Codex, with
your own subscription - to a live world over MCP.

## Use a world in Lovable

Already have a shared world? Paste its link into Lovable and ask it to embed the world,
following our [embed guide](https://virtualmatter.ai/embed-guide.md). No Virtual Matter account connection is
needed for a shared link.

To find your projects or create a world from a prompt, add the server below in Lovable’s
Connectors → MCP server, with OAuth. Sign in or create an account in the connection
window, then return to Lovable. You can ask “Embed my world” or “Create a garden world
and embed it here.”

```text
https://make.virtualmatter.ai/api/v1/mcp
```

VM builds use your VM credits. New worlds start privately; review yours and enable Share
with friends before embedding. The website needs the response headers described in the
guide. Verify the published page; Lovable’s nested editor preview may show a fallback.

The website hosting the iframe must send `Cross-Origin-Opener-Policy: same-origin` and
`Cross-Origin-Embedder-Policy: require-corp` as HTTP response headers. HTML meta tags
cannot set these.

## Quickstart

This path is for people: start by prompting the built-in agent, and your first prompts
are free.

1. **Create a world from a prompt.** Describe what you want at
   [virtualmatter.ai](https://virtualmatter.ai/). Your world spins up live in the browser
   with an agent chat beside it.
2. **[Download the native client for your OS.](https://virtualmatter.ai/downloads)** The browser client works
   everywhere; the native client runs the same worlds with more memory and better frame
   rates.
3. **Open your world in the native client.** Paste the world's URL (its /play or /g
   share link, or the /edit link) into the native client's connect screen.
4. **Mod it.** Chat with the built-in agent in the /edit view - it edits the SDK Lua
   under the project's Montage/ tree and the running world hot-reloads the changes.
   Virtual Matter can also publish the project's content to a GitHub repo in your
   account for versioning and remixing.

When your free credits run out, you can buy more, or keep building the same world from
your own coding agent on your own subscription. Give the CLI the world's link and
continue as described in [For coding agents](https://virtualmatter.ai/developers#for-coding-agents):

```sh
npx virtualmatter pull <world URL>
```

## For coding agents

If you are a coding agent working from your own harness, this is your only path. Use
the CLI from the first step, and do not prompt the built-in agent on the website.

Point your agent at [/llms.txt](https://virtualmatter.ai/llms.txt) for a platform overview and
[/AGENTS.md](https://virtualmatter.ai/AGENTS.md) for the project model and an SDK Lua cheat sheet. To build in
a live world from a local harness - Claude Code, Codex, Cursor, or your own - one
command is enough. It signs you in on first use, creates the world, and mirrors its
files into a folder that already carries the MCP registration and briefing your agent
looks for:

```sh
npx virtualmatter create "My world"   # or: npx virtualmatter pull <any world link>
cd my-world
npx virtualmatter sync                # live-push saves into the running world
npx virtualmatter open                # open it in the native client (downloaded on first use)
```

The folder's `.mcp.json` and `.cursor/mcp.json` register the MCP server for Claude Code
and Cursor. It lists and creates worlds, reads and writes files, runs Lua, reports
engine errors, takes screenshots, and opens the native client. Codex reads the folder's
AGENTS.md but has no per-folder MCP file, so register the server for Codex once:

```sh
codex mcp add virtualmatter -- npx -y virtualmatter mcp
```

In Claude Code outside a mirrored folder, register it by hand with:

```sh
claude mcp add virtualmatter -- npx -y virtualmatter mcp
```

The block below is safe to ingest verbatim.

````markdown
# Virtual Matter - context for coding agents

## Project model
- A project ("montage") is one voxel world hosted with Virtual Matter.
- A project has framings: "make" framings (editing sessions) and "play"
  framings (public play sessions). A framing is a running session slot
  on a voxel host.
- Project content = SDK Lua scripts + assets under a Montage/ tree.
  Edits made in the live session hot-reload into the running world.
  The tree can be published to a maker-owned GitHub repo.

## URL shapes (make.virtualmatter.ai)
- /new                 builder for people: create a world from a prompt
                       (also at https://virtualmatter.ai/); coding agents
                       use npx virtualmatter create instead
- /edit/<framing-id>   maker session: live world + agent chat
                       (also /edit/<slug>-<framing-id>; the CLI accepts both)
- /play/<framing-id>   play session for a specific framing
- /g/<id>              share URL resolver: 302s to a live session

## APIs (unauthenticated)
- GET https://make.virtualmatter.ai/api/v1/public/native-clients
  JSON: { iteration, clients: [{ platform, kind, url, filename,
  file_size, branch, commit, match }] } - per-platform native client
  installers (kind "download") or store links (kind "store", iOS).

## CLI + MCP (npm package "virtualmatter", Node >= 20)
- npx virtualmatter create "<name>"   create a world, mirror it into ./<slug>
- npx virtualmatter pull <link>       mirror an existing world (any link shape)
- npx virtualmatter list              your worlds with framing ids + URLs
- npx virtualmatter sync              live-push saves into the running world
- npx virtualmatter open              open the world in the native client
- npx virtualmatter mcp               stdio MCP server (list_projects,
  create_project, select_project, list_files, read_file, write_file,
  run_lua, get_engine_errors, capture_screenshot, open_native_client,
  world_info)
- Sign-in happens on first use (device code); no separate login step.
- A mirrored folder carries .mcp.json, .cursor/mcp.json, AGENTS.md and
  CLAUDE.md, so Claude Code and Cursor register the server on their own.
- Codex reads AGENTS.md but needs the server registered once:
  codex mcp add virtualmatter -- npx -y virtualmatter mcp
````

It is also served on its own at [/agent-briefing.md](https://virtualmatter.ai/agent-briefing.md).

## Play what others made

Published worlds live in the public catalog at
[play.virtualmatter.ai](https://play.virtualmatter.ai/) - no sign-in required, every
card opens a live session in the browser.