ovstorage-user-getting-started
Use when starting a new ovstorage session or recovering from NoRoute, NotConfigured, or Unsupported errors by inspecting configured backends and routes.
SKILL.mdovstorage/skills/ovstorage-user-getting-started/SKILL.md
GitHubGetting Started: Discover What's Configured
Goal: Find out what ovstorage knows about — versions, declared backend layers, configured connections, addressable prefixes — before attempting any real work.
When to use this: As the first call in any new session, or when an
operation has failed with NoRoute / NotConfigured / Unsupported
and you need to understand what's actually available. NoRoute means
no backend serves this address and no anonymous fallback is granted for
its scheme.
Recipe
Call ovstorage_doctor with no arguments.
{
"tool": "ovstorage_doctor",
"arguments": {}
}
What success looks like
The envelope's result field is a DoctorReport:
{
"v": "0.1",
"ok": true,
"operation": "ovstorage_doctor",
"result": {
"ovstorage_version": "0.1.0",
"backend_kinds": [
{"kind": "file", "display_name": "Local files", "supports_runtime_add": true},
{"kind": "s3", "display_name": "Amazon S3", "supports_runtime_add": true}
],
"connections": [
{
"id": "01H...",
"backend_kind": "s3",
"display_name": "my-bucket",
"addresses": ["s3://my-bucket/"],
"auth_state_kind": "Authenticated"
}
],
"address_roots": [
{"address": "s3://my-bucket/", "backend_kind": "s3", "display_name": null, "visibility": "Visible", "connection_id": "01H...", "user_metadata": {}}
],
"aliases": []
}
}
How to read the report
backend_kinds— the backend layers this stack was built with, not a catalogue of what the library could construct. A stack whose config declares one layer reports one kind, and a stack with no layers reports none, however much the library is capable of. A missing kind means the config does not declare a layer for it: fix the config first. Thefilebackend is built into the library and needs no plugin artifact — it still appears here only once afilelayer is declared. Every other kind additionally needs its plugin loaded.connections— backends the user has configured.AuthenticatedandAnonymousconnections are ready to use;AwaitingAuth,AuthFailed, or other non-ready states mean operations against that connection's addresses need credentials or configuration work first.address_roots— the URL prefixes that resolve. If you're about to operate on an address, confirm a prefix here matches it. A root spelled as a bare scheme —s3:///,gs:///orazure:///— with"visibility": "Hidden","connection_id": nulland"user_metadata": {"org.omniverse.ovstorage/scheme-fallback": "anonymous"}is the sign this host grants an anonymous fallback for that scheme: a public address on it that no connection serves is still readable, anonymously and read-only, while an unrouted address on any other scheme answersNoRoute. A hostless root without that marker is an ordinary root, not a fallback.aliases— convenience name remappings; safe to ignore unless you're working with the alias surface specifically.
When things go wrong
This call is essentially read-only library state — it doesn't usually fail. If you get an envelope with ok: false, the failure is in the MCP server itself (e.g., server can't start, plugin loading panicked at boot). The error message should explain.
See also
- ovstorage-user-handle-errors — what to do when other tools error with
NoRoute/NotConfigured; before concluding ans3://address is unroutable, checkaddress_rootsabove for a hiddens3:///fallback root docs/public/agent/mcp-tools.md— fullDoctorReportshape