Skip to main content
mobpack is the portable runtime artifact for mobs. You build it once, then deploy it with an objective, invoke a typed callable flow, or build a browser bundle.
A mobpack is not a VM, container, or complete host image. It carries a mob definition and the files of its mob directory. It does not carry the Meerkat binary, OS packages, or operator network policy. It should not carry provider credentials or secret environment values either, but nothing removes them: rkat mob pack archives every regular file under the mob directory; two files are meant to be left out (see What is packed).

What this guide is for

Use this guide when you want to:
  • package a mob into a portable artifact
  • sign and validate that artifact
  • invoke it consistently across CLI, service, and browser targets

What you get

  • Single-file artifact: .mobpack
  • Optional signing and trust verification
  • Deterministic inspect and validate boundaries
  • Closed capability and target-surface declarations
  • Typed, capability-gated deploy defaults
  • Optional adaptive FlowMaster policy and schema assets
  • Typed callable invocation (mob run) and browser bundle target (mob web build)

Directory to artifact

Expected source files:
  • manifest.toml
  • definition.json
  • optional skills/, hooks/, mcp/, config/defaults.toml
  • optional adaptive content under adaptive/ and schemas/
The runtime recognizes skills/, hooks/, mcp/, config/, adaptive/, and schemas/ as typed asset sections, plus the root manifest, definition, and signature records. Other safe files can be carried and are covered by the digest, but the runtime does not interpret them as assets. Paths are canonicalized and unsafe or duplicate entries fail closed. Required capability tokens and surface selectors use closed typed vocabularies, so an unknown token fails instead of silently downgrading execution.

What is packed

rkat mob pack archives every regular file under the mob directory, at any depth. It prints no warning and no list of them. Hidden files are included: an env file placed there (.env, .env.local) is in the pack with its contents, and so is the whole .git directory when the mob directory is a repository of its own. rkat’s own state directory is packed like any other. A command such as rkat run that is started inside the mob directory creates .rkat/ there when no directory above it has one; even a run that fails for a missing provider key creates it. It holds the stored conversations of those runs, the prompts included, and all of it goes into the pack. With a .rkat/ in a directory above, the state goes there and is not packed. rkat mob pack, rkat mob inspect and rkat mob validate do not create the directory. Two files are meant to be left out: the key this pack is signed with (--sign) and the file this run writes (-o). In 0.4.1 through 0.9.14 (confirmed by runs on 0.9.14; the earlier releases read from the source) each is left out only when its path, component by component, is the mob directory argument’s path followed by the file’s own (rkat mob pack mob -o mob/out.mobpack --sign mob/release.key --signer-id <id>, or . with ./out.mobpack and ./release.key). A single or doubled separator at the end of the directory argument, or a doubled one right after the directory in the file’s path, makes no difference; a doubled separator or a . further inside the file’s path does, and the key is packed. With any other components, the key is packed, and so is the output of an earlier pack at that path: rkat mob pack . -o out.mobpack --sign release.key --signer-id <id> inside the mob directory, ./mob with mob/release.key, an absolute directory with a relative path, a path through a symbolic link. A pack that holds its signing key gives the key to everyone who gets the pack. From 0.9.15 the two are left out however their paths are written. What is left out is the file that is this pack’s signing key and the file this run writes: by its resolved path, and on Linux and macOS also by file identity, so another name of the same file (a hard link, or another case on a file system that ignores case) is left out too. On Windows the comparison is by resolved path only (the key’s as resolved when the command opens it), so the key under any other name in the mob directory is packed there: a hard link, or the key file itself when it has another name while the command reads the directory. The identity comparison is tested through hard links; a file system that ignores case and the Windows comparison were read from the source, not run. From 0.9.15 a key or output path that cannot be resolved, for another reason than that the file does not exist, fails the command instead of being compared as written. From 0.9.15 the key file is opened once, before the mob directory is read: the file that is left out and the key the pack is signed with come from that one open, and a --sign path that names no file fails the command before the directory is read. In every release a copy of the key is another file and is packed, and so are a key file this pack is not signed with, a key file when the pack is not signed, and a pack written earlier under another name. A pack is a gzip-compressed tar archive: anyone who has the file can read every file in it. A web build copies the pack into its bundle as mobpack.bin, so everyone who can load the hosted page can download it. Before you share a pack or host a bundle:
  • Keep env files, keys and repository metadata out of the mob directory.
  • Keep the signing key and the pack output outside the mob directory, as the command under Signed packs and trust policy does.
  • Keep rkat’s state out of the mob directory: run rkat from another directory, or pass --state-root <directory outside the mob directory>. If the mob directory already holds a .rkat/ directory, move it out.
  • List what the pack holds: rkat mob inspect <pack> prints one line for each archived file: the word file, a tab, and the file’s path. It also reads the mobpack.bin of a built bundle. A path with .rkat/, .git/ or an env file such as .env in it, at the top of the pack or below a subdirectory, names a file that should not be there.
  • Move out everything that is not the manifest, the definition and the assets you meant to ship, then pack again.

