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
inspectandvalidateboundaries - 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
manifest.tomldefinition.json- optional
skills/,hooks/,mcp/,config/defaults.toml - optional adaptive content under
adaptive/andschemas/
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
rkatfrom 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 wordfile, a tab, and the file’s path. It also reads themobpack.binof a built bundle. A path with.rkat/,.git/or an env file such as.envin 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: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_tokensfor the per-turn output cap [models]defaults foranthropic,openai, andgemini[budget]valuesmax_tokens,max_duration_secs, andmax_tool_calls[compaction]valuesauto_compact_threshold,recent_turn_budget,max_summary_tokens, andmin_turns_between_compactions
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:- CLI
--trust-policy RKAT_TRUST_POLICY- config
trust.policy - default
strict(fail closed; accepting unsigned or unknown-signer packs requires an explicitpermissiveopt-in)
- unsigned packs
- unknown signers
- invalid signatures
- signer key mismatches
Trusting a signer
A signing key is a file that holds 32 random bytes as 64 hexadecimal characters. Make one, for example, with:signature.toml:
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:
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: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>:
--detach requires a
callable flow and returns its run id; inspect the persisted mob and run
afterward:
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.tomladaptive/flowmaster.prompt.mdschemas/registry.jsonand 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):
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 UImeerkat-bootstrap.js— reusable ES module exportingbootMobpack(opts); import it from your own appmeerkat_web_runtime.js— the wasm-bindgen gluemeerkat_web_runtime_bg.wasm— the compiled meerkat agent stackmobpack.bin— the packed mob artifact (loaded via the runtime’sinit_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 usestokio_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:
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 — thermcp 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
Buildops-war-room.mobpack, publish web bundle behind internal auth, and let responders open a zero-install multi-agent workspace in-browser.
Embedded dashboard copilot
Bundledashboard-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-shfor a signed release-triage mobpack that is packed, inspected, validated, and deployed end to endexamples/029-web-incident-war-room-shfor a browser-deployable SEV war room with source-controlled mobpack inputs and kickoff promptsexamples/030-web-dashboard-copilot-shfor an embeddable dashboard copilot that emits a web bundle plus sample host-integration assets
