Install DSH plugins offline using a plugin market package

A first offline DSH plugin install is less about the command than about where the package comes from and how dependencies get resolved: prepare the plugin's tarball on a connected machine, carry dependencies in if needed, then run dsh plugin --profile web add ./<name>-<version>.tgz on the target host and verify with list plus the profile's node_modules (source).

Offline versus online DSH plugin install: only the fetch step moves

An online install lets the package manager fetch from a registry; an offline install moves that fetch to a connected machine and leaves only the write on the target — both end at the same place, $DSH_HOME/profiles/<name> (source). So the whole chain is two questions:

1. Where does the package come from: a tarball published by the author, a tgz you build with pnpm pack, or a private registry;
2. Where does it go: dsh plugin --profile <name> add <local path>, with the profile named exactly.

Keep the scopes apart: installing the host offline and installing plugins offline are two different paths. The host is covered in installing dsh in an air-gapped network; this article covers the first DSH plugin on a machine that has none. If the plugin is already installed and you only want a newer version, follow offline plugin updates instead.

Step 1: prepare the DSH plugin package on a connected machine

With no public registry in reach, the package must be prepared on a connected machine, and dependencies need planning early (source). Three ways to get it:

1. Carry the author's published tarball — the least effort; add already accepts a .tgz path, so the published artifact can simply be copied in.
2. Build one yourself on a connected machine — the route to use when you hold the source:

# On a connected machine, inside the plugin source directory
pnpm pack
# → dsh-hello-plugin-0.2.0.tgz

Mind the order: pnpm pack only collects build output, so build steps such as prepare must complete on the connected machine first, or the archive you carry in is an empty shell.

3. Go through a private registry — if the network runs something like Verdaccio, publish the plugin and its dependencies there and internal hosts install by package name; this route solves dependency resolution as a side effect.

The most common trap: a tgz holds only the plugin. On a first install the profile has no dependencies yet, so the package manager must resolve them from a registry — fully offline that fails during resolution. Two ways out: run a private registry in the network, or pnpm pack the dependencies as well, install those first, then install the plugin.

Step 2: copy the DSH plugin in and fix the target profile

Copying is unremarkable — a temporary directory is fine — while choosing the profile is what actually matters (source). Three steps:

1. Identify the root — run echo $DSH_HOME. Expected: if it prints a value use it, otherwise the default is ~/.dsh.
2. List existing profiles — run ls "$DSH_HOME/profiles". Expected: web and headless appear, and air-gapped hosts often carry extra profiles, so pick deliberately; see installing one plugin into several profiles.
3. Confirm the plugin name and version — on the connected side open DSH Plugin Hub at Settings → Plugin Market and check the card for name, author and target version. Expected: the tarball you carried in matches what the plugin market shows, so you did not pack the wrong one.

Step 3: offline add to install the DSH plugin and verify

Installing is a single add against the local tarball: dsh plugin --profile web add ./<name>-<version>.tgz writes it into that profile's dependencies and node_modules. Four confirmations:

1. Run the install — from the directory holding the tarball, run dsh plugin --profile web add ./hello-plugin-0.2.0.tgz. Expected: the command enters the install flow instead of reporting a missing package; a resolution error means dependencies are missing, so return to step 1.
2. List what is installed — run dsh plugin --profile web list. Expected: the plugin and its version appear in the output.
3. Check the dependency record — open $DSH_HOME/profiles/web/package.json. Expected: the plugin is listed as an ordinary dependency.
4. Check the on-disk location — inspect $DSH_HOME/profiles/web/node_modules. Expected: the top-level directory matches the package name, with real files under .pnpm; see where DSH plugins are installed.

The plugin market still opens on an air-gapped host and is useful for checking plugin names and versions, but it does not supply packages — offline installs must use a local path.

Notes and limits for offline DSH plugin installs

1. Dependencies are the real obstacle: a tgz holds only the plugin, and a first install has nothing to resolve against, so a fully offline attempt always fails without a private registry or pre-packed dependencies.
2. Build before you pack: pnpm pack does not run build scripts, so a package missing output will fail again at load time.
3. --profile is required and has no short form: air-gapped hosts often run several profiles, and the wrong target means the plugin is not installed where you think.
4. Verify in three places: an exit code of zero is not proof; list, package.json and node_modules should all agree.
5. Roll back by reinstalling: run add again with a correct tarball to overwrite, and back up the whole profile directory before you touch anything.

Sources: dsh CLI README, Packaging and installing plugins (official docs), dshplugin/dsh-plugin-hub