FAQ

When you need this: You have a quick "what happens if..." question about syncing skills or MCPs.

Will Kasetto Overwrite My MCP Entries?

No. MCP merges are additive and existing server entries are never overwritten. See How Sync Works.

What Happens When Two Sources Define the Same MCP Name?

First write wins based on config order. Later sources with the same server name are skipped. See How Sync Works.

Where Is the Lock File?

• Global scope: $XDG_DATA_HOME/kasetto/kasetto.lock (default: ~/.local/share/kasetto/kasetto.lock)
• Project scope: ./kasetto.lock

See How Sync Works.

Should I Commit kasetto.lock?

Yes. For project scope, commit both kasetto.yaml and kasetto.lock, just like you'd commit Cargo.lock or package-lock.json. The config says what you want; the lock pins exactly which versions everyone gets. The lock is deterministic and portable (relative paths, no timestamps), so it diffs cleanly. Machine-local runtime state lives in the cache dir and is never committed. See How Sync Works → The Lockfile Contract.

How Do I Update Pinned Versions?

Run kst sync --update (alias -u) to re-resolve branch / default-HEAD sources and rewrite the pins. A plain kst sync honors the lock and won't fetch when destinations already match. Use kst sync --update <name> to update only selected entries, or kst sync --update-local to re-resolve every local directory source (the usual way to ship your own skill edits without touching remote pins). See How Sync Works → How sync Honors the Lock.

How Do I Uninstall Safely?

• To remove tracked installs for a scope: kst clean
• To remove everything including the binary: kst self uninstall

See kst clean and kst self uninstall in Commands.

Can I Use Multiple Agents?

Yes. Set agent to a list. See Configuration.

Does Kasetto Run Code from Skills?

No. Skills are copied as directories. Execution is up to the agent you load them into.

Can I Pin Sources to a Known-Good Version?

Yes. Use ref: with a tag or commit SHA. See Cookbook.

What Does --dry-run Do?

It prints what would change without writing any files. Useful in CI. See CI & automation.

Why Didn't My MCPs Show Up?

Most common causes:

• The target agent settings file is malformed JSON/TOML
• The MCP file doesn't contain a top-level mcpServers object

See How Sync Works (corrupted settings file behavior).

How Do Remote Configs (--config https://...) Authenticate?

Kasetto selects tokens by the URL hostname using the same rules as skill/MCP sources. See Authentication.

Why Does kst sync Fail Behind a Corporate Proxy?

Kasetto honors the standard proxy environment variables (HTTPS_PROXY, HTTP_PROXY, ALL_PROXY, and NO_PROXY) and trusts both its own bundled root certificates and your operating system's certificate store. A proxy that re-signs TLS therefore works as long as its CA is installed system-wide. This covers corporate TLS-intercepting proxies and sandboxed environments such as Claude Code cloud sessions.

To point Kasetto at a CA bundle explicitly, set SSL_CERT_FILE to a PEM file or SSL_CERT_DIR to a list of directories. Setting either one replaces the platform store rather than adding to it; the bundled roots stay active, so public certificate authorities keep working either way.

One consequence worth knowing: because the platform store is trusted, Kasetto accepts any certificate authority your operating system accepts, including an interception CA that can read sync traffic.