Lease Sharing

A lease is normally exclusive: the client that acquires it is the sole owner and no one else can reach the leased exporter. Lease sharing lets the owner grant additional clients read/observe/connect access to the same lease while keeping ownership — useful for pairing on a debugging session, letting a teammate watch a serial console, or handing a CI-held lease to a human for inspection.

This guide covers distributed mode; sharing is coordinated by the controller and therefore does not apply to local mode or direct-mode connections.

Owners vs. shared clients

Sharing splits capabilities into two roles:

Capability	Owner	Shared client
Connect / dial the exporter (jmp shell, driver calls)	✅	✅
Observe serial consoles	✅	✅
List/inspect the lease (jmp get leases)	✅	✅
Add or remove shared clients	✅	❌
Change duration / times	✅	❌
Transfer the lease to another client	✅	❌
Release or delete the lease	✅	❌

In short, shared clients get access but not control: everything that mutates the lease (sharing, timing, transfer, release, delete) is restricted to the owner. A shared client that attempts one of these receives a PermissionDenied error.

Sharing at creation time

Share a lease with one or more clients as you create it using --share (a comma-separated list of client names):

$ jmp create lease -l board=rpi4 --duration 2h --share client-alice,client-bob

Managing sharing on an existing lease

Use the jmp share command group to change sharing after the lease exists. All three subcommands take the lease ID as the first argument.

$ jmp share add my-lease client-alice client-bob
$ jmp share remove my-lease client-alice
$ jmp share list my-lease

jmp share list distinguishes the owner’s intent from what the controller actually granted:

$ jmp share list my-lease
Lease my-lease shared with:
  client-bob
  client-alice  (not active: denied by policy or client not found)

A name shows as not active when it is in the owner’s requested share set but was filtered out — either because no client with that name exists, or because an exporter access policy does not allow that client to reach this exporter. See Access policies below.

Working with a lease shared with you

A shared client does not create a lease — the owner already did. To find leases shared with you, list across all clients with -A/--all-clients:

$ jmp get leases -A

Leases you can reach but do not own are annotated with shared by <owner> so you can tell them apart from your own.

To open a shell against a lease shared with you, pass its ID with --lease:

$ jmp shell --lease my-lease

If you hold exactly one accessible lease, jmp shell selects it automatically; --lease is required to disambiguate when you can reach more than one.

Access policies and effective sharing

Sharing is always subject to the exporter’s access policies. Adding a client to a lease expresses intent; the controller then evaluates the policies and computes the effective share set — the clients that are actually granted access. A client the owner shared with but that the policy denies (or a name that matches no client) is silently excluded from the effective set and never gains access.

This is why jmp share list reports two states: the requested list and whether each entry is currently active.

Revoking access

jmp share remove (and policy changes that newly deny a client) provide a soft guarantee, not an instantaneous kill:

• The controller immediately stops granting the removed client new connections.

• A shared client’s live jmp shell session polls its own access and exits on its own within a short interval (currently 15 seconds), so there is a bounded window during which an already-open session can still be used.

• Removal does not forcibly tear down a router stream the exporter has already established.

If you need to cut off everyone immediately — including the owner and all shared clients — end the lease itself:

$ jmp delete lease my-lease

Serial consoles for shared sessions

Serial consoles are a common reason to share a lease: one person drives the console while others watch. The pyserial driver supports a read-only observe mode and an exclusive write token so multiple shared clients can attach to the same console safely. See the “Serial console sharing and observe mode” section of the pyserial driver reference for j serial console --observe, release-console, and console-status.