GRID Docs | General Robotics

The grid-cortex-client Python package provides a unified interface to all AI models hosted on GRID Cortex.

Installation

The client is already installed in every GRID session workspace and in the Python environment the GRID CLI prepares for skill run. No separate installation is needed. Start with the GRID installation guide.

If you previously installed the client from public PyPI, use a GRID session workspace or the CLI-managed Python environment for current versions. Existing public PyPI releases remain available as historical versions; no new releases are published there.

Authentication & Endpoint

Set up your API key (and endpoint, if needed):

During onboarding General Robotics will give you a personal CORTEX API key.
Export it so the client can pick it up automatically:
export GRID_CORTEX_API_KEY="<YOUR_KEY>"
If you run Cortex on-prem or on a managed cloud deployment, point the client at the Cortex API URL supplied with your deployment — the dedicated grid-… API hostname, not the admin-… portal hostname:
export GRID_CORTEX_BASE_URL="https://<your-cortex-api-host>/cortex"

You can also pass the key directly when constructing the client:

from grid_cortex_client import CortexClient
client = CortexClient(api_key="<YOUR_KEY>")

Quick Start (2 lines)

Get started with just two lines of code:

from grid_cortex_client import CortexClient
result = CortexClient().run(model_id="zoedepth", image_input="demo.jpg")

The result type depends on the model — see the individual model pages for details.

Unified API

Every model is called through the same function:

CortexClient.run(model_id: str, **kwargs) -> Any

model_id — the model identifier (e.g. "zoedepth", "gsam2", "pi05")
**kwargs — model-specific inputs (image_input, prompt, left_image, etc.)

from grid_cortex_client import CortexClient

client = CortexClient()
depth = client.run(model_id="zoedepth", image_input="scene.jpg")
mask  = client.run(model_id="gsam2", image_input="scene.jpg", prompt="a robot arm")

Discovery

List all available models and get per-model documentation at runtime:

from grid_cortex_client import CortexClient

client = CortexClient()

# List all deployed model IDs
print(client.available_models())
# ['da3metric', 'zoedepth', 'owlv2', 'gsam2', 'sam3', ...]

# Get detailed documentation for a specific model
print(client.help("sam3"))

You can also use the ModelType enum for IDE autocompletion:

from grid_cortex_client import CortexClient, ModelType

client = CortexClient()
depth = client.run(ModelType.ZOEDEPTH, image_input="demo.jpg")

Async & WebSocket Clients

AsyncCortexClient

For asyncio-based applications, use AsyncCortexClient — same API as CortexClient but with await:

from grid_cortex_client import AsyncCortexClient

async def main():
    client = AsyncCortexClient()
    depth = await client.run(model_id="zoedepth", image_input="demo.jpg")
    print(depth.shape)
    await client.close()

CortexHubClient (WebSocket)

For high-throughput pipelines, CortexHubClient provides a persistent WebSocket connection. It supports two patterns: Request-response (simple)

from grid_cortex_client import CortexHubClient, ModelType

async with CortexHubClient() as hub:
    depth = await hub.run(ModelType.ZOEDEPTH, image_input=img)

Pub/Sub (concurrent, non-blocking)

from grid_cortex_client import CortexHubClient, ModelType

async with CortexHubClient() as hub:
    await hub.publish(ModelType.ZOEDEPTH, request_id="depth1", image_input=img)
    await hub.publish(ModelType.GSAM2, request_id="mask1", image_input=img, prompt="cat")

    async for result in hub.subscribe():
        print(f"{result.request_id}: ok={result.ok}")
        process(result.data)

Each HubResult contains request_id, model, data, ok, and optional error.

Troubleshooting

401 Unauthorized – Check that your shell actually has GRID_CORTEX_API_KEY exported and that the key is correct. A key only works on the cluster it was created in. Anything the GRID CLI starts for you — including a robot workspace’s Python and notebooks — already has the active cluster’s key; a python you start yourself needs it exported. Timeout / connection errors – If you are on-prem/managed cloud, confirm GRID_CORTEX_BASE_URL points to your instance. You can also adjust the default 30 s timeout:

client = CortexClient(timeout=60)

Overview

Cortex Models

GRID Cortex Client

Installation

Authentication & Endpoint

Quick Start (2 lines)

Unified API

Discovery

Async & WebSocket Clients

AsyncCortexClient

CortexHubClient (WebSocket)

Troubleshooting

Installation

Authentication & Endpoint

Quick Start (2 lines)

​Unified API

​Discovery

​Async & WebSocket Clients

​AsyncCortexClient

​CortexHubClient (WebSocket)

​Troubleshooting

Unified API

Discovery

Async & WebSocket Clients

AsyncCortexClient

CortexHubClient (WebSocket)

Troubleshooting