Package & distribute

Declare production files#

A .curio archive contains the production manifest, UI assets, Backend executable if needed, contracts, and other declared runtime files. Define explicit contents in your source manifest:

{
  "build": { "command": ["npm", "run", "build"] },
  "package": { "files": ["dist/ui", "contracts", "assets/icon.png"] }
}

This is a fragment. List only files your project actually produces. A UI-only project without contracts or an icon should use ["dist/ui"]. Include any required licenses and third-party notices with the runtime output.

package.files is a list of relative files/directories, not globs. Commands use argv arrays; a build script needing shell syntax must invoke a shell explicitly.

Build a verified archive#

trove check
trove pack

pack runs the declared build, copies files to isolated staging, validates production entries and contracts, and writes dist/packages/<id>-<version>-<target>.curio. UI-only packages are platform-independent (any); Backend packages target the current platform architecture.

Development, build, package, and bindings fields are removed from the archived manifest. The source manifest is left intact. .env*, .trove, .git, development SDK vendor files, and .curio outputs are excluded. Runtime files in node_modules must be explicitly included; this does not provide a Node runtime.

trove pack --dry-run --json
trove pack --out ~/Desktop/my-tool.curio
trove pack --overwrite --no-input

Dry-run only reports a plan; it does not run the build or validate its future output. Existing outputs require interactive confirmation or --overwrite. A failed build does not produce a new successful package; an old output may still remain, so check the command’s result before publishing.

Install and test locally#

Stop the development session, then install:

trove install

With no file argument, the CLI looks in the current project’s dist/packages/. One candidate is selected automatically; multiple candidates need a choice or an explicit file in noninteractive mode:

trove install ./dist/packages/dev.example.notes-0.1.0-any.curio --no-input --json

Use your actual output filename. Open the installed Curio from Trove with the development server stopped. Check navigation, assets, SDK calls, contracts, and Backend startup. install waits for Host’s actual success or failure.

Native runtime requirements#

Host requires a self-contained native Backend executable for the target platform; it does not bundle Node or Python. Verify every published architecture, executable permissions, and required runtime files.

The Rust Backend template in trove new includes native builds, type export, and client generation. trove pack runs these steps and validates the artifact. Node examples demonstrate protocol interoperability; a JS bundle is not a runtime-independent native artifact. See the Backend guide.

Publish through a software source#

pack does not upload a file, bump a version, or register a source. You publish a .curio archive and a Source Index entry through your chosen source. The Source Index schema describes the required format.

Trove supports Git, HTTP(S), and local-file indexes. A Git source reads source/index.json from the remote default branch; artifact URLs can refer to paths relative to source/ or absolute HTTP(S) downloads. HTTP/local indexes use absolute HTTP(S) or file:// artifact URLs.

The index identifies each Curio/version and provides artifact target, URL, byte size, and SHA-256. Host verifies these before installation. Generate size and hash from the final archive, not intermediate build files:

shasum -a 256 ./dist/packages/dev.example.notes-0.1.0-any.curio
wc -c < ./dist/packages/dev.example.notes-0.1.0-any.curio

Use your real package path. Prerelease builds may replace an existing version/architecture pair during development; stable releases require a new version. For packages stored in Git, commit index and artifacts together to keep a consistent source snapshot.

Submit to the official source#

Loading the latest contribution guide…

Credentials and availability#

Git index access uses the machine’s Git/SSH configuration. HTTP release attachment downloads are anonymous: Host does not reuse Git credentials, account tokens, or browser cookies for them. An SSH-accessible index does not make a login-protected release attachment downloadable.

Publish artifacts at addresses accessible to the intended users without HTTP login, and keep credentials out of index files. In Trove, add the source with an ID matching its index, refresh it, and verify installation from that source.

When installations and updates take effect#

Installation validates the complete artifact before storing it by SHA-256. Different builds of the same version remain distinct artifacts; running code is not overwritten in place.

If a UI is running, the new artifact waits until the next window open. For headless tools, Host stops managed processes before switching; the next request starts the new artifact on demand. Development sessions reference the project directory and do not replace installed artifacts. Failed transitions retain a recoverable valid state.

Installation sources remain pinned. Confirm a source change in Host, or use trove install file.curio --switch-source. Data remains associated with the Curio ID. Legacy installation metadata is backed up before migration. After installation, open the tool and verify the Run origin and artifact in the debug console.