# CLI, installation and MCP configuration Source: [src/dmsg_cli/README.md](https://github.com/ldclabs/ic-panda/blob/main/src/dmsg_cli/README.md). This is a public-source snapshot; review dates and deployment limits below still apply. --- # dmsg The dMsg command line client. `dmsg daemon` runs the daemon, the only process that holds keys and state; every other command asks it over loopback. The cryptography, storage and protocol logic live in [`dmsg_client`](https://github.com/ldclabs/ic-panda/blob/main/src/dmsg_client/README.md). ## Home `dmsg logout` signs out of the selected account and removes its saved login and fast-unlock key. Its encrypted workspace and other accounts stay on this device. The next browser login opens the same workspace with fresh delegation targets. The desktop exposes this action in the account menu as **Log out**. `--home `, else `$DMSG_HOME`, else `~/.dmsg`: | Path | Content | | --- | --- | | `config.toml` | Deployment parameters and policies; the only place to change them. Without it the production deployment built into the binary applies ([`production.toml`](https://github.com/ldclabs/ic-panda/blob/main/src/dmsg_client/production.toml)) | | `preferences.json` | The desktop's file settings: `files_mount` (allowed after a system dialog, beside `config.toml`'s) and `files_trash_days` (instead of `config.toml`'s). Only the desktop's main process writes it; the daemon reads it at start and on `files/preferences_reload`, never from a request's values | | `owner.token` | Owner credential with `secure_storage = "file"`, readable only by its owner | | `daemon.json` | Port, process and instance ID of the running daemon | | `dmsg-daemon.lock` | Held by the running daemon: one daemon per home | | `logs/dmsg-YYYY-MM-DD.log` | The daemon's run log, one file per UTC day, kept 30 days (`dmsg logs`) | | `logs/stderr.log` | The stderr of a daemon started by `dmsg start` (rewritten each time) or at login: what fails before the run log opens | | `/accounts//workspace.sqlite` | An account's workspace on this device: its own device keys, encrypted versions and chunks, sealed records, sync and backup jobs | | `/accounts//agents.sqlite` | Agent Protocols connector state of the account's hosted Agent IDs; no private key (see [`dmsg_agent`](https://dmsg.net/_/docs/agents.md)) | | `/accounts//blobs//` | The file library's ciphertext chunks, one file per chunk named by its SHA-256; `blobs/tmp/` holds chunks being written | | `/accounts//open//` | Plaintext copies of library files opened for another program (`dmsg files open`), owner-only and kept out of Time Machine, removed after 30 minutes, on lock and on exit | | `/accounts//mount/` | A file arriving over the mounted disk, owner-only and kept out of Time Machine, until it is imported; removed on lock | | `/logins//` | The workspace of a login without an account; it becomes `accounts//` once the login has one | | `/current` | The account selected last, which a restart and fast unlock use | A home without `config.toml` uses [`production.toml`](https://github.com/ldclabs/ic-panda/blob/main/src/dmsg_client/production.toml), compiled into the binary: the production relay, IC host, name registry and Agent Protocols hosts, so the desktop app and a fresh install work without setup. A `config.toml` replaces it whole (nothing is merged), and `dmsg validate-config` and `dmsg doctor` say which one applies. A release's built-in settings change with the release; a `config.toml` stays as written. ```toml environment = "local" # local, staging or production ic_host = "http://127.0.0.1:4943" relay = "http://127.0.0.1:8787" # dmsg-cloud relay: device API and Agent Delegation handle = "" user_homes = [""] # optional pins; the registry is the authority root_key = "" # local only login_url = "http://localhost:3002/_/login" # local only; default https://dmsg.net/_/login idle_lock_minutes = 15 # 1 to 1440 background_online = false # keep the device key while locked sync_interval_minutes = 0 # scheduled sync; 0 is off files_max_bytes = 4294967296 # largest file the file library takes (default 4 GiB) files_trash_days = 30 # days a trashed library file is kept, 1 to 365 files_mount = false # allow mounting the library as a disk (loopback WebDAV); preferences.json may too secure_storage = "system" # "system" (default on macOS and Windows) or "file" connect_url = "http://localhost:5174" # local only; default https://connect.dmsg.net agent_hosts = [ # Agent Protocols hosts the hosted agents may sign for { host = "https://api.al.ink", label = "alink" }, { host = "https://agents.example", profile_service = "https://profiles.example" }, { host = "https://mail.example", label = "mail" }, # an Agent Mail relay { host = "https://knowledge.example", label = "knowledge" }, # an Agent Knowledge service ] agent_blocked_senders = ["did:agent:…"] # mail from these is deleted unopened agent_ca = "/path/to/ca.pem" # local only: replaces the system roots for agent_hosts [legacy] # the old service's freeze the deployment reviewed channels = [""] identity = "" buckets = [""] cutover = "<32-byte hex cutover ID>" [wallet] # team wallets; production names the hub hub = "" bitcoin_api = "https://mempool.space/api" # an Esplora API solana_rpc = "https://api.mainnet-beta.solana.com" evm_rpc = { "1" = "https://ethereum-rpc.publicnode.com", "8453" = "https://mainnet.base.org" } ``` Outside `local`, every URL must be HTTPS and `root_key`/`login_url`/`connect_url`/`agent_ca` are refused. The relay is also the Agent Delegation service of the account's principal. `[legacy]` is needed only for frozen comparisons and shared channel inheritance; frozen evidence of any other canister or cutover is refused. The built-in settings name the three frozen channel canisters, the name identity and the cutover sealed by SNS proposals 553–558. They list no OSS bucket: the old buckets cannot freeze folders yet, so a frozen comparison of a channel with attachments stays incomplete. `agent_hosts` is the only source of the host allowlist: no command, method or tool changes it, and a host must be an origin (loopback HTTP only in `local`). Mail relays and Knowledge services are hosts like any other, and HTTPS only: an agent fetches cards, delivers letters and submits or reads Knowledge only at them. An entry names an origin the agents may sign for, not what it serves: each tool reads its protocol's discovery document at the origin it is given (`/.well-known/agent-mail`, `agent-knowledge`, `agent-discourse`, `agent-delegation`, `agent-profile`) and fails where the origin serves none. The relay is one of them: it is the account principal's Agent Delegation and Agent Profile service. What each agent may do at which of the hosts, such as reading Agent Discourse everywhere without speaking, is the owner's grant (`grants add` below). `agent_blocked_senders` is likewise the only source of the mail sender policy. The connectors' requests follow no redirect. The daemon makes the home its owner's only (mode 700) when it starts: the workspaces' metadata and the hosted agents' room records and letters are not encrypted. `secure_storage = "system"` keeps the owner credential and the fast-unlock key in the system credential store (Keychain, Credential Manager, Secret Service) under the service `dmsg`. `"file"`, the default elsewhere, keeps the owner credential in `owner.token`; fast unlock is then unavailable. Fast unlock turns on with every login unlock unless `fast-unlock disable` turned it off, and lasts thirty days after the last login unlock, as long as the login (`dmsg login` asks Internet Identity for thirty days). On macOS the Secure Enclave keeps its key (`src/enclave.rs`, CryptoKit through `swift/Enclave.swift`, which `build.rs` compiles; building on macOS needs the Xcode Swift toolchain): each fast unlock asks for Touch ID, or the login password without it, and gives up after a minute unanswered; the login is kept sealed under the local data key and comes back with it. Elsewhere the key sits in the credential store, nothing asks for the person and no login is kept. Team-wallet cosigner keys use the Secure Enclave the same way. With system credentials and supported hardware, the first login after registration, pairing, recovery or an upgrade binds the workspace by default. The system asks once to verify the hardware factor; cancellation or failure leaves content locked. The existing login query supplies the secret, with no added update or everyday vetKD call. Old unbound fast unlock first requires login. An explicit `device-bound disable` is remembered across later logins; enabling it again clears that preference. Systems without hardware or using file credentials keep their existing compatibility path. `device-bound enable [--biometry-only]` binds the workspace to this Mac: another Secure Enclave key, in a credential-store entry of its own, joins every unlock, the login's included, and alone opens fast unlock. Touch ID is asked once to check the key. It reports what stays outside it (the device key kept with background online, resident Agent IDs); copies of the workspace made before keep opening with a login. Signing out, turning fast unlock off and a failing key keep its entry; `device-bound disable` or a reset removes it. `--biometry-only` takes only the fingerprints enrolled now: after they change the key reports itself lost, while a missing Touch ID keyboard is only unavailable. Approval keys are Secure Enclave keys the account registers per device (`device key register|request|approve|retire`); `account hardware on|off [--payment] [--attestation]` requires their signature for account, device and Agent principal changes, and optionally payments and formal attestations. On a device with a registered key, a high-risk or protected approval asks Touch ID through the key, once, and the key signs the approval; a required approval on a device without one fails with `APPROVAL_KEY_REQUIRED`. With keys required, a device without a working key runs `device key request`, which asks Touch ID there and prints a request, and an administrator device with a key runs `device key approve`. Every workspace also has a hardware anchor: a Secure Enclave key that never asks and works once the Mac has been unlocked after it started. The daemon signs with it when it starts and whenever it selects a workspace. A workspace copied to another Mac, by Migration Assistant or a restored backup, cannot sign there and is moved (`state: "moved"`): it never unlocks and receives no notifications with the old device's identity, and nothing in it is erased. `device/moved_set_aside` moves it whole to `moved/-/` and starts a new device of the account, which then pairs or recovers; `device/moved_list` lists the copies and `device/moved_discard {id}` deletes one. A workspace that already held Secure Enclave keys when its anchor was made counts as moved when the first of them fails on this Mac; the first that opens settles it. Older Macs without Secure Enclave use a device-bound digest of IOPlatformUUID to detect ordinary system copies; this is weaker than an enclave anchor. Resident Agent credentials and notification receivers stay inactive while hardware is foreign or still unverified. Existing approval and cosigner keys also participate in late-anchor checks; keys created afterwards do not. While the old device is still active, the new device can take over from a copy without the old Mac (`dmsg device moved`). After `login`, `approve-successor ` asks to succeed the copy's device and makes a high-risk approval request on this Mac; approving it enrolls the new device, signed as the copy's device, and rotates the content root to it, and `unlock` binds it. The copy's device must be an administrator, and the account must not require approval keys for device control. `import --succession ` then brings in the copy's file library, only adding, and settles the succession's content step; the other steps run as in any succession, and the copy no longer opens once the old device is revoked. A wallet the copy's device created still binds it without a device ID: where no other device is bound to it, `run revoke` first asks to take over that wallet's bindings; otherwise take them over with `wallet join --exclusive`, which removes this account's other bindings, before revoking. A copy whose device bound its workspace to its hardware does not open here (`FORBIDDEN`). The import source is opened read-only. The permitted local succession keeps its mutable journals in `moved-operations//`, separately from that source; discarding the copy also removes those journals. The hardware creation tests run without a prompt: `cargo test --locked -p dmsg_cli --bin dmsg enclave::tests::creates_keys_without_asking -- --exact --nocapture` and `enclave::tests::anchors_sign_without_asking` the same way. Run it in an active macOS login session with the device unlocked. Hardware and biometric capability checks do not guarantee that the security service will permit key creation at that instant. A native failure now keeps its negative `OSStatus` in the error; for example, Apple's [`errSecInteractionNotAllowed`](https://developer.apple.com/documentation/security/errsecinteractionnotallowed) is `-25308`. Inspect the matching test process's CryptoTokenKit logs for the underlying rejection. A system refusal must not remove `.userPresence`, change the key's `WhenUnlockedThisDeviceOnly` protection, or fall back to a software key. ## Install, start and update ```sh dmsg start # the daemon in the background, unless one runs dmsg stop # after the running operation; returns once it exited dmsg restart [--interrupt] [--wait 60] dmsg install [--dir D] # this binary to the shared location dmsg update [--check] [--force] [--interrupt] [--wait 60] dmsg autostart install | uninstall | status dmsg validate-config dmsg doctor # checks; exits 1 when one fails dmsg logs [-n 100] # the newest lines of the run log ``` [`scripts/dmsg/install.sh`](https://github.com/ldclabs/ic-panda/blob/main/scripts/dmsg/install.sh) (macOS Apple Silicon, Linux) and [`install.ps1`](https://github.com/ldclabs/ic-panda/blob/main/scripts/dmsg/install.ps1) (Windows x64) download the latest release, check its SHA-256 and run `dmsg install`; `--uninstall`/`-Uninstall` stops the daemon and removes the login registration and the binary, never the home. Homebrew installs `ldclabs/tap/dmsg`. - **One binary.** `dmsg install` puts the running binary at the shared location (`DMSG_INSTALL_DIR`, else `~/.local/bin`, or `%LOCALAPPDATA%\dMsg\bin` on Windows, outside the desktop app's install directory) unless the one there is the same release or newer, or Homebrew's (left to `brew upgrade dmsg`). When this binary is signed by a Developer ID team (macOS), an installed one stays only if it verifies and is signed by the same team, checked before anything runs it: a shared one that fails is replaced, and a Homebrew one that fails gives way to the shared location. The desktop app runs its bundled copy only this way and then runs the installed one, so the CLI, agents and the app share one daemon. `--json` reports `{action, path, version, on_path}` with `action` one of `installed`, `upgraded`, `replaced`, `current`, `kept_newer`, `homebrew`. - **Releases.** dMsg client releases are tagged `dmsg-v` and are the repository's latest release (canister releases are not). `dmsg update --check --json` reports `{current, latest, available, homebrew}`. `dmsg update` downloads this platform's binary (`dmsg-macos-arm64`, `dmsg-linux-x86_64`, `dmsg-linux-arm64`, `dmsg-windows-x64.exe`), checks it against the release's `.sha256` and, when this binary is signed by a Developer ID team, that the new one verifies and is signed by the same team; then it replaces this binary through a staged file. `DMSG_RELEASE_URL` replaces `https://github.com/ldclabs/ic-panda/releases` (tests, mirrors). - **Stopping for an update** (plan DT10). `restart` and `update` stop a running daemon with `daemon/stop {if_idle: true}`: the daemon refuses new requests and background passes, waits for the running operation and stops only if no approved request, account update or root rotation is left unsettled; otherwise it keeps running and answers what is in flight. The command asks again every two seconds for `--wait` seconds and then fails with `BUSY`, replacing nothing. Locked, unsettled work cannot reconcile, so unlock first, or use `--interrupt`: the work is journaled and resumes after the restart. An update starts the new daemon and checks the version it reports; the new daemon is locked. Requests waiting for a person and unsynced versions are kept either way. `dmsg start`, which the desktop app runs on every connection, also restarts a running daemon older than its binary, such as one left running while the app upgraded the installed binary: it asks once and, when work is in flight, leaves that daemon running. - **Diagnostics** (plan §13). `dmsg doctor` checks, without changing anything: `config.toml`; the home's permissions (and `owner.token`'s with `secure_storage = "file"`); the owner credential in its store; the daemon (running, and the same version as this binary); the relay's `/ready` and its environment; this clock against the `time` `/ready` reports (over 5 seconds is a warning, over 30 a failure: signed requests carry 45-second deadlines); the registry's user homes and the configured pins; the hint channel. `--json` prints `{ok, checks: [{name, status, detail}]}` with `status` `ok`, `warn` or `fail`. The run log has one line per call (method, the tool an agent ran, owner or agent, outcome code, milliseconds; steady polls only when they fail) and one per change of a background task's outcome (sync, flush, web requests, MCP Events, hint channel), so a task failing every round while offline logs its unchanged outcome once. Separate `failure` lines record the originating subsystem, allowlisted cause and HTTP status when available: timeout, DNS/TLS/connect/closed connection, response decoding, IC rejection/certificate, or storage permission/full/busy/corruption errors. These are emitted before a lost mutation reply becomes `EXECUTION_UNKNOWN`; that code still requires reconciliation, never blind resubmission. `sync/pass` adds the failed sync stage. For example: `failure source=relay reason=http http_status=503` followed by `sync/pass stage=export_page ms=8037 outcome=UNAVAILABLE source=relay reason=unavailable`. Lines hold fixed names, codes and numbers only: never parameters, content, account/device IDs, URLs (including signed URLs), headers, paths, tokens, raw server messages or panic payloads. Unknown tools are omitted; unknown methods use `unknown`. Library diagnostics pass a second strict allowlist at the file writer; other library targets and `RUST_LOG` verbosity are ignored. Panic records contain only a source filename and line. On Unix the log directory is owner-only and newly created log files use mode 0600. - **At login.** `dmsg autostart install` registers this binary with this home: a LaunchAgent `net.dmsg.daemon` on macOS, a systemd user unit `dmsg.service` (XDG autostart without a user systemd) on Linux, the user's `Run` value `dMsg` running `dmsg start` on Windows. It takes effect at the next login; `uninstall` leaves a running daemon alone. ## Commands ```sh dmsg daemon [--port N] # foreground; port 0 (default) picks a free one dmsg status [--json] dmsg login [--origin dmsg.net|panda.fans] [--no-browser] [--bind] dmsg unlock [--fast] [--account ] | lock | stop dmsg accounts | switch dmsg fast-unlock enable | disable dmsg device-bound enable [--biometry-only] | disable dmsg account create | show | security dmsg account bind-request | bind-approve --principal

