gpfsagent/README.md

gpfs-agent

Agentic chat front-end for the IBM Storage Scale (GPFS) REST API v3, driven by Claude with tool-use. Read-only by default; writes and destructive operations are gated behind explicit env flags. Ships with both a terminal REPL and a pure-Python web UI (Streamlit). Runs natively or in Docker.

Quick start

1. Configure

cp .env.example .env
# edit .env: ANTHROPIC_API_KEY, GPFS_API_BASE, GPFS_USERNAME, GPFS_PASSWORD

2a. Docker (recommended for Linux)

docker compose up -d --build
# open http://<host>:8501

Stop / view / update:

docker compose logs -f
docker compose pull && docker compose up -d
docker compose down

Override the host port with HOST_PORT=9000 docker compose up -d. If your GPFS GUI uses a private CA, drop the cert into ./certs/ca.pem and uncomment the volume + GPFS_CA_BUNDLE lines in docker-compose.yml.

2b. Native Linux (no Docker)

./run.sh          # web UI on 0.0.0.0:8501
./run.sh cli      # terminal REPL
HOST=127.0.0.1 PORT=8080 ./run.sh   # bind override

run.sh creates a .venv on first run and installs dependencies.

2c. Windows (PowerShell)

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
streamlit run gpfs_agent\web.py        # web UI
python -m gpfs_agent                   # REPL

Web UI

The Streamlit app lives at / on the configured port. It shows:

• A chat panel (uses Claude with tool-use against the GPFS REST API)
• A sidebar with model, API base, mode, the live system prompt, and a tool-call log (last 25 calls with status, reason and payload)
• A "Reset conversation" button
• When GPFS_ALLOW_WRITES=true: a session-scoped "Auto-approve mutations" checkbox. Mutating calls are denied unless this is on.

REPL commands: /reset, /system, /quit.

How the guardrails work

Everything is configured in .env:

Variable	Effect
GPFS_ALLOW_WRITES	When false (default) the model is given a tool that only accepts GET.
GPFS_ALLOW_DESTRUCTIVE	When false (default) DELETE is stripped even if writes are on.
GPFS_CONFIRM_MUTATIONS	When true (default) every POST/PUT/DELETE is gated by a confirm step.
GPFS_PATH_ALLOW / _DENY	Optional regexes applied to the request path.
GPFS_INSTRUCTIONS	Free-text instructions appended to the system prompt.
GPFS_INSTRUCTIONS_FILE	Path to a file with longer instructions; merged with GPFS_INSTRUCTIONS.

Guardrails are enforced in three layers:

1. Tool schema — the method enum given to the model is built from cfg.allowed_methods, so it cannot ask for DELETE when disabled.
2. Dispatcher — tools.py re-checks method and allow/deny regex and triggers the confirm hook before any mutating HTTP call.
3. System prompt — agent.py injects natural-language guardrails plus a curated v3 endpoint reference (see endpoints.py) so the agent has accurate context without having to guess.

Project layout

gpfs_agent/
├── __init__.py
├── __main__.py        # python -m gpfs_agent  (REPL)
├── agent.py           # Anthropic tool-use loop
├── cli.py             # Rich REPL
├── config.py          # .env loading & validation
├── endpoints.py       # curated /scalemgmt/v3 reference (in-context)
├── gpfs_client.py     # httpx wrapper around the GPFS REST API
├── tools.py           # Tool schemas + guarded dispatcher
└── web.py             # Streamlit chat app
Dockerfile             # python:3.12-slim + streamlit
docker-compose.yml     # one-command deploy
run.sh                 # bash helper for native Linux

Notes on the GPFS REST API

• GPFS_API_BASE should include the version prefix, e.g. https://gui:46443/scalemgmt/v3. v3 is the current native REST API on Storage Scale 5.2.x / 6.0.x; the typical port is 443 (CNSA / container deploys) or 46443 (native install).
• Auth is HTTP Basic against a Storage Scale GUI user. Use an account scoped to the operations you intend to allow.
• For self-signed lab gear, set GPFS_VERIFY_TLS=false or point GPFS_CA_BUNDLE at a PEM file (mount as a volume when running in Docker).
• The interactive Swagger UI lives at https://<gui>/openapi/ — useful for discovering endpoints your specific release ships.