Packages

Share a package with another person

Agent playbook — written for the agent connected to your account; you can read along

What's the difference between forking and sharing?

Fork copies a public package into the other person's account. They own that copy: they can edit, publish, schedule jobs, and keep their own storage. Use a fork when they should adapt the behavior or run it independently.

Share leaves the package in your account. After the guest accepts, they can read source and invoke it, but they cannot publish or write it. Storage stays yours. Use a share when you want one live package — a household tool, a private package that should not be public, or a source of truth that should stay in sync.

Both people need a paid plan to share. Forking a public listing does not.

Use this guide when one person should use another person's package without sharing a login. Sharing is behind the package-share-grants feature flag (off by default). Search packageShareInvite / packageShareAccept first; open capability detail for the exact call shape.

Package sharing is an invitation from a package owner to a guest. The guest keeps their own account. After they accept, they can import and invoke the shared package and read its source.

Sharing is not:

Giving someone your password or MCP token
A community fork (the guest does not get their own copy of the source repo; prefer a fork when they should own a copy)
A platform scope grant (package_scope_grants). Those are admin-minted, platform-account only, and grant full authoring under a platform scope. Person accounts never own that table.

Invite, accept, use, leave

Owner invites by username or email (packageShareInvite). The invite email links to @{owner}/{packageName} with an Accept banner. Email invites bind to an existing account only when that mailbox is verified; otherwise the row stays pending until the guest verifies.
Guest must accept (packageShareAccept). Nothing attaches silently.
Invite-before-signup: a pending invite is held. The email explains Kody, what is shared, and that the guest creates an account, pays, then accepts.
Guest uses the shared package from their own packages or execute.
Owner revokes (packageShareRevoke) or guest leaves (packageShareLeave). New invokes fail immediately. An in-flight Worker isolate may finish.

Both owner and guest must be on a paid plan to invite, accept, and use.

Pin and follow

At accept, the guest chooses a trust level. The Accept UI defaults to pin.

pin — accept the current published commit only. If the owner publishes ahead, use and import fail closed with a link to /@{owner}/{packageName}/approve-changes. That page shows the accepted → current published source diff. Approve updates the snapshot only for the commit that was reviewed; a later owner publish requires a fresh review. Approve and follow switches trust to follow.
follow — accept the current published commit and auto-accept later owner publishes.

accepted_published_commit and trust_level live on the grant. This pin is grant-level publish trust, not a user-facing import specifier pin (0001).

What a guest can and cannot do

The v1 role is use: read_source + invoke. Future collaborate / write roles can add more permissions without changing the grant table.

Guests can:

Read package source (safety review for human and agent)
Invoke and import the shared package
Create their own packages that depend on the granted package
Use package-scoped secrets through the package

Guests cannot:

Publish or write the shared package
See raw secret values (hard invariant)
Create jobs, apps, webhooks, or subscriptions on the shared package
Watch the owner's transcripts or runs

Shared state is the owner's packageStorage. The owner pays that storage even when a guest writes it. The guest pays executes and jobs on their packages. The owner pays owner-created jobs and apps on the shared package.

Runtime isolation

When shared package code runs for a guest, it does not receive the guest's other user secrets, integrations, or packages by default. It gets package-scoped powers (owner stamp, mounts, owner storage) plus explicit inputs. Guest wrapper modules still run as the guest. Imported shared modules stay stamped as the shared package.

MCP playbook

Invite by scoped name:

{
	"name": "@alice/household-notes",
	"username": "jesse"
}

Accept with the safer default (pin if trust_level is omitted):

{
	"name": "@alice/household-notes",
	"trust_level": "pin"
}

List what you shared and what is shared with you:

{ "scope": "outbound" }

{ "scope": "inbound" }

Approve a pin-ahead publish, optionally switching to follow:

{
	"grant_id": "…",
	"switch_to_follow": false
}

Use packageShareInspect for one grant, packageShareRevoke as the owner, and packageShareLeave as the guest. Prefer scoped package name over leftover kody_id in examples.