Manifest contract

A minimal manifest names and versions the artifact. Optional sections declare capabilities, model aliases, profile assets, supported target surfaces, and adaptive metadata:
Known surface selectors are cli, rpc, rest, mcp, and web. Skill paths must be canonical paths under skills/. definition.json remains the one MobDefinition authority; the manifest describes packaging and deployment requirements around it.

Deploy defaults are an allow-list

config/defaults.toml is parsed into MobpackDeployPolicy, not merged into the host’s general Config. A pack may declare only:
  • top-level max_tokens for the per-turn output cap
  • [models] defaults for anthropic, openai, and gemini
  • [budget] values max_tokens, max_duration_secs, and max_tool_calls
  • [compaction] values auto_compact_threshold, recent_turn_budget, max_summary_tokens, and min_turns_between_compactions
For example:
Compaction knobs require session_compaction in [requires].capabilities and on the selected runtime. Unknown sections and fields fail closed. In particular, a pack cannot set realm bindings, self-hosted endpoints, provider tool keys, comms credentials, hooks, shell security, storage, retry, or general agent/tool configuration. Operator realm and environment layers remain authoritative; pack values are deployment defaults, not overrides of operator-owned truth. The definition also cannot smuggle realm references. Optional hook and MCP assets are declarations that still require compatible host capabilities and host-local resources. Keep secrets outside the archive: nothing removes them at pack time (see What is packed).

Signed packs and trust policy

Sign at pack time:
Signing embeds the public key but does not install the signer in the verifier’s trust configuration. Use permissive mode for this immediate local path, then switch to strict after installing the signer as trusted (see Trusting a signer):
Trust policy resolution:
  1. CLI --trust-policy
  2. RKAT_TRUST_POLICY
  3. config trust.policy
  4. default strict (fail closed; accepting unsigned or unknown-signer packs requires an explicit permissive opt-in)
Strict mode rejects:
  • unsigned packs
  • unknown signers
  • invalid signatures
  • signer key mismatches
Permissive mode accepts unsigned packs and valid signatures from unknown signers with warnings. It still rejects an invalid signature, digest mismatch, or signer-key mismatch. Permissive means relaxed signer enrollment, not skipped integrity.

Trusting a signer

A signing key is a file that holds 32 random bytes as 64 hexadecimal characters. Make one, for example, with:
Keep it outside the mob directory. A signed pack carries the signer id and the public key in its signature.toml:
A host trusts a signer once a trust store lists it. rkat reads two files, each optional: ~/.rkat/trusted-signers.toml for the user, and .rkat/trusted-signers.toml in the directory rkat is run from. A .rkat/ in a directory above is not read for this; to use a project’s file from elsewhere, pass --context-root <project directory>: that directory’s file is then read in place of the run directory’s. --user-config-root <directory> moves the user’s file to <directory>/.rkat/trusted-signers.toml. Each file lists signers by id, with the public_key value from signature.toml:
When both files list a signer, the entry in the directory’s file is used; if the two entries hold different keys, rkat prints a warning that it overrides the user’s entry. Check the result with rkat mob validate ./dist/release-triage.mobpack: under the default strict policy it refuses the pack as an unknown signer before the signer is listed, and prints valid with the pack’s digest after. Replacing a key. There is no revocation list. To replace a signer’s key, sign with the new key and replace the signer’s entry in every trust store that lists it. Until an entry is replaced, that host accepts packs signed with the old key and refuses packs signed with the new one. Once it is replaced, a pack signed with the old key is refused as a signer-key mismatch, under strict and under permissive. Replace the entry; do not only remove it: with the entry removed, a host that runs permissive accepts a pack signed with the old key again, as an unknown signer with a warning.

Run Modes

Deploy a pack with one objective and optional host-owned model or budget overrides:
Invoke a pack as a typed callable. When the pack includes schemas/main-input.json, parameters are validated against it before the flow starts. The resulting object is the flow’s params context, so step messages can read values such as {{ params.prompt }}. --prompt is sugar for --param prompt=<text>:
Pack runs use the realm’s durable mob and run stores. --detach requires a callable flow and returns its run id; inspect the persisted mob and run afterward:
--detach persists the run record but does not transfer execution custody to a daemon. The flow executes only while that CLI process lives. After the process exits, the next mob hydration converges any unfinished run to canceled with execution custody lost. Use a long-lived host process when the work itself must continue independently.
When the mob already exists in the realm, the target can be its mob id instead of a file path. That path invokes the installed definition and does not reload or re-verify a pack.

Adaptive mobpacks