| bind-accept dmsg account unbind | policy [--freeze|--unfreeze] [--daily N] [--purposes a,b] | recovery-delay dmsg account recovery on [--days N] | off dmsg account hardware on [--payment] [--attestation] | off dmsg recovery status | request | complete | dispute dmsg legacy delete-channel dmsg channel delete-legacy-draft dmsg legacy pair [--origin https://dmsg.net|https://panda.fans] | pairs | cancel dmsg legacy import --nonce N --fingerprint F --principal P | list | report [--offset N] [--limit N] dmsg legacy file | frozen dmsg device list | pair-request [--member] | approve --device dmsg device key status | register [--biometry-only] | request [--biometry-only] | approve --device | retire [--device ] dmsg device succession request | review | approve --device | list | status dmsg device succession run | skip content|native_addresses [--keep a,b] | cancel dmsg device transfer receive [--session S] [--succession ID] [--wait] | status | cancel dmsg device transfer send [--to ] [--address host:port] [--succession ID] [--approval ID] [--wait] dmsg device moved list | set-aside | import [--succession ID] | approve-successor | discard dmsg vault add --title T [--type login|api|key|ssh|wallet|card|identity|server|database|license|note] [--generate] [--notes N] [--username U] [--url L] [--tag T]... [--field [TYPE:]LABEL=VALUE]... [--otp URI] [--secret-stdin] dmsg vault edit [--title T] [--notes N] [--username U] [--url L] [--tag T]... [--clear-tags] [--favorite|--no-favorite] [--field [TYPE:]LABEL=VALUE]... [--rm-field ID|LABEL]... [--otp URI] [--secret-stdin] dmsg vault rm ... | restore | duplicate [--title T] | list [--trash] | search dmsg vault show [--reveal] [--revision R] | history | revert | otp [--field F] dmsg vault conflicts | resolve [--keep-current] | import [--yes [--all]] | health dmsg files ls [folder] [--trash] | tree | show | search dmsg files add ... [--to ] [--keep-both] | mkdir | mv ... | rename dmsg files tag +t|-t... | note [text] | star [--off] dmsg files get [--version V] -o | open [--version V] | opened [--cleanup [nonce]] [--save] dmsg files verify | verify --all | versions | version-use | version-rm dmsg files rm ... | restore ... | purge [...] | usage | local-only dmsg files share [--version V] [text] | save [--to ] dmsg files backup ... [--all-versions] | backup-status | backup-cancel dmsg files cloud ls [--refresh] | refresh | get [--to ] | rm ... | verify | usage dmsg files evict [--version V] dmsg files link [--version V] [--days 7] [--max-downloads N] [--password] | links [--refresh] | link-revoke dmsg files mount [--status] | unmount dmsg sync | sync status dmsg profile show | publish | retry | resolve dmsg profile avatar dmsg reset --yes dmsg approvals list [--all] | show | approve | reject | cancel | quote dmsg approvals check-file | reconcile dmsg attest text | digest (--file F | --sha256 H) | file --text T | action dmsg attest history | usage | readiness | export -o | verify [--file F] dmsg device capabilities --set a,b,c | formal-approve on|off | revoke dmsg connect browsers add [--copy-link] | list | revoke dmsg connect requests | sync dmsg channel list | show | create [--type direct|collaboration|distribution] dmsg channel invite [--role member|publisher] | accept dmsg channel members | role | remove | leave | archive dmsg channel rotate | rekey | reactivate | history dmsg channel send [text] [--file ] [--message-id M] | read [--after N] [--backfill] dmsg channel download --out | pending [--key K] dmsg channel outbox [--discard M] | search | receipts | uninvite dmsg channel settings [--name N] [--mute true|false] [--hide true|false] dmsg channel transfer|sponsor propose | accept | commit dmsg channel sponsor cancel dmsg inbox policy | configure closed|contacts|free|paid [--price P] [--payee P] [--allow A]... dmsg inbox send [--pay] [--invitation I] [--order O] | pay dmsg inbox order | outgoing | escrow | refund dmsg inbox list | mark [--archive] dmsg payment transfers | revise dmsg payer use [pem] | balance dmsg wallet list | show | principal | quote | create --name N [--member id:role[:label]]... | refund dmsg wallet join [--replaces ... | --exclusive] | unbind ... | bindings dmsg wallet proposals | proposal | send --from A --asset X --to T --amount N --max-fee F dmsg wallet propose | member-agents [--agent did:agent:…]... | approve|reject|veto|cancel | freeze dmsg wallet execute|broadcast|settle|reconcile | report broadcast|settled|failed dmsg wallet balances|audit|refuel | cosigners | cosigner-new

`, and the new login then `account bind-accept ` within ten minutes. `account unbind`, `account policy` (freeze formal signatures, executions a day, allowed purposes), `account recovery-delay` and `account recovery on|off` are approvals too. Recovery, when every device is lost and on-chain recovery was enabled beforehand: a new device logged in with a bound login runs `recovery request`; any device of the account sees it in `account security` and can `recovery dispute` it during the delay (one to seven days, three by default). After the delay, `recovery complete` takes the account over, derives the committed root's key once, opens it and rotates to a root only this device holds; run again, it resumes. The daemon watches the selected account's certified public recovery digest, including while locked with background online disabled. Ordinary security reads update this observation; an independent loop checks for changes every 10 seconds and fetches security about once a minute when needed. `dmsg status` warns about a pending recovery and points to `dmsg recovery dispute`; `--json` includes `recovery` (`account`, `pending`, `digest`, `observed_at_ms`, `stale`). Null means not yet checked; after two minutes without a fresh observation the state is stale, and an existing warning remains. The observation survives daemon restarts. When the request changes, the daemon expires the account security display snapshot, then `recovery/changed` wakes the shared notification policy. Incident identity and phase coverage persist across daemon or desktop restarts. Other explicitly registered local accounts receive minimal notification projections through scoped credentials without switching the selected workspace or loading content roots. A stopped presenter, sleeping/offline device or disabled OS permission cannot provide timely local alerts. The warning is informational; cancelling still uses the existing authenticated device approval flow. The [notification contract](https://github.com/ldclabs/ic-panda/blob/main/docs/protocol/notifications_zh.md) describes remote capability negotiation, preferences and provider limits. Unlocking opens the root and returns as soon as local content is readable; the daemon then syncs once in the background, even with periodic sync disabled. A matching stored root uses the security already checked on unlock without contacting the relay. Content sync and flush passes serialize submissions, but release the client during network waits so local reads, edits and locking remain available. Status includes `syncing` and the last sync error; the log's `sync/pass` records each pass's duration and failed stage without content or identifiers; `last_sync.stage` also identifies that step. An unlocked account automatically retries `NETWORK_UNAVAILABLE`, `UNAVAILABLE` and `EXECUTION_UNKNOWN` failures after 60 seconds, even with periodic sync disabled. The background loop checks every ten seconds when idle; other background work can delay the retry. Success clears the failure. Locking pauses these retries; integrity, permission and other permanent failures require attention rather than retrying. Every write waits for the next sync pass (`dmsg sync`, the scheduled sync, or the one after unlock); `status` shows pending versions and conflict copies. An edit that lost a race is kept as a conflict copy on every device; `vault resolve` adopts it, or keeps the current version with `--keep-current` (the desktop also merges them part by part). An item in the trash takes only `vault restore` (or adopting a copy) back. `profile show` and `profile resolve` return the official PrincipalDocument. Edit its display fields in a JSON file and run `dmsg profile publish `; the account mutation checks the original updated_at and reports directory publication separately. `dmsg profile retry` reconciles an uncertain document mutation and retries publication. `profile avatar` uploads a public raster image and returns its immutable URL; put the returned `public_url` in avatar_url before publishing. Production uploads return `https://assets.dmsg.net/avatars//`; the client does not derive this from the API origin. Uploading never publishes a draft. The desktop reads `profile/avatar_image { avatar_url }` for both new uploads and legacy HTTPS image links. A successful publication (including a retry) emits `profile/changed` so the sidebar rereads the published name and avatar. Files. The file library (`dmsg files`) keeps files on this device only, in folders, each file as a set of versions with its own key, and nothing of it syncs: a backup to the cloud is an explicit action, a file deleted here keeps its backup, and a backup deleted there keeps the file here. `files add` encrypts files and folders in one pass through a 1 MiB buffer (up to `files_max_bytes`, 4 GiB by default), sniffs the type from the bytes, keeps a thumbnail of an image, and resumes an interrupted import of the same file on the same bytes; a folder comes in as a folder of the same name. A file of the same name in the target folder takes the import as a new version, and a folder of the same name the folder's files, unless `--keep-both` stands the new one beside it as `name (2)`. `files/import_cancel`, which needs no lock on the client, stops an import under way at its next chunk and drops its unfinished file; what it added before stays. `files/search` also keeps the files under a `folder`, the `starred` ones or those with a `tag`, and `files/tags` counts the files of each tag. `files get` writes only a fully verified version to a path that does not exist yet; `files open` exports a copy to `open/` for another program and removes it after 30 minutes, on lock and on exit, asking first (`files/open_changed`) when the program changed it, so the change can be kept as a new version. `files rm` moves to the trash, emptied after `files_trash_days`; `files purge` empties it now. `files verify --all` checks every chunk file against its name, which needs no key, beside the library, so other requests go on meanwhile, then every version while unlocked; the daemon does the same once a day after a minute without anyone at the device, and `files usage` shows the last check (`last_check`) with what failed. `files share` sends a version to a channel as a new edition under its own key: it shares no key and no chunk with the library's copy or a backup. `files save` keeps a shared file from a channel message as a file of the library, re-encrypted under a key of its own. File imports, exports, previews and verification release the client between chunks, so other local requests and locking can proceed during large files. The desktop renders local listings and cached cloud inventories before waiting for quota and remote refreshes; a late response cannot replace a different folder or account's listing. `files local-only` tells what only this device holds: local versions without a cloud backup, changes waiting to sync and when a sync last succeeded; the desktop shows it before revoking a device or binding the workspace to its hardware, and when syncs have failed for a week. Backups. `files backup` queues the requested versions durably and returns; `files backup-status` reports their progress, and the `files/backup_run` RPC runs an explicit upload pass. The daemon wakes to run queued jobs in the background. A successful queue response does not mean the upload has finished. The backup explicitly stores the library version itself in the cloud: it uploads the current version (or every version) of the files named, folders recursively, as `kind=backup` objects whose chunks are the version's own and whose manifest, sealed under the current content root, holds the file's key, path, tags and note; the object and version IDs on the relay are random. The jobs continue in the background, locked too with `background_online`, in slices of about five seconds with other requests going first in between, and `backup-status` shows them; a failed attempt is tried again five minutes later. Nothing starts a backup but this command: not an import, not an edit, not a cloud refresh, and a copy deleted from the cloud is never uploaded again. `files cloud ls --refresh` reads the account's backup inventory from the relay (every device's, each entry's signed plan checked against the certified evidence the relay kept when it was reserved, so backups of devices replaced since still count, each manifest opened with the root of its generation; one whose root this device lacks is listed as such and opens at a later refresh, once the root is here), marks local versions the backups are of, and `cloud get` fetches one into the library, where it was or into `--to`, after checking every chunk and the whole file. `cloud rm` deletes cloud copies for good, which frees their quota and changes nothing on this device; the copy a version released with `files evict` reads from is its last, so `cloud rm` refuses it until `cloud get` brings the version back or the version is deleted here. `files rm` on this device changes nothing in the cloud. `cloud verify` downloads and checks a backup; `files evict` then frees a verified version's chunks here, so it reads only after `cloud get`. `cloud usage` shows the relay's storage room; a backup request that would not fit fails with `QUOTA_EXCEEDED` before anything starts. Links. `files link` shares a version with someone outside dMsg: a fresh edition under its own key goes to the cloud as a `share` object (its manifest sealed under that key, never a root) and the relay publishes the link `/s/#`, the site being the one of `login_url`. The key rides in the fragment, which servers never see; with `--password` the link carries no key and the key travels wrapped under an Argon2id key of the password (19 MiB, two passes, salted with the share ID), so the person needs both. A link lasts `--days` (seven by default, thirty at most) and `--max-downloads` starts (unlimited by default); `files links` lists this device's links with the counts the relay last reported, and `--refresh` reads the relay, which also lists links other devices made, with names and URLs when this device holds the account root for their encrypted management record, and otherwise by ID. `files link-revoke` accepts asynchronous cleanup; an expired link's copy is queued for cleanup automatically. Space returns only after physical cleanup and quota settlement. The browser page at `/s/` decrypts by the chunk rules of `content-v1.json`. Mount. With `files_mount = true`, or the desktop's settings allowing it, `files mount` serves the library as a loopback WebDAV share at `/dav//` and mounts it through the system (macOS NetFS, Windows `net use`, Linux `gio mount`), as the disk `dMsg Files` (`dMsg 文件` in Chinese). The desktop passes the volume name in its interface language; the CLI uses its own locale. The name is fixed for that mount, so a language change takes effect after remounting. Finder's separate server group uses the URL host (`127.0.0.1`); changing the volume name does not rename that system-managed group. The token is random for each mount and lives only in the daemon's memory; on macOS the mount also carries a random Basic password, which NetFS takes without asking the person. The daemon sends it over stdin to a short-lived `dmsg mount-netfs` child; no helper app or credential file is created. Reading decrypts one 1 MiB chunk at a time, ranges included; a file written to the disk waits, owner-only, in `mount/` until the whole of it has arrived, then becomes a new version of the file of that name or a new file; a folder maps to a folder, a delete goes to the trash, a copy re-encrypts under a new key, and an editor's safe save (a temporary file moved over the original) becomes a new version of the original. `.DS_Store`, `._*`, `Thumbs.db`, `desktop.ini` and the like are accepted and dropped. A lock, an account switch, `files unmount` and the daemon's exit unmount, and the share answers nothing without the token. Mounting is off by default because of the systems' WebDAV clients: macOS keeps a plaintext cache of opened files in its system cache directory while mounted; Windows refuses files over 50,000,000 bytes (`FileSizeLimitInBytes` of the WebClient service), so larger files go through `files get`; Linux mounts through GVFS, which programs not built on it reach through its FUSE path. `files mount --status` shows the mount with the system's note. A mount in progress reports `mounting: true` and `mounted: false`. On macOS, status reads and the background pass check the system mount table: ejecting in Finder clears the share and notifies the desktop. Mount and unmount requests also reconcile this state, so an already ejected disk can be mounted again or unmounted successfully. Failed unmounts of disks still mounted return an error and remain tracked for retry. Reads and writes count as activity for idle locking; directory metadata polling does not. Changes through the disk notify desktop views. The mount tests cover the daemon's HTTP routes as well as the DAV filesystem. On macOS, after `cargo build -p dmsg_cli`, run `cargo test -p dmsg_cli native_mount_ -- --ignored --nocapture --test-threads=1` for explicit system mount tests using temporary offline accounts. They need permission to mount a volume and exercise reads, writes, safe saves, unmounting on lock and reconciliation after an external eject. Windows and Linux require separate native validation. Approvals are decided by a person: `approvals approve|reject`, `connect browsers add` and the prompt after `attest …` or `device …` need an interactive terminal without `--json`; otherwise the request is only created and waits in the approval center (and the desktop's approval window). A request is named by its ID or a unique prefix of at least six characters. A web request shows its origin as relayed by the browser through connect.dmsg.net, the browser's label, the account and the payload. `approvals list --all` shows finished requests too, for 30 days after they were made, with who decided them, where and when. Each source other than this device's own clients (an agent, a client, a web origin) has at most five requests waiting. A request the daemon rates high-risk (a payment, an added or revoked device, a change to a device's capabilities or to the account's logins, signing policy, recovery delay or Agent principal) shows as such, and on a Mac whose Secure Enclave keeps the fast-unlock key approving it first asks for Touch ID or the login password; declined, the request keeps waiting. Where the account registered this device's approval key, that question goes through the key, which also signs the approval. `approvals check-file ` compares a file with the digest a request signs (a page's document, or a digest given in hex) without changing what is approved; `approvals reconcile` settles approved requests whose outcome is not known yet, which the daemon also does on its own. An attestation whose outcome the home no longer keeps (a day past its approval) ends as `lost`. Settings read and prepare browser invitations, candidates, grants and revocations without holding the client during relay requests. Candidate reads and grants recheck the local invitation and its expiry after the wait; granting still requires fresh FormalApprove authority and explicit human confirmation. Policy edits reuse one account read for their previous policy and approval checks. Profile publication reuses its final principal read; account mutations retain the existing serialized account journal. Approval lists read in short local steps and omit filesystem metadata checks; the selected request's detail and execution still check its file. The desktop uses `approval/list {ids_only:true}` for waiting-request navigation, without decrypting every request. File preparation, comparison and bundle verification run on blocking workers; approving a local file still hashes it again before reading fresh account state and signing. Signature history opens each execution once, and exporting a synced signature looks up that execution directly. `attest readiness` says whether this device can sign now: a login, formal approval on this device, a signing policy that is not frozen, and this month's allowance as last read. Finished attestations are kept by the account as encrypted content objects that sync like vault items, so `attest history` lists those of the account's other devices too and `attest export` writes their bundles; a device recovered after all were lost has them after its first sync. `attest verify` needs no daemon and reports each check on its own: the statement against the file (`matches_file`, `mismatch`, `digest_only`, `text` or `action`), the device's signature, the receipt's certificate under the configured root from one of the registry's user homes, the receipt's binding to the artifact, its key, account and request, and the device's present status; a device revoked since does not undo a signature that verifies. The command fails with `INTEGRITY_FAILED` after its report when a check fails. Whoever receives a bundle can also verify it in a browser at `https://dmsg.net/_/verify`, or with `verifyAttestationBundle` from `dmsg-sdk/bundle`. `attest action` takes an application action its product prepared, as the canonical CBOR a page would send to `signAction` ([app-action](https://github.com/ldclabs/ic-panda/blob/main/docs/protocol/app-action.md)): the app's current registration must admit it and it must name this account. The origin shown is the action's own; nothing relays it. Approving asks the product authority (`inspect_app_action`) first, and a refused action fails without a signature; the request waits no longer than the action is valid. The CLI's own text (reviews, prompts, summaries) is in Simplified Chinese when the locale (`LC_ALL`, else `LC_MESSAGES`, else `LANG`) starts with `zh`, otherwise English; `--json` output, error codes, the daemon's messages and `--help` stay as they are. Channels: `create` makes the first epoch at once. `invite` seals the current epoch's key to the invited account's devices, so after `accept` with the JSON printed it reads that epoch from its start, what was written before it joined included; `rekey` first when it should not, and `history` gives it older epochs. An invitation is accepted only in the epoch it was issued in, so one made while the channel waits for keys rotates it first when this account may coordinate; otherwise it carries no key and lapses with that rotation. Removing a member, a member leaving, a revoked device or `rekey` leave the channel at `rotation_required`; an unlocked daemon whose account may coordinate (the owner, an admin or a member with `can_rotate`) rotates it on its own, and `rotate` does it at once. A device a member adds needs no new epoch. `uninvite` withdraws an open invitation. A billing transfer (`sponsor propose`) pauses the channel's messages until it completes, and `sponsor cancel` calls it off. `send` journals a message before it signs it, and a retry with the same `--message-id` never sends it twice; `outbox` lists what is still on its way and `outbox --discard` gives one up. `settings` renames a channel for this account, mutes or hides it, `search` looks through what this device read, and `receipts` shows how far members' devices took and read the messages. A message that does not open stays in `read` as unreadable instead of stopping the channel; a history grant has its epochs read again on the next `read`. `read` prints what this device read; while unlocked the daemon also reads the channels the account's hint channel names. Locked, the account's hint channel says only that a channel has new messages or a letter arrived, and the desktop notifies without saying from whom. A command whose reply was lost is kept in `pending`, and running it again, or `pending --key`, settles it under the same request ID. After `leave` the relay serves the channel no more to this account; the device keeps the last state it verified. The channel loop reads up to four independent channels concurrently and prioritizes hints over periodic reads. A hint during a read queues another pass; the follow-up for the relay's five-second hint window remains. Inviting and rotating hold only the channel's control-operation turn, so other channels and local reads remain responsive during network waits. The desktop opens cached messages immediately and refreshes the selected channel in the background. A sent message appears on its durable ACK, while earlier incoming messages are merged into their sequence positions. Inbox refreshes resume from the last verified page. Letters and the page cursor commit together, including pages filtered down to no visible letters; the end is reached only when the cursor stops advancing. The desktop reads the sealed local cache with `inbox/list {refresh:false}` before refreshing, and reads the cached contact policy with `inbox/policy {refresh:false}`. Sending, marking, configuring rules, requesting payment approval and checking or recovering escrow funds wait on the network without holding the client. An acknowledged mark updates cached flags immediately. Retrying a send keeps its original order and sealed payload; locking stops later local writes. Plan status reuses one service lookup and reads certified entitlement, contract terms and catalog concurrently. Quote preparation, checkout balance checks and name preparation release the client during network waits, with the unlocked session and payer rechecked before saving journals or approvals. Name prices read their three independent inputs together; transfer monitoring batches certified owner proofs and bounds acceptance queries to four at once. `handle/operations {refresh:false}` reads only the local operation journals. Payments go through the approval center like signatures: `inbox pay`, `plan checkout|advance` and `handle claim|register` only create the request, which a person approves at the terminal or in the desktop's approval window, seeing the exact amount, ledger and payer. The payer is the login's Principal unless `payer use ` names an identity file; the dMsg account itself never holds funds. A paid letter is `inbox send --pay` (a quote), then `inbox pay`; a subscription is `plan quote`, then `plan checkout`. A web application's checkout arrives as a web request and is quoted (`approvals quote `) before it can be approved; the page gets the order's progress. `payment revise` resends an escrow transfer the ledger refused at the fee it asked for, never above the escrow's limit. `inbox refund` claims, in one transfer, what a letter's escrow holds for the wallet: the payment after the acceptance deadline, the unused fee reserve once every payout succeeded, and deposits the escrow did not take. Team wallets (`dmsg wallet`) are canisters of their own, created through the hub for a one-time ICP activation within the plan's quota. `quote` is an update because it stores the deposit and expiry it returns; a plan with no wallet left quotes `remaining` 0 instead of failing, and `create` refuses that quote. The desktop reads the stateless `wallet/quote_preview` for the fast price, fee and quota view. Proposing, executing what members approved, broadcasting and reporting run at once; `create`, `join`, `approve`, `reject`, `veto`, `unbind`, and a transaction this device must cosign, wait in the approval center. `refund ` returns a quote's deposit, less the ledger fee, to the identity that paid it once the hub failed to create the wallet or the quote expired unused; the quote's ID is in the create request's approval details. The daemon calls wallets with a wallet key kept on this device (`wallet principal`), which `join` binds to the account with a device approval, one binding per device; deciding still needs a `WalletApprove` device every time. A new device takes over a retired one's binding with `join --replaces `, or every other device's after a login recovery with `--exclusive`; `unbind` removes the bindings of lost devices, and `bindings` shows which of this account's bindings belong to revoked or unknown devices. Neither changes the member's role or votes. `execute` reads chain parameters from the `[wallet]` endpoints, checks the wallet's plan with its own decoder, and broadcasts what the wallet signed; `settle` reports it final once the chain says so. `cosigner-new` keeps the key in the Secure Enclave and fails where there is none; only `--software` makes a software key, which a wallet requiring hardware cosigners refuses. `native-create` makes this device's root of native Taproot (BIP-340) keys, sealed for a new Secure Enclave key, or with `--software` under the local key; `native-protect` and `native-unprotect` add and remove such keys, one always staying. `native-key` derives this device's key for a wallet and prints its `AddCosigner` intent; it and every L1 signature ask for the person. `nc-migrate` shows how a native address moves to this device's key (register the key, add an address, the address book when the tier requires it, then a sweep through L1 or, with `--l2`, the chain key after the delay) and with `--start` proposes the next step. Names move between accounts in three steps, the last two within a minute: the owner's `handle transfer ` prints a token, the target account's `handle accept ` authorizes receiving it, and the owner's `handle commit ` moves it; both are approvals. `handle reconcile --block N` settles a registration whose charge is unknown with its ledger block. `ops` reads the orders, cash transfers and PANDA commitments the wallet may see as payer, merchant or operator and repeats their original operations: reconcile an order, retry a transfer, revise a refused transfer's fee as its recipient, refresh or reconcile a claim, release expired commitments. `attest usage` shows this month's formal executions and archives finished months in the workspace before the home drops them. Agent principal reads, publication/refresh and approval preparation use short session-bound client steps. Controller registration reads the next generation once; renewal and revocation read the principal and stored credential together. Network waits leave local reads and locking available. Approved account changes still use the account journal's existing serialized execution path. Agents. `agent principal enable` and every `agent controller` change are account changes an administrator device approves; the user home publishes the principal document to the directory (`published: false` in `principal show` means it has not yet, and `principal publish` retries). `controller register` creates the key in the vault; without `--scope`/`--audience` its ceiling is `*`. `agent grant` and `revoke` sign, on a device with `FormalApprove` and after approval, with the newest current controller whose ceiling covers the grant, or the scopes and relying parties of the credential revoked or replaced (`--generation` names one, which must cover it); no such controller is `FORBIDDEN` before anything is approved. `agent grant --replaces ` replaces a credential under its ID for a new lifetime, with the same subject and scopes and relying parties among its own (anything wider is `INVALID_INPUT`). `delegations` shows where each signed event stands and `credentials` what the delegation service holds. `principal publish` also has the delegation service read the published document again. `agent id create