Before starting a task, decide which documents it needs, which service may receive them, and which changes you will review. A request to summarize one document needs a smaller scope than permission to edit a workspace or publish to a connected service. This guide targets Sonny 0.12.7. The recovery runbook is for the person responsible for preserving and restoring the machine’s state.
Review what can act
A Recipe describes the workflow and the tools available to it. Permission checks decide whether a particular call may proceed. Isolation limits the environment where a call runs. Review all three: loading a Recipe, granting a call, and verifying an execution boundary are separate decisions.
Use the Recipe trust guide to review provenance and the MCP connection guide to inspect an executable or remote endpoint before approving it. A downloaded repository can contain instructions, model fragments, hooks, and tool configuration. Read these before trusting its workspace. Trusting a workspace does not approve every future tool call or prove that a remote service has suitable access controls.
Review lifecycle hook commands as executable configuration. Disabling model tools does not disable those configured hooks.
When a call is denied, inspect the named policy, selected Recipe and exact operation. Narrow the request or ask the operator to review that particular capability. A missing connection, an unavailable credential, a denied tool and a failed isolation check require different fixes. Repeatedly resubmitting the same request cannot grant the missing authority.
The dangerous auto-approval and isolation-bypass switches change different protections. Trusted machine/user policy can forbid them; project configuration cannot grant them. They are unsuitable as a general fix for a denied call. The policy and permissions reference lists the exact file fields, environment requests, ceilings and inspection exits. Automatic approval also does not override a tool denial or a trusted isolation floor. An isolation status label alone is weaker evidence than executing the required boundary and cleanup checks. The mesh operator guide explains how to read the release’s isolation doctor output. Use the isolation configuration reference for the policy, machine-trust and image-statement contracts; a schema check alone does not establish a verified boundary.
Follow the information
| Destination | Information that may reach it | Review before use |
|---|---|---|
| Selected model provider | Your prompt, conversation history, supplied documents, composed instructions and relevant tool results | Provider, endpoint, account, retention agreement and Recipe/model selection |
| MCP server or other connected tool | The admitted call and its arguments; returned content joins the task | Executable/URL, arguments, environment references, server scope and remote access policy |
| Local tools | Workspace files, command inputs and generated artifacts within the admitted scope | Read/write scope, approval request and verified isolation posture |
| Local stores and exports | Sessions, traces, retrieved memory, tool results, diagnostics and exported documents | Actual paths, filesystem access, retention, backup copies and intended recipients |
| Configured telemetry/training services | The enabled telemetry or explicitly selected upload/export payload | Destination, content settings, consent and service retention policy |
Running the UI locally does not establish that the model or a connected tool is local. An API key authenticates a provider connection; it is not a limit on which document content the model request contains. Inspect the provider selection and credential flow separately.
Traces and conversation history
Conversation traces are on by default. For a local session they normally
live under <data>/traces/<session-id>/; hosted sessions use a tenant
subdirectory. --trace-dir selects another root. Use --no-trace for one run,
or set SONNY_TRACE=0 before launch, to opt out of conversation tracing.
Neither switch deletes old traces, clears conversation history or prevents
model/tool requests.
In the executed one-shot fixture, --no-trace suppressed the run’s own trace
but an internally launched MCP-server process still created a separate trace
under traces/mcp-server/. The same child-trace creation occurred with
SONNY_TRACE=0 on the parent. Whole-process-family trace suppression remains
unqualified in this release; inspect subprocess stores as well as the run’s
reported trace path. Other applications and remote services have their own logging.
The installed release redacted a synthetic password= assignment in a trace,
but retained an arbitrary private note and sent the original input to the
controlled model. Pattern-based redaction cannot establish that an arbitrary
document, identifier or opaque credential is safe to share. Treat traces as
private task content even when known token patterns are masked. This release
does not automatically expire these conversation trace files.
The TUI’s sessions.db retains original message and tool-result content for
resume. The executed fixture recovered that original text from a real TUI
conversation. The one-shot --prompt path created a session row but did not
checkpoint a transcript there; a matching session ID alone is not proof that
a later headless call has replayed its history. Keep required one-shot outputs
and task evidence explicitly. See sessions
for the
separate metadata, export and portability boundaries.
OpenTelemetry is a separate system: an OTLP endpoint can enable it when
SONNY_OTEL is unset. SONNY_OTEL=0 disables that instrumentation and
OTEL_SDK_DISABLED=true is its hard-off switch. Raw content attributes are off
by default; SONNY_OTEL_CONTENT opts into them. These settings do not disable
conversation traces. Context-efficiency telemetry is another separately
requested output. Check the launching environment and service configuration,
including inherited endpoint variables, when reviewing where diagnostics go.
Locate and protect local data
Run sonny config path under the same account and environment as the affected
client. The configuration directory table
lists Linux/BSD, macOS and Windows defaults. XDG overrides are bases: the
standard resolvers append sonny. Explicit database, trace and service launch
options may point outside those roots.
The tested Linux release creates trace files as 0600, but its session SQLite
file can inherit a permissive process umask. A private containing directory
restricts traversal; it does not make the file itself owner-only. For new Unix
recovery files and launches handling private data, the runbook explicitly uses
umask 077. Review existing files and access controls separately; changing the
umask does not repair an existing file. Windows ACLs and installed macOS/Windows
client behavior need platform-specific verification.
| Store or location | Purpose and sensitivity | Retention/deletion boundary | Recovery and rebuildability |
|---|---|---|---|
<config>/models.yaml, models.d/, Recipe sources, MCP/hooks/UI configuration | Endpoints, paths, launch definitions and approved behavior; configuration may itself contain secrets | Retained until edited/removed; revoking an approval does not erase remote data | Back up reviewed configuration; revalidate endpoints, executable hashes and approvals after restore |
<config>/pack-keys/, catalog-keys/, mesh client material | Trusted public keys; mesh private keys confer identity | Removing a local key does not revoke a copy or certificate elsewhere | Preserve the intended trust roots; private material needs a separate protected recovery plan |
<data>/credentials/, OS keychain, OpenBao/Vault | Provider credentials and, for the sealed-file fallback, its decryption material | Removing local files does not revoke a provider token or erase a keychain/remote store | Reauthenticate through the supported flow; do not treat a copied database as a portable login |
sessions.db (--session-db, SONNY_SESSION_DB) | TUI history, settings and legacy credential-related state; original content is sensitive | Session deletion is a logical operation; traces, exports, snapshots and external effects have separate lifetimes | Use a consistent SQLite snapshot; conversation content cannot be rebuilt from an empty store |
control.db (--control-db, SONNY_CONTROL_DB; managed manifest selects its own path) | Ownership, workspace trust, plans, audit/control records and runtime blob references | Stopping a session does not remove all control records | Preserve its related profile, encryption keys and deployment configuration as one stopped recovery set |
<data>/runtime/, localprofile/, profiles/ | Runtime blob key and local identity/signing material; private authority | Key loss can make retained encrypted state unreadable; local deletion does not revoke enrolled devices | Protect keys separately from public diagnostics; a database-only copy is insufficient |
<data>/traces/ or --trace-dir | Conversation event JSONL, with pattern-based redaction | No automatic conversation-trace expiry; opt-out affects future writes | Copy closed files if needed; excluded traces cannot be recreated from an empty store |
<data>/memory/, project .sonny/memory/, installed Recipes | YAML memory records and Recipe content; may reveal private facts | Deleting a record does not retract prior model requests, conversation copies or exports | Preserve authoritative YAML; derived memindex/ may be rebuilt |
<cache>/pack-repos/, catalog-repos/, memindex/ | Source clones and derived indexes, which may contain private content | Inspect local edits before cleaning a clone | Rebuild only from available, pinned sources or authoritative memory; preserve unpublished edits |
<cache>/worktrees/ or SONNY_CHILD_WORKTREE_DIR | Delegated worktrees, possibly with unmerged changes | A cache label does not authorize removal | Review and integrate or back up each owned worktree together with its Git repository |
<state>/ | Fitness overlay, availability, tabs, policy ledgers and worker audit | Per-file behavior; worker audit rotates at 1 MiB, while policy/audit records may be required evidence | Preserve required state; do not broadly call it disposable |
Project .sonny/, exports and alternate paths | Memory, paste images, init journals, Recipes and chosen output files | Removing user data roots does not remove project or explicitly selected outputs | Inventory separately; preserve work and journals needed for recovery |
Some paths bypass the standard resolver: pack signature keys fall back to
~/.config/sonny/pack-keys unless SONNY_PACK_KEYS_DIR is set; the legacy OAuth
key uses $XDG_CONFIG_HOME/sonny/oauth_token.key or that Linux-style home
fallback; active tabs use $XDG_STATE_HOME or ~/.local/state/sonny. The
context-inspection cache defaults to ~/.sonny/trace/cache.db. Check these on
macOS and Windows as well as the platform-native roots. The table is
source-derived across platforms and exercised on Linux, not an installed
cross-platform certification.
Share a small diagnostic
Start with the version, the exact error and a synthetic reproduction. Inspect configuration snippets for keys, tokens, private URLs and identifying paths. Read exports and trace excerpts before attaching them. Avoid sharing an entire session/control database, credential directory, recovery bundle or environment dump. A redacted trace still requires a content review.
Delete data deliberately
First review active work and preserve anything needed for recovery. Revoke provider tokens and remote access through the service that issued them when appropriate. Close clients and stop their writers before removing local state. Use the session or memory operation for a targeted logical deletion, then inspect separately retained traces, exports, backups, project files, worktrees, remote integrations and provider retention.
Uninstalling the executable does not remove these stores. Removing one store does not securely erase SQLite free pages/WAL, filesystem snapshots, other devices, exports or external/provider copies. Disk encryption, backup retention and organization deletion policy remain relevant. The recovery runbook explains how to separate preserved state from a disposable restore test.
Before sharing run data, review trace audiences and capture limits and the separate training/export eligibility and collection scope .