An adaptive mobpack declares [adaptive] with a FlowMaster profile, objective class, SHA-256 policy digest, required schemas, and target surfaces. It also supplies:
  • adaptive/policies.toml
  • adaptive/flowmaster.prompt.md
  • schemas/registry.json and every registered required schema
rkat mob pack stamps the adaptive_flow requirement and generates the canonical adaptive/layer-decision.schema.json. Validation rejects a policy digest mismatch, incomplete policy with any zero limit, missing registered schema, or stale layer-decision schema. A runtime without adaptive_flow rejects the pack instead of running a non-adaptive fallback.

Browser target: mob web build

The browser runtime is the real meerkat agent stack compiled to wasm32 — same agent loop, same LLM providers (Anthropic, OpenAI, Gemini), and same streaming as CLI/RPC/REST. mob web build does not compile it; the command copies the required prebuilt runtime artifacts into the browser bundle. Prerequisites: the prebuilt meerkat-web-runtime artifacts — the wasm-bindgen glue (meerkat_web_runtime.js) and its paired meerkat_web_runtime_bg.wasm — produced by wasm-pack build meerkat-web-runtime --target web or an equivalent wasm-bindgen pipeline. The CLI fails closed without them and never emits a placeholder bundle. Pass either the generated output directory or the *_bg.wasm file (the sibling .js glue is copied alongside it):
Output is a static asset bundle. It still needs provider access through a user-supplied key or your authenticated proxy. Serve the directory (for example with python3 -m http.server --bind 127.0.0.1) and open index.html. The page is served on this machine only; to show it to others, host the bundle deliberately. The directory holds:
  • index.html - browser bootstrap page: trust-verifies the pack and initializes the WASM runtime, but does not create a mob or provide prompt/transcript UI
  • meerkat-bootstrap.js — reusable ES module exporting bootMobpack(opts); import it from your own app
  • meerkat_web_runtime.js — the wasm-bindgen glue
  • meerkat_web_runtime_bg.wasm — the compiled meerkat agent stack
  • mobpack.bin — the packed mob artifact (loaded via the runtime’s init_runtime)
  • manifest.web.toml — derived web manifest
mobpack.bin is the pack itself, unchanged: anyone who can load the page can download every file in it (see What is packed). The generated bootMobpack bakes in the trust policy this bundle was built with (--trust-policy); override it (and supply trusted_signers) for signed/strict production deployments.

How the WASM runtime works

The runtime uses tokio_with_wasm as a drop-in tokio replacement (backed by the JS event loop), reqwest with browser fetch for HTTP, and web-time for browser-safe timestamps. The #[async_trait(?Send)] pattern handles wasm32’s single-threaded model. For local development, the direct SDK bootstrap below explicitly opts into permissive trust:
A key written into the page’s code, as in that call, is sent to everyone who loads the page, and each of them can read it. Do that only on your own machine. For a page you serve to other people, either let each person enter a key of their own at run time, which stays in that person’s browser (every script running in the page can read it there), or give the runtime a dummy key and the base URL of your authenticated proxy, which adds the real key on the server; see Initialize runtime. For production, set mobpackTrust.policy to "strict" and supply mobpackTrust.trustedSigners, mapping each verified signer id to its Ed25519 public key as 64 hex characters. Verify that mapping through a trusted channel rather than trusting a key merely because it is embedded in the pack. Omitting mobpackTrust means strict verification with an empty signer store, so unsigned packs and packs from unenrolled signers fail closed. Native CLI --trust-policy flags and user/project trust stores are not imported by this direct SDK path; configure browser-local trust explicitly.

Browser capabilities and limitations

Available: agent loop (streaming, retries), all LLM providers, sessions, JSON schema validation, budget enforcement, events, skills, MCP config types, tool/compactor/memory traits. Not available (browser inherent): filesystem config loading, stdio MCP servers, shell tool, file-based persistence. Use programmatic config and in-memory storage instead. Not yet available (upstream blocker): MCP protocol client over HTTP — the rmcp crate depends on tokio/mio which don’t compile on wasm32. MCP config types and tool definitions work; actual connections to MCP servers are blocked pending rmcp wasm32 support.

Cool web patterns

Incident war room

Build ops-war-room.mobpack, publish web bundle behind internal auth, and let responders open a zero-install multi-agent workspace in-browser.

Embedded dashboard copilot

Bundle dashboard-copilot.mobpack and embed it in your observability or release dashboard to summarize anomalies and propose mitigation steps in context.

Example library

See runnable examples:
  • examples/028-mobpack-release-triage-sh for a signed release-triage mobpack that is packed, inspected, validated, and deployed end to end
  • examples/029-web-incident-war-room-sh for a browser-deployable SEV war room with source-controlled mobpack inputs and kickoff prompts
  • examples/030-web-dashboard-copilot-sh for an embeddable dashboard copilot that emits a web bundle plus sample host-integration assets

See also