botminds.aiRequest a demo

Academy · Solutions · Ship it

Package & ship a solution

In one line. Package the solution you built once as a recipe, publish it to a Hub, and install it into a fresh project for the next team — without copying a single document, credential, or tenant id. You’ll build. A published Solution: snapshot and freeze Project A, publish it to the signed Hub with a setup guide and sample data, install it as Project B, wire Project B’s own credentials and model, and prove it by running a sample invoice end to end. You’ll use. Build: Invoice processing · Access & roles · Hubs & distribution · Glossary

The setup: you built the invoice solution in Build: Invoice processing. It works — for one team, in one project. Now Finance West wants it. Then the German subsidiary. Then a customer. Rebuilding it by hand each time is slow, error-prone, and drifts: version three quietly differs from version one. You want to build once and deploy to many.

The load-bearing idea: structure travels; data doesn’t. A package carries agent instructions, schemas, pipeline steps, guard rails, dashboards — never your documents, vectors, or model keys. You’ll take Project A (the finished invoice solution) and stand up a working copy in Project B (the next team), passing through a Hub in between. Plan for about 45 minutes; the full publish / install / REBIND mechanics live in Hubs & distribution.

Two grains of packaging exist, and you’ll see both:

Solution (whole project) Object Package (single object)
You ship The entire invoice project Just the Invoice Extractor agent
It installs into a new project (or an existing one, via Install here) an existing project
Use for standing up the whole app for a new team or tenant adding one reusable piece to a project that exists

Honesty callout — read before you start. The whole-project Solution path (the stages below) is the established, shipped way to distribute a solution today. The per-object Object Package track is partly forward-looking: the per-object publish → import → REBIND flow does ship, but the fuller design — signed single-object packages, an install wizard with schema-compatibility verdicts, per-object upgrade-in-place, a rollback ledger — is designed but not fully built (whole-project Solutions do upgrade in place and roll back on the signed Hub today). Treat EMBED / DECLARE / REBIND as the mental model (it already explains today’s behaviour), and when in doubt, ship a Solution.

Steps

Stage 1 — Prepare the source: commit, snapshot, freeze

(Project A · shipped)

You never publish a moving target. Lock the configuration first; you’ll describe the package at publish time.

  1. In Project A, open Studio ▸ Project ▸ Version Control.
  2. On the History tab, click Commit… and record a checkpoint — message e.g. “v1.0 invoice solution — ready to ship”. This is your named, rollback-able milestone.
  3. Switch to the Snapshots tab and take a full export — your belt-and-braces copy before you hand the solution to other teams.
  4. Switch to the Governance tab and click Freeze. The freeze-status chip (top-right) flips from green Active to red Frozen. Frozen configuration gates destructive edits, so nobody quietly rewrites the recipe you’re about to publish.

Tip — the shipping rhythm. Commit at each milestone, snapshot before anything risky, freeze once a solution is stable and shipping. Unfreeze only when you genuinely need to change it, then re-freeze.

Checkpoint. The version-control chip reads Frozen, and your commit shows in History.

You’ll describe and publish the package in Stage 3 — but first understand exactly what ships, in Stage 2.

Stage 2 — Know what ships: EMBED / DECLARE / REBIND

(conceptual · the mental model — applies today)

When you publish, the platform walks the solution’s dependency closure — every object it needs to run — and classifies each edge into one of three buckets. This is why some fields appear in the publish dialog and others don’t, and why the import asks you to pick local objects. Walk your invoice solution piece by piece:

Piece of the invoice solution Class Ships? Why
Invoice Extractor agent — instructions, persona, sub-agents, skills, guard rails EMBED Yes, by value Pure config — re-created with a fresh id in Project B.
The dashboards (Intelligence) EMBED Yes, by value Shipped as part of the Solution.
The LLM model the agent uses DECLARE No An environment capability. The package says “I need a GPT-4-class chat model”; it never carries your endpoint or API key. Project B must already have one.
Any MCP server the agent calls; the platform version DECLARE No Required at the destination, with its own credentials — verified at install, never shipped.
The Invoice collection schema / view the agent reads and writes REBIND No — the binding travels, not the data A project-local data dependency. The package carries a named slot plus a description (“the invoices view”), and the importer wires it to one of their collections or views at install.
A Datasheet the agent queries (if your build used one) REBIND No Same: a slot plus description, bound to Project B’s datasheet at install.
Your invoices, extracted values, vector index — No, ever Data. Sanitized out at publish. Project B starts empty.
Your model keys, tenant ids, secrets — No, ever Stripped at publish. Nothing sensitive ships.

Read the table top to bottom and you have the whole model: EMBED = config shipped by value; DECLARE = capability required, never shipped; REBIND = a data dependency wired at install. Structure travels; data doesn’t.

Tip. On the agent-object track, the REBIND rows are exactly the textareas in the publish dialog and the dropdowns the importer fills in. On the signed-Solution track, the DECLARE rows surface as the install compatibility check: the preflight requirement rows and the credentials preview the installer sees before committing — see Stage 4.

