# Velven

> The community marketplace for spaces built with AI. Games, worlds, tools, wonders. Publish a folder with one command and Velven hosts it, checks it and plays it on its own page; or link a space already live on another host. Velven is where spaces get found, entered and ranked.

## Documentation

- [All docs](https://velven.ai/docs): the quickstart, hosting, the CLI, the SDK guide, publishing with an agent, the skills, the REST API, troubleshooting, the crawler and the players' guide; every guide is also served as markdown.
- [Quickstart (markdown)](https://velven.ai/docs/quickstart.md): publish a folder with `npx @velven/cli publish` (a private preview), `--prod` to go live after the safety check, publishing without an account and claiming, or linking a live URL.
- [Hosting (markdown)](https://velven.ai/docs/hosting.md): velven.json (every field), the limits, the safety check and its outcomes, previews, versions and rollback, publishing without an account, how files are served, moving a linked space onto Velven; then linking a live URL on the seven hosts, the proof tag and the framing header per host.
- [CLI (markdown)](https://velven.ai/docs/cli.md): every command of `@velven/cli` (login, publish, versions, rollback, dev, reset), its flags, JSON output, environment variables, exit codes and CI.
- [REST API (markdown)](https://velven.ai/docs/api.md): every endpoint, with hosting, boards, achievements, secrets and bans in full.
- [Troubleshooting (markdown)](https://velven.ai/docs/troubleshooting.md): the errors people hit most when publishing, listing or adding a leaderboard, and their fixes.
- [Playing on Velven (markdown)](https://velven.ai/docs/players.md): friends, rooms, comments, notifications, profiles, achievements and points, for players.
- [VelvenBot (markdown)](https://velven.ai/docs/bot.md): what the crawler fetches and how to keep it away.

## For coding agents

- [Publish with an agent (markdown)](https://velven.ai/docs/agent.md): the CLI for a coding agent, the MCP server for a chat assistant, and the listing API for a space already live elsewhere: device-code login, exact curl examples, response shapes, error codes, allowed values.
- [Publish with an agent (HTML)](https://velven.ai/docs/agent)
- MCP server: https://mcp.velven.ai/mcp (Streamable HTTP, OAuth with a Velven account when a tool needs it). Tools: publish (one page or a few files, 3 MB; a preview by default, prod: true to go live after the check; without sign-in an unlisted page with a claim token), my_spaces, versions, rollback, search_docs.
- [SDK guide (markdown)](https://velven.ai/docs/sdk.md): sign-in, hosted leaderboards, saves, achievements and stats, player content, multiplayer rooms and presence inside the frame, as one file. The leaderboard quickstart, the script tag, the npm package `@velven/sdk`, the boards block (`"trust":"client"` for a page that posts its own scores), the server tier, the local environment and the sandbox, the reference, the changelog.
- [SDK guide (HTML)](https://velven.ai/docs/sdk)
- [Add a leaderboard in 10 minutes (HTML)](https://velven.ai/docs/sdk/leaderboard-quickstart): the fastest path, a client board tested on localhost, then on Velven; also in the SDK guide's markdown.
- [SDK changelog (HTML)](https://velven.ai/docs/sdk/changelog): what each release added; also in the SDK guide's markdown.
- [Agent skills (markdown)](https://velven.ai/docs/skills.md): Velven's skills in the skills.sh format, `npx skills add velvenai/skills`, and the Claude Code plugin; the `onboard` skill publishes or lists a space, claims one, and adds the leaderboard. Source at https://github.com/velvenai/skills.

## API

- POST https://velven.ai/api/agent/login: start a login, returns a verification_url and a device_code.
- POST https://velven.ai/api/agent/token: poll with the device_code until the creator approves.
- GET https://velven.ai/api/agent/me: which creator a token belongs to.
- POST https://velven.ai/api/v1/hosting/versions: start a version of a hosted space (bearer token, or none for an unlisted page); upload the missing files to the returned URLs; then POST .../versions/{id}/finish with preview true (a 24-hour preview) or false (live after the safety check). GET .../versions/{id} for its status; .../spaces/{slug}/versions, /rollback and /reset manage it. The CLI does all of this: npx @velven/cli publish.
- POST https://velven.ai/api/spaces: list a space live elsewhere (bearer token). Hosts: Vercel, Netlify, GitHub Pages, Cloudflare, Replit, Firebase, ChatGPT sites.
- POST https://velven.ai/api/spaces/verify: prove the creator built it (meta tag).
- GET https://velven.ai/api/spaces?mine=1: the creator's spaces.
- POST https://velven.ai/api/spaces/{slug}/move: move a space to a new URL (bearer token); the new page carries the proof and allows framing.
- GET and PUT https://velven.ai/api/spaces/{slug}/boards: a space's leaderboards (bearer token); GET and PUT .../achievements its stats and achievements; POST https://velven.ai/api/spaces/{slug}/secret issues the server tier's secret; DELETE .../scores/{id}, POST and DELETE .../bans moderate.
- POST https://velven.ai/api/v1/scores, /api/v1/achievements and /api/v1/stats: a space's own server posts a score, unlocks an achievement or sets a stat with x-velven-secret and the player's identity token. GET /api/v1/scores reads a board's rows. Details in the SDK guide.
- GET https://velven.ai/.well-known/jwks.json: the public keys the identity tokens are verified against.

## Policies

- [Terms](https://velven.ai/terms)
- [Content policy](https://velven.ai/content-policy)
- [Takedown](https://velven.ai/takedown)
- [Privacy](https://velven.ai/privacy)

## In the browser

Pages expose their actions as WebMCP tools on document.modelContext (Chrome origin trial): 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. Details in the agent guide.