Safety

Action policy and approvals

The policy engine is deterministic code. It classes every action before it runs, in the cloud and again on your machine, and the model cannot override it.

Every action there is

The model can only propose these typed actions. There is no shell, no file delete and no Docker prune: they are not actions at all, so no plan can contain them.

Action	Risk	What it does
`http_retry`	low	Repeat a GET or HEAD request.
`refresh_snapshot`	low	Collect a fresh environment snapshot.
`restart_container`	medium	Restart one container, checked by id and name first.
`restart_process`	medium	Stop a process and start it again with the exact command line and directory it was running with.
`stop_process`	medium	Send SIGTERM or SIGINT to a dev process. High risk for anything else.
`update_runtime_config`	high	Change one non-secret key in a project `.env` file. The original is backed up to `~/.whoseport/backups`.

The engine refuses outright: system processes (launchd, systemd, sshd, Docker itself), PID 1, secret-looking keys, files outside the project or that are not .env files, and commands containing shell syntax.

A policy decision

json

{
 "allowed": true,
 "requiresApproval": true,
 "actionClass": "mutating",
 "risk": "MEDIUM",
 "reason": "MEDIUM risk actions require approval"
}

Autonomy levels

Level	Name	What runs without asking
0	Observe	Nothing. Inspection only.
1	Explain	Nothing. Diagnosis and recommendations only.
2	Approve	Low-risk actions only. Every change waits for you. The default.
3	Guarded	Also restarts of containers and of known dev processes (node, bun, python, …). High-risk actions still wait.

The level is set on each machine, because the agent enforces it locally and a setting in the cloud should never widen what runs on your laptop:

bash

$ WHOSEPORT_AUTONOMY_LEVEL=3 whoseport agent start

Or set autonomyLevel in ~/.whoseport/config.json. Investigations started from whoseport ask --local and from the MCP server always run at level 1 and never change anything.

Who approves

The person who started the investigation, or an admin of the organization. Approvals happen in the dashboard and are recorded on the investigation timeline with who decided and any note. A decision is final: an approval cannot be decided twice.

Where actions execute

The cloud never gets a shell. An approved action travels as a typed object to your local agent, which checks it against policy again, confirms the target still matches what was observed, and executes exactly that action.

flow

Model proposes → Policy engine → Your approval → Local agent re-checks → Result → Verify

Verification is not optional

A command returning is not a fix. After the actions run, WhosePort checks the state the plan expected: a port free or listening, a process running or gone, a container running or healthy, an HTTP status, a TCP connection. If a check fails, the investigation ends as not fixed with the failing check, rather than claiming success.