Stage 3 — Publish to the Hub

(Project A · shipped)

Two choices of where the package lands, matching the two grains: publish the whole project (this build’s main path — a signed Solution on the Hub), or publish just the Invoice Extractor agent to the Agents registry (covered under production notes below).

  1. In Project A, open Studio ▸ Hubs ▸ Solutions and click Publish to Hub. (If your workspace has several Hub servers registered, the Target hub picker chooses where it lands — the registry of hubs itself is workspace-Admin-only.)
  2. Describe the package in the modal, for a stranger:
    • Name / Version / Category / Summary — e.g. Invoice Processing, 1.0, Finance, one sentence on what each team gets.
    • Listing icon — small PNG/SVG.
    • Overview & setup guide — markdown, with a live preview. This becomes the Solution’s Setup guide tab; write what the installer must do on day one.
    • Sample / demo data — attach a test invoice or two. They ship with the Solution (stripped of secrets) and power Run demo after install.
    • Demo entry point — optionally, the project route “Run demo” should open on.
  3. Click Publish to Hub. A live per-stage progress bar runs (framing → packaging → signing → uploading), then the receipt shows exactly what shipped: asset count, bytes, content hash — secrets redacted.

Under the hood. Behind Publish, the platform sanitizes the package — drops every document, vector, secret, and tenant id — signs it, hashes it, and registers it on the environment-independent Hub. It also stamps the package with the platform version of the ring it was built on, which is what the install-side preflight checks. Full mechanics: Hubs & distribution.

Checkpoint. Your Invoice Processing Solution appears under Browse all solutions on the same page, with a Signed pill and v1.0 — no admin approval is needed to publish; governance kicks in at install and at production promotion (Stage 4).

Stage 4 — Browse, preflight, and install

(Project B · shipped)

Now play the receiving team. For the Solution track the install creates the new project for you, so you can start from any context that can reach the Hub — the workspace’s Import from Hub entry opens the same marketplace without a project.

  1. Open Studio ▸ Hubs ▸ Solutions. The marketplace opens on a collapsible Featured rail, then a split master–detail browser: search or filter the list on the left, and select Invoice Processing to load its detail pane.
  2. Read before you install: the Overview tab (summary + the dev → stg → prod promotion ladder), the Setup guide tab (your Stage 3 markdown), Version history, and Samples.
  3. Preflight. In Overview, click Check install compatibility. You get: signature ✓, each requirement marked met or missing (the platform row is real — a Solution built on a newer ring fails preflight on an older one), and the credentials preview: “you’ll need to configure N credentials”, with counts and where (connection keys, script secrets) but never values. Missing rows are exactly your DECLARE dependencies — fix them before installing.
  4. Install. Click Install as new, name the project (e.g. Invoice Processing — Finance West), and Confirm & Import. A live per-stage progress bar runs while the platform verifies the signature, unpacks the modules, and creates the project — Invoice collection schema, extractor agent, skills, guard rails, the Four-Eyes lifecycle, dashboards, all minted with fresh ids. No invoices come across; the new project starts empty of data. (Inside an existing project, Install here drops the modules into it instead.)

Governance on this path. Some installs are approval-required — the result panel then offers a one-click Approve & install, keeping the gate with the platform, not the package. Shipping a Solution up the ladder is governed harder still: Ship to stg executes immediately, but Request production release queues for a superadmin’s Hub Release Approvals — and the target hub is frozen at request time, so if the destination registry changes before approval, the approval is refused. Details: Hubs & distribution.

Stage 5 — Wire the destination: credentials and REBIND slots

The install re-created your collections and modules, but the DECLARE dependencies still need Project B’s capabilities — exactly what the Stage 4 credentials preview promised.

On the Solution track (this build): the Configure imported credentials dialog opens automatically after install. Bind Project B’s LLM model / key (not yours — it never shipped) and fill the connection keys and script secrets the preview counted; you can start with demo values and add real ones later. Two extras land with the project: the sample files + setup guide appear in a “Solution Samples” File Drive folder (one click from the result panel), and Run demo with sample data pushes the shipped samples through the normal intake so you can watch the solution work before touching real data.

On the agent-object track (a single agent imported from the Agents registry), a configuration dialog opens instead — for each REBIND slot, pick a local object:

+- Import: Invoice Extractor -------------------------------[x]-+
| This needs you to map the following to your project:          |
|                                                                |
| LLM Model *   [ Select a model      v ]                        |
|   "any GPT-4-class chat model"          <- the publisher's     |
|                                            note (DECLARE)      |
| View *        [ Select a view       v ]                        |
|   "the invoices view"                      (REBIND)            |
|                                                                |
| Datasheet *   [ Select a datasheet  v ]                        |
|   "invoice line-items table"               (REBIND)            |
|                                          [ Import ]            |
+----------------------------------------------------------------+
  1. LLM Model (required) — pick Project B’s GPT-4-class model. This is the DECLARE dependency resolving to a local capability: Project B’s key, not yours.
  2. View (required) — pick the invoices view in Project B (or the one the Solution just created). This is the REBIND slot binding the agent to this project’s data.
  3. Datasheet (required, if the agent referenced one) — pick Project B’s. Each field shows the description you wrote at publish time, so you know exactly what to choose.
  4. Click Import. The platform mints fresh ids for the embedded pieces and binds the slots to the local objects you picked.

