Use a published pack

Add a published pack to one runner: review its actions first, install a fixed version, grant only the access its actions need, and verify one action.

1. Choose a pack#

On the host, list the published packs that match it. The command checks what the host runs — programs, processes, ports — and installs nothing.

sudo emisar pack suggest

You can also browse the public pack catalog . Pick the pack for the service this runner hosts.

2. See what you are adding#

The pack's catalog page lists every action your agent will gain — with its arguments, side effects, and risk tier — plus the host requirements. Skim the list to know what the pack does; under the default policy, the risky actions wait for a person no matter what you install. Write down the pack ID, the version, and the full sha256 hash — the install pins all three.

3. Install a fixed version#

Pin what you reviewed: <pack>=<version> picks the published version, and --hash makes the runner reject anything but those exact bytes.

sudo emisar pack install redis=0.2.3 \
  --hash sha256:<full-reviewed-hash>

The command validates the pack, reloads a running runner, and ends by probing the pack's declared verify action. If that action lacks its required host access or credentials, the failure shows up now, at the terminal, and the next step fixes it. A public catalog hash becomes trusted automatically. A custom hash stays pending on Packs.

Installing from a private packctl registry uses its immutable URLs — see Host your own registry.

4. Configure host access and credentials#

Each pack ships its own setup guide. When its actions need protected files, sockets, or service controls, the guide maps that access to exact actions. Credentials are listed separately. It appears on the pack's catalog page under Setup, and on the host:

sudo emisar pack info redis

1. Install every missing program named by the pack.
2. If Host access is shown, run only the recipe for actions you intend to enable. Emisar displays these commands; it never runs them.
3. Put each required credential value in /etc/emisar/runner.env.
4. Add each required variable name to execution.inherit_env in /etc/emisar/config.yaml.
5. Restart the service after changing its environment, user, or groups.
6. Run sudo emisar pack verify redis — the probe that failed before the required access was in place passes now.

Keep credential values out of action arguments and pack YAML. See Pack credentials for the complete environment pattern.

5. Verify the pack#

1. Run sudo emisar doctor --probe. It checks the host and runs every pack's verify action. Fix every pack error.
2. Open Runners. Confirm that the runner advertises the new actions.
3. Open Packs. Confirm the exact version, hash, and trust state.
4. Run one low-risk read action from the pack.
5. Open Audit. Confirm that the event records the pack, action, runner, and operator.

For a fleet change, use a canary and bounded batches. See Roll out and roll back packs.

A pack that never appears, or an action missing from a runner that should have it — Troubleshooting separates the causes.