> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyberwave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker registry

> Use the Cyberwave Docker Registry to pull and push custom drivers and AI models and re-use them across your robots and automations

## Overview

<Note>
  The Docker Registry is available on **Cyberwave Enterprise** plans. Contact us at [info@cyberwave.com](mailto:info@cyberwave.com) to enable it for your organization.
</Note>

Cyberwave hosts a private Docker registry at `registry.cyberwave.com`. You use it to store and distribute the container images that run on your robots and cloud nodes — drivers, ML models, custom ROS packages, and anything else your edge devices need.

Authentication uses the same `CYBERWAVE_API_KEY` you already use for the REST API and MQTT. Your workspace role determines what you can do:

| Workspace role | Registry access |
| - | - |
| READER | Pull images |
| WRITER | Pull and push images |
| ADMIN | Pull, push, and delete images |
| OWNER | Full access |

<Info>
  There are no separate registry passwords. The same API key and workspace membership that govern REST and MQTT access also govern registry access.
</Info>

***

## Setup

<Steps>
  <Step title="Install the Cyberwave CLI">
    If you haven't already, install the CLI. It includes the Docker credential helper.

    ```bash theme={null}
    pip install cyberwave-cli
    ```
  </Step>

  <Step title="Set your API key">
    Use the same environment variable the SDK and CLI already read:

    ```bash theme={null}
    export CYBERWAVE_API_KEY="cw_your_token_here"
    ```
  </Step>

  <Step title="Log in to the registry">
    Authenticate Docker against `registry.cyberwave.com` before pulling private images or pushing.
  </Step>
</Steps>

<Accordion title="Alternative: manual docker login">
  If you prefer not to install the credential helper, you can log in explicitly:

  ```bash theme={null}
  echo "$CYBERWAVE_API_KEY" | docker login registry.cyberwave.com \
    -u you@example.com --password-stdin
  ```

  `docker login <server>` targets that specific registry, not Docker Hub. Credentials are cached locally until they expire or you run `docker logout registry.cyberwave.com`.
</Accordion>

***

## Pulling images

### Public images

Public images (e.g. Cyberwave-maintained drivers) require no authentication:

```bash theme={null}
docker pull registry.cyberwave.com/public-drivers/ugv-driver:v1.2.3
```

For production, pin by digest instead of tag:

```bash theme={null}
docker pull registry.cyberwave.com/public-drivers/ugv-driver@sha256:<digest>
```

### Private images

Private images require authentication. Your workspace role must grant at least READER access:

```bash theme={null}
docker pull registry.cyberwave.com/my-workspace/navigation-driver:v2.0.0
```

If you have access, the pull succeeds. If not, it fails with `403` — the same behavior as trying to access a REST endpoint or MQTT topic without the right role.

***

## Pushing images

To push, your workspace role must grant at least WRITER access.

<Steps>
  <Step title="Build your image">
    Tag it with the full registry path. The path includes your workspace or project namespace:

    ```bash theme={null}
    docker build -t registry.cyberwave.com/my-workspace/my-driver:v0.1.0 .
    ```
  </Step>

  <Step title="Push">
    ```bash theme={null}
    docker push registry.cyberwave.com/my-workspace/my-driver:v0.1.0
    ```

    If the credential helper is configured, no separate login step is needed. The Cyberwave Token Service validates your API key, checks your workspace role, and authorizes the push.
  </Step>
</Steps>

<Warning>
  Version tags (e.g. `v1.2.3`) are immutable — once pushed, they cannot be overwritten. Use mutable tags like `dev` or `latest` during development.
</Warning>

***

## Using registry images on edge devices

Reference registry images in your `cyberwave.yml` driver configuration:

```yaml theme={null}
driver:
  docker_image: registry.cyberwave.com/public-drivers/ugv-driver:v1.2.3
```

Edge Core pulls the image automatically when the twin connects. If the image is private, the edge device authenticates using the API key configured during device setup.

***

## Tagging conventions

| Tag pattern | Meaning | Mutable? |
| - | - | - |
| `v1.2.3` | Release version | No (immutable) |
| `latest` | Most recent release | Yes |
| `dev` | Development build | Yes |
| `<branch>-<sha>` | CI build | Yes |

***

## CI/CD integration

In GitHub Actions or other CI systems, authenticate using a Cyberwave service API key:

```yaml theme={null}
- name: Login to Cyberwave registry
  run: |
    echo "${{ secrets.CYBERWAVE_CI_API_KEY }}" | docker login registry.cyberwave.com \
      -u ci@cyberwave.com --password-stdin

- name: Build and push
  run: |
    docker build -t registry.cyberwave.com/my-workspace/my-driver:${{ github.sha }} .
    docker push registry.cyberwave.com/my-workspace/my-driver:${{ github.sha }}
```

The CI API key is a normal Cyberwave API key whose workspace membership grants WRITER access to the target project.

***

## Architecture

The registry uses [Harbor](https://goharbor.io/) with a Cyberwave-managed token service. When Docker needs to authenticate, the flow is:

```mermaid theme={null}
sequenceDiagram
    participant D as Docker Client
    participant H as Harbor (registry.cyberwave.com)
    participant T as Cyberwave Token Service

    D->>H: 1. docker pull / push
    H-->>D: 2. 401 + token endpoint URL
    D->>T: 3. Request token with CYBERWAVE_API_KEY
    T->>T: 4. Validate key & resolve workspace role
    T-->>D: 5. Scoped JWT (pull, push, delete)
    D->>H: 6. Retry with JWT
    H-->>D: 7. Serve the request
```

The token service is a standard Docker Registry v2 token endpoint backed by the Cyberwave auth and ACL system. Harbor handles image storage, vulnerability scanning, replication, and retention policies.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.