Checkpoint. On the Solution track the result panel reads “✓ Created project …” with your samples materialized; on the agent track you get an “…imported successfully” toast. Either way, the installed agent appears in Project B’s Agent Builder ▸ Agents.

Stage 6 — Prove it: a plain project object that runs

(Project B · shipped)

The reassuring payoff: an installed object is just a normal project object. There is no special “imported” mode to learn.

  1. In Project B, open Studio ▸ Agent Builder ▸ Agents. The Invoice Extractor is there like any agent you’d build by hand — open it; every reference resolved to this project’s model, view, and datasheet, not Project A’s.
  2. Confirm the Invoice collection, its schema and labels, the Four-Eyes lifecycle, and the dashboards came across.

Then the real proof that structure travelled and the binding works — run a sample invoice end to end:

  1. In Project B’s Consumer App, open the Invoice collection (App ▸ Documents) — it’s empty. Good: no data shipped.
  2. Upload a single sample invoice PDF (reuse the test invoice from Build: Invoice processing).
  3. Watch the live progress chip: the installed Invoice Extractor, running on Project B’s bound model, extracts the fields — total, vendor, dates — exactly as it did in Project A.
  4. Follow the invoice through the Four-Eyes lifecycle (Intake → AI Processing → AI Recommendation → L1 Review → L2 Approval), reviewing and approving as before.
  5. The invoice reaches Approved in Project B.

You moved a complete solution between projects without copying a single invoice. The recipe travelled; the data started fresh.

If extraction fails or the agent errors: it’s almost always an unresolved DECLARE — Project B doesn’t have a matching LLM model, or you bound the wrong one. Re-open the agent and check the model picker (or re-open the credentials dialog). The Stage 4 compatibility check and credentials preview would have flagged this before install — run it again to see which row is missing. Empty pickers in the REBIND dialog usually mean the target object — a view, a datasheet — doesn’t exist yet in Project B: create it first, then re-import.

Make it production-worthy

  • Make Stage 1 a habit, not a one-off. Before each re-publish: Commit a milestone, Snapshot (full) for safety, Freeze so the published recipe can’t drift. To ship v1.1: unfreeze → edit → re-commit → re-snapshot → re-freeze → Publish to Hub again, choosing Publish the next version. Every project installed from the Hub then shows an update available banner: upgrade in place (keeps documents, queues and history; auto-saves a rollback snapshot) or install side-by-side — and the ⋯ ▸ Roll back menu returns a project to any prior published version.

  • Ship a single agent when the team already has a project. Sometimes the next team just wants the extractor agent, not a whole new app. In Project A, open the Invoice Extractor in Studio ▸ Agent Builder ▸ Agents and use its ⋮ ▸ Publish: logo, Name, Description, Tags, plus the dependency description textareas (model = DECLARE; view/datasheet/collection = REBIND). Publish lands it in Studio ▸ Hubs ▸ Agents; in an existing Project B, open that tab, select it, Import, and resolve the REBIND slots as in Stage 5. The agent drops in as a plain agent — no new project created.

    Coming soon / by design. The per-object publish → import → REBIND flow above ships today. The fuller Object-Package design — signed single-object packages, an install wizard reporting schema-compatibility verdicts (exact / compatible / extendable / incompatible) per REBIND slot, upgrade-in-place vs install-as-copy, and a rollback ledger — is designed but not fully built. Use today’s REBIND flow; don’t expect the full wizard yet. For anything mission-critical, ship a whole Solution.

  • Govern both ends. Freeze Project A’s config before publishing, so the published recipe is the blessed one; ship across environments up the promotion ladder — Ship to stg is immediate, Request production release waits for a superadmin’s approval, with the target hub frozen at request time (Hubs & distribution). And set up roles in Project B after install — the Solution carries the lifecycle and stage gates’ shape, but you assign L1-Reviewer / L2-Approver to the new team’s actual people in Studio ▸ Security (Access & roles). Roles are people-bindings: they don’t, and shouldn’t, ship.

What to keep from this build: structure travels, data doesn’t — a package is a recipe, not a copy. Every dependency is EMBED (shipped by value), DECLARE (required at the destination, never shipped), or REBIND (wired at install); memorise which bucket each kind falls in and you can predict the whole publish-and-install experience. Commit, snapshot, freeze before you publish; assign roles in the destination after you install. The worked builds taught you to build solutions — this one taught you to ship any of them: package once, install everywhere, with nothing sensitive leaving the building.

Where to go next

Prefer learning inside the product? The same academy lives in the platform's Learn menu — every screen links to the chapter that explains it.

See the platform live