oci2i - OCI Registry TUI Browser

A terminal user interface (TUI) browser for OCI/Docker registries with support for multiple registry contexts, dynamic authentication, and a rich interactive experience.

Features

• 🌳 Tree-based repository navigation with namespace grouping
• 🏷️ Tag browsing with debounced loading and caching
• 📋 Manifest inspection with detailed metadata
• 📝 Request/response logging for debugging
• ⚡ Fast and responsive with skeleton loading animations
• 🔐 Flexible authentication: Basic auth, command-based tokens (AWS ECR, etc.)
• 🎯 Multiple registry contexts like kubectl contexts
• 💾 Smart caching to avoid redundant API calls

Installation

Prerequisites

• Rust 1.70+ (for building from source)
• Access to an OCI registry (Docker Hub, AWS ECR, local registry, etc.)

Build from Source

git clone <repository-url>
cd oci2i
cargo build --release

The binary will be available at ./target/release/oci2i

Optionally, install it system-wide:

cargo install --path .

Configuration

Creating the Config File

oci2i uses a YAML configuration file to manage registry contexts. The config file should be created at one of these locations (checked in order):

1. ~/.oci2i/config.yaml (recommended)
2. ./oci2i-config.yaml (current directory)

Create the directory and file:

mkdir -p ~/.oci2i
touch ~/.oci2i/config.yaml

Config File Format

current-context: <context-name>
contexts:
  - name: <context-name>
    registry:
      url: <registry-url>
      auth:
        type: <auth-type>
        # Additional auth fields based on type

Configuration Examples

Local Registry (No Authentication)

current-context: local
contexts:
  - name: local
    registry:
      url: http://localhost:5001
      auth:
        type: none

Docker Hub (Basic Authentication)

current-context: dockerhub
contexts:
  - name: dockerhub
    registry:
      url: https://registry-1.docker.io
      auth:
        type: basic
        username: your-dockerhub-username
        password: your-dockerhub-password

AWS ECR (Command-based Authentication)

current-context: ecr
contexts:
  - name: ecr
    registry:
      url: https://123456789012.dkr.ecr.us-east-1.amazonaws.com
      auth:
        type: command
        command:
          - aws
          - ecr
          - get-login-password
          - --region
          - us-east-1
        username: AWS

AWS ECR with Profile (Command with Environment Variables)

current-context: ecr-staging
contexts:
  - name: ecr-staging
    registry:
      url: https://339712957910.dkr.ecr.us-east-1.amazonaws.com
      auth:
        type: command
        command:
          - aws
          - ecr
          - get-login-password
          - --region
          - us-east-1
        username: AWS
        env:
          - name: AWS_PROFILE
            value: staging-profile

Custom Registry with Token Command

current-context: custom
contexts:
  - name: custom
    registry:
      url: https://registry.example.com
      auth:
        type: command
        command:
          - sh
          - -c
          - echo $MY_TOKEN
        username: myuser
        env:
          - name: MY_TOKEN
            value: secret-token-here

Complete Multi-Context Configuration

current-context: local
contexts:
  - name: local
    registry:
      url: http://localhost:5001
      auth:
        type: none

  - name: dockerhub
    registry:
      url: https://registry-1.docker.io
      auth:
        type: basic
        username: your-dockerhub-username
        password: your-dockerhub-password

  - name: ecr-prod
    registry:
      url: https://123456789012.dkr.ecr.us-east-1.amazonaws.com
      auth:
        type: command
        command:
          - aws
          - ecr
          - get-login-password
          - --region
          - us-east-1
        username: AWS

  - name: ecr-staging
    registry:
      url: https://339712957910.dkr.ecr.us-east-1.amazonaws.com
      auth:
        type: command
        command:
          - aws
          - ecr
          - get-login-password
          - --region
          - us-east-1
        username: AWS
        env:
          - name: AWS_PROFILE
            value: staging-profile

Usage

Starting the Application

Simply run:

oci2i

