Installation

    There are two ways to use OpenEye:

    • Hosted API — send images to https://openeye.sh/v1 with an API key. Nothing to install. See "Path B: Hosted API" in the Quickstart and the Hosted API section.
    • Self-hosted CLI — install openeye-sh and run models on your own machine, free. The rest of this page covers that.

    Requirements

    • Python 3.12 or later
    • pipx (recommended): https://pipx.pypa.io/

    Install from PyPI

    pipx install openeye-sh

    This installs two commands: openeye (the CLI) and openeye-mcp (an MCP server over stdio; needs the mcp extra).

    Optional Dependencies

    Install extras for specific model backends. Quote the brackets in zsh and fish.

    # YOLO object detection (yolov8, yolo26)
pipx install "openeye-sh[yolo]"

# Depth estimation (depth-anything)
pipx install "openeye-sh[depth]"

# Grounding DINO (open-vocabulary detection)
pipx install "openeye-sh[grounding]"

# YOLO + depth + grounding + VLM client + OpenCV
pipx install "openeye-sh[all]"

# Camera support (OpenCV)
pipx install "openeye-sh[camera]"

# MCP server for agents (openeye-mcp)
pipx install "openeye-sh[mcp]"
    ExtraAdds
    yoloUltralytics (yolov8, yolo26)
    depthTransformers + torch (Depth Anything V2)
    groundingTransformers + torch (Grounding DINO)
    samSAM 2
    rfdetrRF-DETR
    smolvlaLeRobot (SmolVLA)
    onnx, onnx-gpuONNX Runtime (CPU or GPU)
    tensorrtTensorRT + ONNX Runtime GPU
    vlmOpenAI-compatible client for VLM providers
    cloudboto3 + google-cloud-storage (s3:// and gs:// datasets)
    cameraOpenCV
    mcpMCP server (openeye-mcp)
    allyolo, depth, grounding, vlm, and OpenCV

    To add an extra to an existing pipx install, reinstall with --force:

    pipx install "openeye-sh[depth]" --force

    Platform Notes

    • macOS — MPS (Apple Silicon GPU) is supported for YOLO and Depth Anything
    • Linux — CUDA is supported when torch is installed with CUDA
    • CPU — All models work on CPU (slower)

    Verify Installation

    openeye --version
openeye list

    openeye docs prints the full command reference; openeye docs --json gives a machine-readable version for agents.

    Development Install

    git clone https://github.com/aw3-technology/openeye.sh.git
cd openeye.sh/cli
pip install -e ".[all]" --group dev
    Quickstart →