velven
Docs
Menu

Put your space on Velven

Publish a folder with one command and, once it passes a safety check, your space is live on Velven with its own page, clip and leaderboards. A page already live on another host can be linked instead.

View as Markdown

Sign in from your terminal

You need Node 20 or later. Nothing to install: npx runs the Velven CLI.

Terminal
npx @velven/cli login

It shows a code and opens Velven in your browser. Sign in with GitHub, Google or an email link, pick a handle if this is your first time, and press Approve.

Note: Want to try it first? Skip this step: a publish without an account makes an unlisted page you can claim later.

Publish a preview

Build your space, then publish the folder that holds its index.html:

Terminal
npx @velven/cli publish ./dist

The first time, the CLI asks for a title, the type of space and the devices it works on, and saves the answers in velven.json in that folder. It uploads the files and prints a preview link: your space, played on Velven's page, for you and anyone signed in you send it to, for 24 hours. Scores and saves made there go to a sandbox, not the live space.

velven.json has every field, and the CLI reference every command.

Go live

Terminal
npx @velven/cli publish ./dist --prod --wait

Velven opens the version as a player would and checks it against the content policy. This takes a few minutes. When it passes, the version is live on its Velven page, the take becomes its clip and thumbnail, and the space is on Velven. The CLI prints the page's address.

  • Refused: the reason is printed and nothing changes. Fix it and publish again, or press Ask for review on the space's Files tab.
  • Could not judge: the take never got past a start screen. Add a hint to velven.json, such as "start": { "click": "Play" }, and publish again.

Note: Every later velven publish --prod from the folder updates the same space, and velven rollback puts an earlier version back. Versions and rollback.

Fill in your page

Open the space's edit page from its Velven page. The Page tab holds what players read beside the frame: about, how to play, the controls, features and questions. An agent can write it from your code through the API.

Publish without an account

Run npx @velven/cli publish ./dist without signing in and Velven makes an unlisted page: live once it passes the check, with every SDK feature, but on no list or search until you claim it. The CLI prints the page's address, a claim token and a claim link, and saves the token in velven.json, so publishing again from the folder updates the same page.

The page is deleted 7 days after its first publish unless you claim it: open the claim link and sign in, or run velven login and publish again from the folder. Publish without an account has the limits.

Upload in the browser instead

Open Add a space and choose Upload files. Drop a folder, a zip or one HTML file, or paste HTML. Fill in the title, type and devices, then publish: the same check runs, and signed out you get an unlisted page and a claim link.

Or let your agent do it

A coding agent runs the same CLI for you, and an assistant in a chat publishes through Velven's MCP server. Publish with an agent has both, and agents that use skills can install Velven's skills.

Prove a linked space is yours

Signed in, the add page shows the proof tag at once. Add it to your page's <head>, with your own handle, and deploy again:

HTML
<meta name="velven" content="@handle">

Once you copy the tag or press Check now, the light checks your site every 20 seconds. You don't have to wait for it: fill in the details while the deploy goes live. When the light finds the tag, it turns green and names your handle.

Note: Only the page's own HTML counts, not a tag added by a script after load. The proof tag has the steps for each host. A space published on Velven needs no tag.

The clip

Every space gets a 5-second clip for its tile; its first frame is the thumbnail. A space published on Velven gets it from the safety check's take. For a linked space, Velven plays it in its own browser and records one after you publish, which takes a few minutes. Until it lands, only you can see the space, marked Getting ready, and a strip on its page shows the progress.

Note: To skip the wait on a linked space, press Add your own clip on the card before you publish: the space goes live as soon as it is proven. Later, open the Clip tab on the space's edit page. Under Upload your own video, press Choose a video. Under Record a new clip, say what the clip should show and press Record again; you can do this 2 times.

Claim a space

Velven lists some spaces itself, marked Unclaimed and credited to their creator. If one is yours, add the proof tag to it and press Claim on its page. Its plays stay, and it moves to your handle. An unlisted page you published without an account shows the same Claim button: claim it with its token.

Next steps

Put the badge in your README, with your own handle and your space's slug:

HTML
<a href="https://velven.ai/handle/slug"><img src="https://velven.ai/badge/slug" alt="On Velven"></a>