StorageOps
StorageOps is a Pi Coding Agent extension and skill pack for diagnosing S3-compatible object storage problems.
It is designed for cases like AccessDenied, SlowDown, SignatureDoesNotMatch, checksum mismatches, stale reads, broken lifecycle rules, failed notifications, and migration surprises. You provide logs, errors, configs, or a short description; Pi loads the StorageOps skills and tools to produce an evidence-based diagnosis.
What You Get
- 15 skill packs — 13 diagnostic (security, protocol compatibility, CLI/SDK behavior, performance, network access, lifecycle cost, replication, mount/workspace usage, migration, data consistency, access logs, big-data pipelines, notifications) plus triage and evidence-reporting — and 1 eval skill pack (16 packs total).
- 4 Pi extension tools:
scan_secretsredacts credential values and returns safe fingerprints.detect_domainranks likely diagnostic domains and recommends the next skill.search_memorysearches prior Pi sessions with scored, redacted snippets.capture_http_tracewraps one bounded command through httpmon and returns a sanitized HTTP summary. Known storage commands must be read-only; an unknown command falls back to bounded observation but is still executed, so use only side-effect-free commands.
- Deterministic helper scripts for access logs, policy analysis, throttling, ETags, payload hashes, small-object cost, migration estimates, SigV4 parsing, Spark committer config, mount workload suitability, endpoint reachability, and golden-case eval.
- A regression suite of compact golden cases and size gates to keep the repository lean.
Quick Start
Prerequisites: Node.js 22.19+, Python 3.11+, and a model provider key.
(Pi Coding Agent 0.78+ requires Node 22.19+; on older Node, npm installs an
incompatible legacy Pi and storageops install will refuse it.)
# 1. Install Pi Coding Agent (the runtime engine)
# storageops install does this automatically, but you can also install manually:
npm install -g @earendil-works/pi-coding-agent
# 2. Install StorageOps
python3 -m pip install storageops -i https://pypi.org/simple
storageops install
# 3. Configure a model key (pick one)
export ANTHROPIC_API_KEY=sk-...
export DEEPSEEK_API_KEY=sk-...
export OPENAI_API_KEY=sk-...
# 4. Run a diagnosis
storageops --print 's5cmd sync reports 429 SlowDown; diagnose likely cause'
Ubuntu / Debian: If
pip install storageopsfails with "externally-managed-environment", usepython3 -m pip install storageops --break-system-packages -i https://pypi.org/simpleon an isolated VM, or create a virtualenv first.Cloud or regional PyPI mirrors: If your default mirror reports "No matching distribution found for storageops", install from the official PyPI index:
python3 -m pip install --upgrade storageops -i https://pypi.org/simple
storageops install automatically installs Pi Coding Agent via npm if it is not
already present. It stops before deployment when an older Pi version is detected
and prints the manual upgrade command, avoiding both auto-upgrades and half-ready
StorageOps installs.
It also prepares the managed httpmon helper for capture_http_trace under
~/.storageops/bin/. PyPI release packages include the verified Linux amd64
helper used by common cloud VMs, so those users do not need to install httpmon,
install Go, or edit PATH manually. Other supported platforms use the bounded
download fallback when the bundled helper does not match.
Configure a Model Key
Use any one of these patterns:
export DEEPSEEK_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-...
export OPENAI_API_KEY=sk-...
Or store a local key for the selected StorageOps/Pi agent directory:
echo sk-... > ~/.storageops/agent/api-key
chmod 600 ~/.storageops/agent/api-key
A bare key in that file defaults to DeepSeek, then Anthropic, then OpenAI. To
bind it to a specific provider, prefix it with provider::
echo anthropic:sk-ant-... > ~/.storageops/agent/api-key # also: gemini:, groq:, ...
Supported prefixes: anthropic/claude, deepseek, openai, google/gemini,
mistral, groq, cerebras. (Without a prefix, a non-DeepSeek key would be
misrouted to DEEPSEEK_API_KEY.)
You can also pass Pi-native options through storageops, for example --provider, --model, --api-key, --print, --resume, or @file inputs.
For a guided local setup without editing JSON:
storageops configure --provider deepseek --model deepseek-v4-pro --api-key
storageops doctor
DeepSeek smoke test:
storageops smoke --provider deepseek --model deepseek-v4-pro
deepseek-v4-pro and deepseek-v4-flash are known-good DeepSeek choices with
Pi 0.78.0. If you keep a key in ~/.storageops/agent/api-key, StorageOps reads
it and exposes it to Pi; you do not need to pass --api-key for normal use.
Install Modes
Independent mode is the default:
storageops install
It writes:
~/.storageops/
├── agent/
│ ├── settings.json
│ ├── api-key
│ ├── extensions/storageops.ts
│ └── sessions/
└── skills/
Merge mode installs into an existing Pi setup:
storageops install --merge
It writes the extension to ~/.pi/agent/extensions/, skills to ~/.pi/skills/, and backs up settings.json before merging StorageOps settings.
Typical Workflows
Single-shot diagnosis:
storageops --print @rclone-debug.log 'Explain the checksum mismatch and safe next steps'
For failing writes such as PUT/copy/upload BadDigest or SignatureDoesNotMatch,
do not trace by re-sending the write. Use the server error body, the client's own
debug dump, and offline helpers such as
skills/storageops-s3-protocol-compatibility/scripts/check_payload_hash.py.
Interactive diagnosis:
storageops
Refresh an install after upgrade:
python3 -m pip install --upgrade storageops -i https://pypi.org/simple
storageops install --force
storageops install --force redeploys files from the currently installed local
package. During install, StorageOps prints the local package version and package
path, warns if PyPI has a newer version, and records deployment provenance in
~/.storageops/install.json.
For Ubuntu/Debian cloud hosts, or right after a fresh release when pip cache may lag:
python3 -m pip install --upgrade storageops --break-system-packages --no-cache-dir -i https://pypi.org/simple
storageops install --force
storageops --version
If the installer still prints an old StorageOps package: v..., the Python
package did not upgrade and old bundled skills were redeployed.
Run quality gates from a checkout:
make validate # fast skill/extension/doc gates (greps the extension)
make ci-local # offline PR gate (mirrors CI validate job)
make validate-full # alias for ci-local
make test # alias for ci-local
make test-fast # faster loop while editing
make ci-full # pre-release: ci-local + package-check
make dev # one-shot dev setup (venv, Node, storageops install)
make live-smoke # live model smoke + 3 golden-case diagnoses (needs API key)
make validate only greps the TypeScript extension; the routing, provider, and
trace behavior is covered by the extension tests, so run make ci-local
(or make test) before changing storageops_cli/extensions/storageops.ts.
make ci-full, install-smoke, and diagnosis-smoke need a wheel build
or network/model key — see Release.
Reproducible dev environment: open .devcontainer/devcontainer.json in VS Code
or Codespaces (make dev with --persist-path on postCreate).
Documentation Map
- Getting Started
- Cloud VM Install Guide
- CLI Reference
- Architecture
- Quick Reference
- Release
- Tutorial
- Skill Quality Guide
- Skill Taxonomy
- Routing Flowchart
- Dependency Map
- API Coverage Matrix
- Examples
- Changelog
- Security
- Contributing
Repository Note
The source tree keeps canonical skills at repository root and exposes them through storageops_cli/skills -> ../skills for packaging. The installer expects packaged skills to be available next to storageops_cli; review distribution changes carefully.
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for storageops 0.8.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| storageops-0.8.0.tar.gz | 3.5 MB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| storageops-0.8.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 7.2 MB
Release files / storageops-0.8.0.tar.gz
| Download URL | storageops-0.8.0.tar.gz |
|---|---|
| Size | 3.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3b6958ab77df15877fd8109b0bf8efd4032dca1f475f5220d48098251cf12bb2
|
|
BLAKE2b-256 checksum How to use checksums |
f577724d24c072d4d5da4ee58948af4a0b357f0268891c5b069794215c17ef76
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 30, 2026.
Transparency logRelease files / storageops-0.8.0-py3-none-any.whl
| Download URL | storageops-0.8.0-py3-none-any.whl |
|---|---|
| Size | 3.7 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b9389ec49073821700440f0e39c9d6b22af28b4fa4cc3803cd10bf33722aecdb
|
|
BLAKE2b-256 checksum How to use checksums |
f7d0efff9186deb62118edd272413b938b3a087222fedf9dca0d23af4778edc8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 30, 2026.
Transparency logSecurity for storageops 0.8.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for storageops-0.8.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 30, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
