Custom Adapter Development#

A custom adapter is a service that implements the Omniverse Storage API specification on top of your own storage backend. It lets any Omniverse client (Kit, CLI, custom agents) treat your storage system as a first-class Omniverse storage provider, without changes to the clients themselves.

This page walks you through what the NGC resource package contains, how to use the Python reference implementation as a starting point, how to validate your adapter with the conformance test suite, and where to find the API specifications if you want to build in another language.

—

What is in the Storage API Resource Packages#

We will use the Storage API resource package as the starting example.

Download the Storage API resource from NGC before starting:

ngc registry resource download-version "nvidia/omniverse/storage-api:1.0.0-beta.4"

After extraction, the package contains:

Directory / File

Contents

filesystem_example/

Full Python reference implementation of the Storage API backed by the local filesystem. Use this as your starting template.

conformance_tests/

Gherkin BDD conformance test suite. Run it against any Storage API implementation to verify specification adherence.

proto/

gRPC .proto files for the Storage API. Use these to generate language bindings in any gRPC-supported language.

openapi/

OpenAPI specifications for the REST interface.

docs/

Rendered HTML documentation for the API, including the conformance test reference.

The filesystem example and conformance tests are the two most important starting points. Start with the example to understand the shape of a compliant implementation, then use the conformance tests to verify your own adapter.

** Other Resource Packages **

Each resource package contains the API specs (proto and openapi) and docs.

—

Step 1: Explore the Reference Implementation#

The filesystem_example/ directory is a fully-working Python implementation of the Storage API that stores files on the local filesystem. It is the same service used throughout the local and minimal deployment guides.

Install and run it to see what a compliant adapter looks like end-to-end:

cd filesystem_example
poetry install
python -m local_filesystem_service filesystem --static-dir /tmp/adapter-dev

With the service running, open the interactive API explorer at http://localhost:8011/docs to browse every endpoint and try requests directly in the browser.

Key source files to read before writing your own adapter:

File

What it shows

local_filesystem_service/rest_service.py

How REST routes map to backend operations

local_filesystem_service/grpc_service.py

How gRPC method handlers map to the same backend operations

local_filesystem_service/filesystem_backend.py

The actual storage backend – the part you replace with your own

local_filesystem_service/__main__.py

Entry point and CLI structure

The pattern is the same for any backend: the REST and gRPC layers are thin adapters that translate requests into calls to a backend class. You implement the backend class; the service wiring stays the same.

—

Step 2: Implement Your Backend#

Generate gRPC language bindings from the proto files if you are not using Python:

# Example: generate Python bindings
python -m grpc_tools.protoc \
    -I proto \
    --python_out=. \
    --grpc_python_out=. \
    proto/storage_api.proto

For other languages, use the standard protoc toolchain with the appropriate plugin (protoc-gen-go, protoc-gen-rust, etc.) against the same .proto files.

Your adapter must implement both the REST and gRPC interfaces defined in the specifications. At minimum, implement the core file object operations:

  • PUT /v1beta/fileobject/by-address/{address} – write a file

  • GET /v1beta/fileobject/by-address/{address} – read a file

  • DELETE /v1beta/fileobject/by-address/{address} – delete a file

  • GET /v1alpha/filefolder/list/{address} – list a folder

  • GET /v1beta/capabilities/services – advertise supported capabilities

The OpenAPI spec in openapi/ and the gRPC .proto files in proto/ are the authoritative contract. Any endpoint not listed in GET /v1beta/capabilities/services can be omitted in early iterations.

—

Step 3: Validate with the Conformance Test Suite#

The conformance_tests/ directory contains a Gherkin BDD suite that tests any Storage API implementation for specification compliance. Run it against your adapter before shipping.

Install and run the suite against a locally running adapter:

cd conformance_tests
python -m venv .poetry_venv
.poetry_venv/bin/pip install poetry
.poetry_venv/bin/poetry install
source .venv/bin/activate

# Optional: override defaults when your adapter does not use local defaults
export TEST_STORAGE_API_REST_ENDPOINT=http://localhost:8011
export TEST_STORAGE_API_GRPC_ENDPOINT=localhost:50051
export TEST_STORAGE_API_RESOURCE_BASE=file-storage://your-adapter

run-conformance-tests

A passing run means your adapter behaves the way generic Omniverse clients expect. The suite covers:

  • File object read/write/delete

  • Folder listing

  • Capability advertisement

  • Error response shapes

  • OpenAPI schema conformance (optional, enabled separately)

To run only a subset of tests during development:

run-conformance-tests -k "stat" -vv

See conformance_tests/README.md in the package for the full list of environment variables and advanced configuration options (custom test data generators, boto3 backend fixtures, schema validation).

—

Step 4: Package and Deploy Your Adapter#

Once the conformance tests pass, containerize and deploy your adapter the same way the filesystem example is deployed. See Containerize the Storage service adapter for the Docker packaging steps and Deploy Storage to MicroK8s for the Kubernetes deployment pattern.

For production deployments, register your adapter with the Discovery Service so Omniverse clients can locate it automatically. See Discovery Service Configuration for Discovery registration details.

Note

These same steps can be follow for the other API specifications as well, and are documented for each API we have released, listed below.

—

API Specifications#

All three API families are available from NGC for building adapters or integrating clients:

Storage API#

Documentation:#

See the Storage API documentation.

Download:#

You can download the Storage API specifications from the NGC registry.

Notifications APIs#

Documentation:#

See the Notifications API documentation.

Download:#

You can download the Notifications Consumer API specifications and the Notifications Aggregation API specifications from the NGC registry.

Permissions API#

Documentation:#

See the Permissions API documentation.

Download:#

You can download the Permissions API specifications from the NGC registry.