Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/chamilonster/Piumy/llms.txt

Use this file to discover all available pages before exploring further.

Piumy has one owner-scoped MCP tool: reset_dashboard_password. It is the only tool in the MCP surface that checks whether PIMYWA_MCP_KEY is configured and refuses outright if it is not. The reasoning is straightforward: on an open MCP server (no bearer token), there is no “you are the owner” signal at all, so a password-reset tool would be reachable by any process on the LAN.

​
reset_dashboard_password

Resets the dashboard login password and returns the new plaintext password exactly once in the tool response. The dashboard stores passwords as bcrypt hashes, which are one-way by design. This tool does not retrieve the current password — it replaces it with a new one, then shows you the plaintext so you can save it. After the response is returned, the plaintext is gone; only the bcrypt hash remains in storage.
​
new_password
string
Optional. A specific password to set (minimum 8 characters). If omitted, a fresh random 24-character password is generated automatically.
Returns: 
{
  "password": "<new-plaintext-password>",
  "note": "Shown once — the stored hash cannot be reversed. Save this now (e.g. hand it to the account owner or a password manager); a future loss requires calling this tool again to reset it."
}
The new password is returned exactly once. After that it exists only as a bcrypt hash in the database — there is no way to look it up. Save it to a password manager immediately.

​
Refusal conditions

The tool returns an error (not a success) in these cases:
ConditionError
PIMYWA_MCP_KEY is not configured"refused: PIMYWA_MCP_KEY is not set — an open MCP server has no owner-only boundary to scope a password reset to. Configure PIMYWA_MCP_KEY, then retry."
new_password is provided but shorter than 8 characters"new_password must be at least 8 characters"

​
Example: generate a random password

Call the tool with no arguments to let Piumy generate a secure 24-character password: 
{
  "tool": "reset_dashboard_password",
  "arguments": {}
}
Response: 
{
  "password": "Xk7mPqW2nRvL9cBzYtD4sF8j",
  "note": "Shown once — the stored hash cannot be reversed. Save this now ..."
}

​
Example: set a specific password

{
  "tool": "reset_dashboard_password",
  "arguments": {
    "new_password": "my-secure-pass-2026"
  }
}

​
Why MCP auth is required for this tool

The bearer token configured in PIMYWA_MCP_KEY is the only “you are the owner” signal that the MCP transport has. Unlike the REST API (which gates sensitive actions behind a whitelisted JID or a dashboard login), MCP has no per-caller identity of its own — every connected agent looks the same to the server. This means:
  • If PIMYWA_MCP_KEY is set, the bearer token IS the ownership proof. Any agent that can make authenticated MCP calls is presumed to be operating on the owner’s behalf.
  • If PIMYWA_MCP_KEY is not set, the MCP endpoint rejects every request — but if it were somehow left open, any process on the LAN could call reset_dashboard_password and lock the owner out of their own dashboard.
Requiring PIMYWA_MCP_KEY before this tool will operate ensures there is always an explicit trust boundary in place. Configure authentication first, then use this tool.
Run sudo /opt/pimywa/pimywa auth setup to generate and persist a token. The MCP endpoint will then accept requests and this tool will become available.

​
Alternative: set the password via environment variable

If you prefer not to use the MCP tool (or if MCP is not yet configured), you can set the dashboard password directly in the environment file and restart the service. 
# In /opt/pimywa/pimywa.env — choose one method:

# Option A: plaintext (Piumy hashes it on startup)
PIMYWA_DASH_PASS=mynewpassword

# Option B: pre-compute a bcrypt hash yourself and set it directly
PIMYWA_DASH_PASS_HASH=<bcrypt hash>
Then restart the service: 
sudo systemctl restart pimywa-core
The plaintext variable (PIMYWA_DASH_PASS) is hashed and removed from the environment at startup — it will not persist in memory or logs. Using the pre-hashed form (PIMYWA_DASH_PASS_HASH) means the plaintext never touches the device at all.
Generate a bcrypt hash offline with any standard tool, e.g. htpasswd -bnBC 10 "" yourpassword | tr -d ':\n' | sed 's/$2y/$2a/' or the equivalent in Python (bcrypt.hashpw). Default cost is 10.

Build docs developers (and LLMs) love

Get started for freeTalk to us