The application will:

1. Load the config from ~/.oci2i/config.yaml or ./oci2i-config.yaml
2. Use the context specified by current-context
3. Show the UI immediately with skeleton loading
4. Execute authentication commands in the background
5. Load and display repositories

CLI Commands

Switch between registry contexts:

oci2i use-context <context-name>

View current configuration:

oci2i config-view

List all available contexts:

oci2i get-contexts

Keyboard Controls

Global Keys

• q: Quit the application
• 1: Focus Repositories panel
• 2: Focus Tags panel
• 3: Focus Details panel
• 4: Focus Logs panel

Navigation

• Enter: Move forward (Repos → Tags → Details)
• Esc: Move backward (Details → Tags → Repos)
• Arrow Keys: Navigate within panels

Panel-Specific Controls

Repositories Panel:

• ↑/↓: Navigate through repos/namespaces
• ←/→: Collapse/expand namespaces
• Enter:
  • On namespace: Toggle expand/collapse
  • On repository: Jump to Tags panel
• r: Refresh repository list

Tags Panel:

• ↑/↓: Navigate through tags
• Enter: Jump to Details panel
• r: Refresh tags for current repository

Details Panel:

• ↑/↓: Scroll through manifest content

Logs Panel:

• [: Previous tab (Log ← Context)
• ]: Next tab (Log → Context)
• f: Toggle fullscreen mode
• ↑/↓: Scroll through logs
• Esc: Exit fullscreen

How It Works

Debounced Loading

oci2i implements smart debounced loading:

• When navigating quickly through repos/tags, it waits 200ms before fetching data
• If you move to another item before 200ms, the timer resets
• Loading continues in the background even if you move away
• Results are cached so revisiting is instant

Caching Strategy

• Repository list: Fetched once, can be refreshed with 'r'
• Tags: Cached per repository, instantly available on revisit
• Manifests: Cached per repo:tag combination

Authentication

The command auth type executes arbitrary commands to obtain authentication tokens:

1. The command is executed with the specified environment variables
2. The command's stdout is used as the password/token
3. Authentication is performed asynchronously in the background
4. Useful for cloud providers like AWS ECR, GCP GCR, Azure ACR

Testing with Local Registry

Start a local Docker registry:

docker run -d -p 5001:5000 --name registry registry:2

Push some test images:

# Pull test images
docker pull alpine:latest
docker pull nginx:alpine

# Tag for local registry
docker tag alpine:latest localhost:5001/alpine:latest
docker tag nginx:alpine localhost:5001/myapp/nginx:stable

# Push to local registry
docker push localhost:5001/alpine:latest
docker push localhost:5001/myapp/nginx:stable

Update your config to use the local registry:

current-context: local
contexts:
  - name: local
    registry:
      url: http://localhost:5001
      auth:
        type: none

Run oci2i:

oci2i

Troubleshooting

Authentication Errors

If you see authentication errors:

1. Check your credentials in the config file
2. For command-based auth, verify the command works standalone:

   aws ecr get-login-password --region us-east-1

3. Check the Logs panel (press '4') for detailed error messages

Connection Issues

• Verify the registry URL is correct and accessible
• Check if the registry requires HTTPS
• For local registries, ensure Docker is running
• Check firewall/network settings

Port Conflicts on macOS

Port 5000 is reserved for AirPlay/AirTunes on macOS. Use port 5001 or higher for local registries.

Project Structure

oci2i/
├── src/
│   ├── main.rs           # Main application loop and UI rendering
│   ├── state.rs          # Application state management
│   ├── backend.rs        # Async backend for API calls
│   ├── oci_client.rs     # OCI Registry API client
│   ├── config.rs         # Configuration management
│   └── ui/
│       ├── mod.rs        # UI module exports
│       ├── panel.rs      # Panel widget
│       └── tree.rs       # Tree widget (custom)
├── Cargo.toml
└── README.md

License

[Add your license here]

Contributing

[Add contribution guidelines here]