Package and publish
A package is the same bytes whether it runs from your plugins folder or from the marketplace.
One package, two routes
The folder in ~/.bentobox/plugins and the archive you upload hold the same bytes. Locally it runs as source; uploaded, the server compiles it to bytecode and signs it, and the client only runs marketplace bytecode that carries that signature. How your code is protected has the details.
A package that works locally can still hit the published limits once uploaded. Limits and permissions has the details. A package that runs from your plugins folder and is rejected on upload is a bug in validation, not something to work around by repacking.
Make the archive
Compress the plugin folder with anything: Explorer, PowerShell, 7-Zip or zip. The marketplace accepts stored and deflated members, folder records, backslash separators, timestamp extra fields, and the wrapping folder that compressing a folder produces.
- Entry
src/main.luau- Manifest
- None. A
plugin.tomlis rejected. - Maximum size
- 64 MiB compressed
- Media type
application/vnd.bento.plugin-source+zip- Source
- Luau under
src/, and tests undertests/ - Assets
- PNG, JPEG, WebP, JSON, TOML, text, CSV or Markdown under
assets/, each named from source (JPEG and WebP ship as PNG, and the client decodes only PNG, so use PNG to see an image before you upload); and audio as.wav,.ogg(Vorbis),.mp3or.flac, at most 30 seconds, 48 kHz and stereo. Audio ships as WAV whatever it was written as: read it withAsset.bytesand play it withaudioPlayer:playBytes
Anything else is refused, with one exception: the builder ignores git's own files, and types/, .git/, .vscode/, an AGENTS.md and a README.md beside src/, so an archive of a scaffolded folder uploads as it is.
The archive need not be byte-for-byte reproducible: the same source compressed twice by different tools gives different archives, and both upload. If you want the digest to be stable, for a release pipeline say, sort the members and drop folder records and extra fields. The CLI below does this.
Who can publish
Any account with an active plan can publish.
An account blocked from publishing cannot upload or change listings. Your plugins says so if yours is.
Create the listing
Plugin ids are assigned by the server, so every plugin starts on the site: create it on Your plugins, then upload the archive to it. A draft can go live once all of these are set:
- Name, up to 80 bytes.
- Summary, 1 to 180 bytes: the line on the storefront card.
- Description, up to 10,000 bytes of Markdown.
- Category, one of Combat, Skilling, Minigames, Money making and Utility. Default is reserved for the plugins Bento publishes itself, and only Bento sets it. Those are added to every account's library, and stay out of it once someone removes them.
- Gallery, 1 to 6 images, each under 8 MiB and at most 4096 px on the long edge. The first image is the cover art everywhere a card is drawn; there is no separate icon field.
- Price, in credits per month, up to 1,000,000. Zero means free.
- A successful build: see the next section.
The only icon in the product is your plugin's own side-panel icon, which the plugin sets from its own assets (icon in its Plugin.new descriptor) rather than from the listing.
Release a version
Uploading source starts a build. The build compiles and signs the bytecode and, on success, binds it to the plugin: there is no separate step to publish a version. Listing a plugin on the storefront is the one extra step, and only applies while it is still a draft.
- Upload the ZIP. The response returns at once, before the build finishes.
- Poll the submission until it reaches a final state.
- On success the new build is live for anyone entitled to the plugin. On failure the diagnostics name the file and line.
A first upload to an unfinished draft reports awaiting_listing instead: the build succeeded, but nothing was bound because the listing is incomplete. Fill in the fields above and upload again.
From the command line
@bentobot/cli does the whole push: it packages the folder, gets an upload ticket, uploads, and follows the build. It has no dependencies and needs Node 22 or newer.
npx @bentobot/cli login
npx @bentobot/cli push <plugin id> ./food-watch --version 1.0.0 --changelog "First release"--version is the heading the release sits under in the changelog and --changelog says what changed; both are optional. The plugin id is the last part of the plugin's address in Your plugins: /plugins/yours/<plugin id>.
The CLI uploads everything in the folder except types/, the README.md beside src/, .git/, .vscode/, node_modules/, dist/, .bento/ and git's own files. The archive is byte-reproducible (sorted members, fixed timestamps, no extra fields), and the upload's idempotency key comes from the plugin id and the archive's digest. A retried push of unchanged source returns the submission already in flight instead of starting a second build, and pushing it again with a corrected changelog updates that entry without rebuilding.
npx @bentobot/cli pack writes the same archive without uploading it, if you would rather upload from the site or check what is in it.
login stores a refresh token in ~/.bentobox/cli-credentials.json with mode 0600. It is not an OS keyring; on a shared machine, run npx @bentobot/cli logout when you are done, which revokes the grant on the server as well as deleting the file.
The HTTP API
The CLI is a thin client over these. Sign-in is OAuth with PKCE against a loopback redirect, scoped to plugin:publish, and the consent screen is /developers/cli/authorize. Access tokens last 10 minutes; the refresh token keeps the sign-in alive for up to 30 days.
| Step | Request |
|---|---|
| Authorize | GET /api/v1/developer-cli/authorize |
| Exchange the code | POST /api/v1/developer-cli/token |
| Scope an upload | POST /api/v1/developer-cli/upload-ticket |
| Send the source | POST /api/v1/plugins/:id/submissions |
| Poll the build | GET /api/v1/plugin-submissions/:id |
| List a draft | POST /api/v1/plugins/:id/publish |
The upload ticket binds the plugin id, the archive's SHA-256, its exact byte length and an idempotency key. It lasts 5 minutes and is spent on one attempt. The ticket goes in the Authorization header of the submissions request in place of the access token; the poll uses the access token again.