Importing and exporting toolkits

Toolkits are portable. You can export the toolkits you’ve built or customized, and you can import toolkits someone else has shared with you, without going through the public library.

The .jtf.json file

A toolkit is a single .jtf.json file (Jootle Toolkit Format, JSON-based). The file contains:

• The toolkit’s manifest (name, version, description).
• All its entity definitions, playbooks, goals, and adapters.
• Optional starter data (sample entities, default settings).

It does NOT contain:

• Your data. The toolkit is the template; your data is separate.
• Your secrets or credentials. Those live in your instance, not in the toolkit file.

A typical toolkit file is between 5KB (a simple list-style toolkit) and 200KB (a complex toolkit with many entities and playbooks). Most are well under 100KB.

Exporting

From Settings → Toolkits, find the toolkit you want to export and click Export. You get a .jtf.json file.

Two flavors of export:

• Bare export. Just the toolkit definition, no data. The recipient installs and starts fresh. Good for sharing the toolkit’s design.
• Export with sample data. Includes a small set of sample entities. Good for showing what the toolkit looks like in use.

You choose at export time. Most public sharing uses bare exports.

Importing

From the library or Settings → Toolkits, choose Import from file. Drop in a .jtf.json file. Your AI parses it, validates the schema, shows you what the toolkit adds, and asks you to confirm install.

Before clicking install, you should review:

• What entities it adds. Names, fields, relationships.
• What integrations it requires. API keys, external services.
• Who built it. The manifest names the author.

Imports from sources you trust (a colleague, a vendor you work with, your own export) are routine. Imports from sources you don’t know should be reviewed carefully, the same way you’d review any file you got from a stranger.

Signed vs. unsigned imports

Toolkits in the public library are signed by Jootle. Toolkits exported from your own instance are unsigned (which is fine, you trust yourself).

Unsigned imports from external sources install with a warning. You can override the warning if you’ve verified the source. The warning exists to make sure you’re making an explicit decision, not accidentally installing something.

If you receive a toolkit you’d like Jootle to verify and sign (for example, your business builds a toolkit for clients and wants it trusted), you can submit it through the library submission flow.

Use cases

Sharing across your own instances. You have a personal Jootle and a business Jootle, and you want a toolkit on both. Export from one, import to the other.

Sharing with a colleague. You built something useful for your work; a colleague at another company wants it. Export, send, they import.

Onboarding a client. Your consulting business builds a custom toolkit for a client. You install on their instance via import, rather than them having to build it themselves.

Versioning your own toolkits. Each time you ship a new version of a custom toolkit you’re maintaining, export to a versioned file (my_toolkit_v3.jtf.json). If a future version breaks something, you can re-import the old one.

Roundtrips

You can export a toolkit, modify the JSON, and re-import. This is how developers iterate on custom toolkits outside the conversational flow.

Some edits require an explicit version bump (changes to entity schema, for example, since they affect existing data). The format handles migrations declaratively: if you bump the version and add a field, existing data gets the new field with a sensible default.

The full schema migration rules are in the JTF spec (developer reference).

Removing an imported toolkit

Imported toolkits uninstall the same way as library toolkits. You don’t need to keep the source .jtf.json file; the toolkit’s contents live in your instance once installed.

Uninstalling preserves your data by default; deleting it is a separate explicit action.

File hygiene

If you’re sharing .jtf.json files:

• Use a clear filename. crm_v2.jtf.json beats toolkit.jtf.json.
• Keep your custom toolkits in version control if they’re nontrivial. Git is a fine fit.
• If a toolkit has external dependencies (specific API keys, SaaS accounts), document them outside the file too, so the recipient knows what they’re signing up for.

When NOT to use import / export

A few cases where there’s a better path:

• Backing up your data isn’t done via toolkit export. Data backup is separate; see Backups and recovery.
• Migrating users from one instance to another. Toolkits travel; user accounts don’t (they’re scoped to the instance).
• Sharing a single playbook or goal with someone, without the surrounding toolkit. Today, you’d share by re-creating it in the recipient’s instance via conversation. A “share a single playbook” export is on the roadmap but not yet shipped.