Sharing an App

An App is the saved, re-runnable unit of work in the agentic runtime — see Apps. Sharing one means writing it to a single file and handing that file over: attach it to an email, drop it in a shared folder, commit it to a repository.

The file is called a bundle, and it ends in .kxapp.

Two things are worth knowing before you send one.

A bundle carries no authority. No secret, no password, no API key, and no permission travels inside it. When someone imports your App, it runs under their account with their permissions — never yours.

A bundle is not signed. There is nothing in the file that proves who made it. Read what is inside before you run it.

Why the plain envelope is not enough

An App stores its text — prompts, rules, context, skill instructions — by reference. The saved App holds a pointer to each piece of content, not the content itself. That is efficient locally, and useless on someone else's machine, where those pointers resolve to nothing.

kx app export apps/local/echo-demo --output echo.app.json

That writes the envelope: the App's structure, by reference. It round-trips on your own machine. It is not self-contained.

A bundle fixes that. It is a kortecx.appbundle/v1 archive: the App's envelope plus every blob of content it points at, packed into one file.

Export an App

kx app list

kx app export apps/local/echo-demo --bundle echo.kxapp

import kortecx as kx

a = (
    kx.app("echo-demo")
    .blueprint(kx.flow().agent("Echo the user's input."))
    .rule("no-pii", body="Never reveal personal data.")
)
a.export("echo.kxapp", bundle=True, client=kx.default_client())

import { app, flow } from "@kortecx/sdk";

await app("echo-demo")
  .blueprint(flow().agent("Echo the user's input."))
  .rule("no-pii", { body: "Never reveal personal data." })
  .export("echo.kxapp", { bundle: true });

kx app export apps/local/analyst --bundle analyst.kxapp --with-data

What travels, and what does not

kx connections add --provider gmail

missing integration: KX_GMAIL_CREDENTIAL (register it with `kx connections add`)

Travels in the bundle:

• the App's structure — its blueprint, steering settings, and budgets
• the text it carries: prompts, rules, memory artifacts, skill instructions
• context blobs it references
• dataset payloads, but only with --with-data

Never travels:

• secrets, API keys, tokens, passwords — any credential value
• registered connections (only the credential name the App asks for)
• your grants, permissions, or policy
• run history, results, and cost records — the format has no field for any of them
• any file on your host filesystem

Import a bundle

Importing reconciles the file under your own account.

kx app import echo.kxapp

Proceed with import? [y/N]

kx app import echo.kxapp --yes

kx app manifest apps/local/echo-demo

An import will not quietly overwrite an App you already have at the same handle. It stops and tells you; --force overwrites deliberately.

The checks an import runs

• Schema. A bundle tagged with a version this build does not understand is rejected outright.
• Shape. Every digest and content reference must be 64 characters of lowercase hex; every blob must be valid base64.
• Digest match. The importer re-derives the App's digest from the envelope and compares it to the one the bundle declares. A mismatch means the file was corrupted or altered, and the import stops.
• Size ceilings. At most 4096 blobs, and at most 512 MiB of content across the whole bundle, checked before a single byte is uploaded. Separately, the server caps any individual blob — 32 MiB by default.
• Content integrity. Each blob is uploaded and the server re-derives its address from the bytes themselves. If the address it computes differs from the one the bundle claimed, the import stops. Blobs you already hold are recognised and not stored twice.
• Envelope validation. The server re-validates the envelope on save, exactly as it would for an App you authored yourself.

Importing can never widen what you are allowed to do

This is the guarantee worth stating on its own.

An App carries a request for capability — the tools it wants, the connections it wants, the model it wants. The runtime grants only the overlap between that request and what you are already permitted to do. A request is never authority.

So an imported App:

• runs under your account and your permissions
• resolves every tool grant against your policy, at run time, server-side
• resolves each connection against your registered credentials, by name
• fails closed if it names a model this instance does not serve, rather than quietly running on a different one

Nothing in the file can change any of that. There is no field for a permission, no field for a grant, no field for a secret. Sharing an App is sharing a plan, never a key.

Clone an App locally

To make a copy of one of your own Apps under a new name — a safe place to experiment, or a starting point for a variant — clone it. Nothing is exported and nothing transfers, because the content is already on the machine:

kx app clone apps/local/echo-demo my-copy

That writes a new App at apps/local/my-copy, records the original's digest as its lineage, and leaves the original untouched. If an App already exists at the new name, the clone stops and asks you to pick another.

The console calls this Duplicate, in each App's overflow menu.

The file itself

A .kxapp is plain text — canonical JSON with sorted keys, and blob bodies base64-encoded. You can open it in an editor and read it.

Because the format is canonical, the same App exported from the CLI, from Python, or from TypeScript produces byte-identical files. That is pinned by a shared golden corpus the three implementations are tested against, so the surfaces cannot drift apart.

The top-level fields:

An App with no carried content and no lineage omits blobs and source_digest entirely.

Next