Installing plugins safely

Installing a plugin is the same trust decision as adding any third-party dependency: the package's code runs with your harness's access to sessions, sandboxes, and storage. The catalog verifies that a package declares a dsh.bundle manifest — it does not review the code. Treat the catalog as discovery, not as a security guarantee, and vet a package before it goes into a profile you rely on.

Trust the source, then the contents

Only install from sources you already trust: a publisher you know, a repository you recognise, or a package that has been maintained in the open for a while. Then check the contents — a package name can be squatted or spoofed, so the name alone proves nothing.

Inspect before you install

Start with the metadata:

npm view <package-name>

It shows the description, version, license, repository, and keywords without installing anything. Then pull the exact tarball the registry would install (npm pack <package-name>) and unpack it to read the two things that matter: cordis.patch.yml, which states which plugin rows the package inserts or overrides, and the module entry it references, which is the code that actually runs. The patch is usually small and easy to read; the module is what you are really trusting.

Check the repository

The listing's detail page links the repository or mirror. Confirm it belongs to the publisher you expect, and that the npm repository field agrees. A package whose metadata points somewhere unrelated, or whose repository history does not match its story, is a red flag.

Try it in a scratch profile

Install into a dedicated trial profile before your real one:

dsh plugin --profile trial add <package-name>

Then confirm the layer applied:

dsh --profile trial --dump-config

If the layer is missing, the package has no dsh.bundle and installed as an ordinary dependency — it contributes no configuration (see Install your first plugin).

Remove it when done

dsh plugin --profile trial remove <package-name>

Removing drops both the dependency and its layer, so a trial profile is easy to clean up. When you are happy with the package, install it into the profile you actually use.