Publish with an agent

Choose a way in#

Ask the creator for the space's title, its type and the devices it works on, or take them from what they already said. Never guess them: they are the listing people see.

Publish with the CLI#

Run the CLI with --json, so every command prints one JSON object, and --yes, so it never waits on a prompt. The CLI reference has every flag and exit code.

npx @velven/cli login                                   # prints a code and a link: show both to the creatornpx @velven/cli publish ./dist --title "Orbit Dodger" --type game --devices desktop,mobile --yes --jsonnpx @velven/cli publish ./dist --prod --yes --wait --json   # when the creator asks to go live

• login prints the code and the approval link and waits until the creator approves. Show them both; the token is saved for this creator's later publishes.
• The first publish writes velven.json into the folder, with "space"; keep it, so later publishes update the same space.
• A plain publish answers status: "preview" and a previewUrl to show the creator. With --prod --wait it answers the verdict: live with pageUrl, or refused or unjudged with reason and shownOnTake, exit 6.
• For unjudged, add a start hint to velven.json, such as "start": { "click": "Play" }, and publish again. For refused, tell the creator the reason; they can ask for a review from watchUrl.

Without login, the same publish makes an unlisted page and answers pageUrl, claimToken, claimUrl and expiresAt, and terms. Show the creator all of them, say the page is deleted after 7 days unless they claim it, and that publishing means they agree to Velven's Terms. Running login and publishing again from the folder claims it.

Publish from a chat with the MCP server#

Velven's MCP server is at https://mcp.velven.ai/mcp (Streamable HTTP). Add it to an assistant as a custom connector, or to Claude Code with its plugin or one command:

claude mcp add --transport http velven https://mcp.velven.ai/mcp

A tool that needs an account makes the app ask the creator to sign in to Velven and approve the connection in their browser. Without signing in, publish makes an unlisted page and answers its address, a claim token, a claim link and a Terms line: show every one of them, and tell the creator to keep the token, the only way to update the page or keep it past 7 days. Signed in later, publish with claim claims it.

Keep the clip current#

After listing, Velven plays the space in its own browser and records a 5-second clip; its first frame becomes the thumbnail. When the site is rebuilt, Velven's background check notices the change within 6 hours and records again. A space published on Velven gets its clip from the safety check of each version that goes live.

After a deploy that changes how the space looks, ask for a retake at once. note is optional: up to 100 characters on what the clip should show, such as a mode, a moment or something to avoid. The creator gets 2 retakes per space; the background check's own do not count.

curl -s -X POST https://velven.ai/api/spaces/recapture \  -H "authorization: Bearer $VELVEN_TOKEN" \  -H "content-type: application/json" \  -d '{ "slug": "orbit-dodger", "note": "start after the title screen, night mode" }'

Your space's page#

Under the frame, the space's page says what the space is, how to play it and which keys do what. Velven writes this text from its own recording, but you know the project better: write it from the code and send it with the listing, or change it later. Every field you send is the creator's, and Velven's recording never writes over it, not even a field you cleared.

Take the controls from the input handlers (the key bindings, the pointer and touch events), the goal and the rules from the game logic, and the features from what the project actually does. Write plainly, in the second person, for someone about to play. For a world, a tool or a wonder, leave out how_to_play and controls if they do not apply.

In the body of POST /api/spaces, beside the other fields:

{  "about": "Orbit Dodger drops you into a decaying orbit full of debris. Every lap is faster than the last.",  "how_to_play": "Stay alive as long as you can. Collect fuel cells to climb back to a higher orbit.",  "controls": [    { "label": "Keyboard", "rows": [{ "input": "Left / Right", "action": "Thrust" }, { "input": "Space", "action": "Boost" }] },    { "label": "Touch", "rows": [{ "input": "Swipe", "action": "Thrust" }] }  ],  "features": ["Procedural debris field", "A new orbit every run"],  "orientation": "landscape",  "players": "single"}

If the listing is made but its page text could not be saved, the 201 response carries "page_not_written": true. The space stands without the text; send the same fields again with PATCH /api/spaces/{slug}.

To read the page as it stands, with who wrote each field in page_authors (model for Velven, creator for you), call GET /api/spaces/{slug}. To change it, send any of these fields, or any of the listing's own (title, description, space_type, engine, models, ai_tools, devices, how_made, source_url), to PATCH /api/spaces/{slug}. Only the fields you name change, and null clears one. Both answer the space's fields.

curl -s https://velven.ai/api/spaces/orbit-dodger -H "authorization: Bearer $VELVEN_TOKEN"curl -s -X PATCH https://velven.ai/api/spaces/orbit-dodger \  -H "authorization: Bearer $VELVEN_TOKEN" \  -H "content-type: application/json" \  -d '{ "features": ["Procedural debris field", "Daily seed"], "faq": null }'

Move to another host#

When the space moves to a new URL, move its listing with it. Its slug, plays, likes, boards, scores, saves and page text stay. Velven checks the new page as it checks a listing, so first put the proof tag on the new page and allow framing there, deploy, then call:

curl -s -X POST https://velven.ai/api/spaces/orbit-dodger/move \  -H "authorization: Bearer $VELVEN_TOKEN" \  -H "content-type: application/json" \  -d '{ "url": "https://orbit-dodger.vercel.app" }'

It answers the space's fields as GET /api/spaces/{slug} does, with previous_url. Every refusal and its code is in the REST API.

• If a server posts scores, set the board secret in the new host's server environment: copy the existing one if you have it, or issue a new one with POST /api/spaces/{slug}/secret, which replaces the old one at once, so the old host stops posting.
• Identity tokens name the new origin as their audience (aud) from the move on. A server that checks aud must expect the new origin; tokens issued before the move carry the old one for up to an hour.
• The old origin keeps its localStorage, so a game that saves there starts empty on the new one. Velven.data saves belong to the space and move with it.

Leaderboards and sign-in#

If the space keeps a score, give it a hosted leaderboard and sign-in with the Velven SDK. The SDK guide covers all of it, and https://velven.ai/docs/sdk.md is the same guide as one file for you to read. In short: load the script or install @velven/sdk, declare the boards in a <script type="application/velven+json"> block beside the proof tag (or in velven.json for a space published on Velven), and post scores with Velven.scores.submit. The space draws its own boards from top and around; a board declared with display page or both also shows on its Velven page. Achievements are declared the same way.

<meta name="velven" content="@handle"><script type="application/velven+json">{"boards":[{"key":"main","trust":"client","metric":"points","sort":"desc"}]}</script><script src="https://velven.ai/sdk/v1.js"></script>

Choose a tier for each board. trust: "server", the default, takes posts only from the space's own server, with the space's secret and the player's token; a page's own post to it answers server_only. trust: "client" takes the page's posts within a range, a cooldown and caps. A space with no backend uses client, as in the snippet above; Server scores helps choose.

A server board needs the secret, issued on the creator's token and shown once. Put it in the host's server environment, never in the page:

curl -s -X POST https://velven.ai/api/spaces/<slug>/secret -H "authorization: Bearer $VELVEN_TOKEN"

Boards can also be declared or changed without a deploy, in the same shape as the block. Only the boards named are written, and the page's next sync overwrites a key it also names:

curl -s -X PUT https://velven.ai/api/spaces/<slug>/boards \  -H "authorization: Bearer $VELVEN_TOKEN" \  -H "content-type: application/json" \  -d '{"boards":[{"key":"main","trust":"client","metric":"points","sort":"desc","min":0,"max":100000,"cooldown":5}]}'

Reading the boards is in the REST API, and deleting a submission or banning a player under Moderation.

Claim a space Velven listed#

Velven lists some spaces itself. They show as unclaimed at /s/slug, and a duplicate answer on submit can point at one. With the proof on the site, claim it for the creator: its plays stay, and it moves to their handle.

An unlisted page published without an account is claimed with its token instead: run velven login and publish again from the folder that holds its velven.json, or have the creator open the claim link.

curl -s -X POST https://velven.ai/api/spaces/verify \  -H "authorization: Bearer $VELVEN_TOKEN" \  -H "content-type: application/json" \  -d '{ "slug": "orbit-dodger" }'

Allowed values#

space_type#

• game Game
• world World
• tool Tool
• wonder Wonder

engine#

• three.js Three.js
• r3f React Three Fiber
• babylon.js Babylon.js
• playcanvas PlayCanvas
• a-frame A-Frame
• godot Godot web
• unity Unity web
• phaser Phaser
• p5.js p5.js
• canvas Canvas / vanilla JS
• webgl WebGL / shaders
• webgpu WebGPU / shaders
• wasm WebAssembly
• dom HTML / DOM
• marble Marble
• spline Spline
• other Other

models#

• claude-fable-5.1 Claude Fable 5.1
• claude-opus-5.5 Claude Opus 5.5
• claude-opus-5 Claude Opus 5
• claude-sonnet-5 Claude Sonnet 5
• gpt-6-astra GPT-6 Astra
• gpt-6-sol GPT-6 Sol
• gpt-6-luna GPT-6 Luna
• gpt-5.6-sol GPT-5.6 Sol
• gemini-3.8-flash Gemini 3.8 Flash
• muse-spark-1.3 Muse Spark 1.3
• grok-4.7 Grok 4.7
• grok-4.6 Grok 4.6
• kimi-k3 Kimi K3
• glm-5.3 GLM-5.3
• jev Jev
• other Other

ai_tools#

• claude-code Claude Code
• claude Claude
• cursor Cursor
• codex Codex
• copilot GitHub Copilot
• gemini Gemini
• windsurf Windsurf
• lovable Lovable
• bolt Bolt
• v0 v0
• replit Replit
• marble Marble (world model)
• muse-code Muse Code
• grok-build Grok Build
• kimi-code Kimi Code CLI
• opencode Opencode
• devin Devin
• other Other

devices#

• desktop Desktop
• mobile Mobile
• vr VR headset

In the browser#

If you drive a browser instead, Velven's pages expose their actions as WebMCP tools on document.modelContext. Call those rather than reading the page: search_spaces on every page; inspect_space_url and publish_space on /add; check_claim and claim_with_token on a claim page; enter_space, upvote_space, save_space and report_space on a space page; email_sign_in_link and choose_handle on sign-in.

On the add page, inspect_space_url works signed out. publish_space needs the creator signed in: it lists the space at once when the proof is already on the site, and otherwise keeps the details, shows the proof steps and re-checks the site until it clears. Chrome ships WebMCP in an origin trial; other browsers see the same pages without the tools.