ExoAtlas: Catalog Discovery and Data Browser

1. Defining ExoAtlas

ExoAtlas is ExoHub’s catalog discovery and data browsing interface. It lets teams search, browse, and download artifacts from a multi-tenant ArtifactDB catalog instance through a rich interactive experience available in two modes:

• Terminal (TUI): Run exo atlas from the CLI for a full interactive terminal experience with keyboard navigation, search, and inline downloads
• Web browser: The same experience accessible from any web browser, with no CLI installation required

Both modes share the same codebase and provide identical functionality – search, filtering, document viewing, and file downloads. The web mode makes catalog discovery accessible to data consumers, collaborators, and stakeholders who may not have the exo CLI installed.

Key Capabilities

• Full-text search across the ArtifactDB catalog with interactive result navigation
• Document browsing with metadata inspection and markdown rendering
• File downloads – in TUI mode files download to the local filesystem; in web mode downloads go directly from S3 to the browser via presigned URLs
• Deep linking – share direct links to specific artifacts via URL parameters (e.g., https://exohub.example.com/atlas/?doc=mnist:bundle.json@v0.1.0)
• Shareable links – press y to copy a document link to the clipboard

2. Role in the ExoHub Architecture

ExoAtlas serves as the discovery and access layer for ExoHub’s catalog infrastructure, bridging the gap between data producers who publish datasets and data consumers who need to find and retrieve them.

Two Access Modes, One Experience

ExoAtlas is designed so that the same interactive experience is available regardless of how you access it:

Integration with ExoHub Components

ExoAtlas operates in coordination with other ExoHub components:

ExoCLI Foundation: ExoAtlas is built into ExoCLI as the exo atlas command. The web mode runs the same TUI binary, ensuring feature parity between terminal and browser interfaces.

ExoGit Metadata: ExoAtlas queries the catalog built from ExoGit data repositories, displaying bundle and artifact metadata generated by exo bundle.

Authentication: ExoAtlas uses the same device-flow OAuth as ExoCLI , with server-side token management and automatic refresh in web mode.

3. Technical Implementation

TUI Mode

The terminal interface is built with BubbleTea and runs directly in the user’s terminal:

# Browse the catalog
exo atlas

# Open a specific document
exo atlas "myproject:file.txt@v1"

# Use a specific catalog
exo atlas --url https://charon.example.com/v1/mydb

The catalog URL is resolved from: --url flag, then EXOHUB_CATALOG_URL env var, then catalog_url in the active exo context.

Web Mode

The web mode runs as an HTTP server (exo serve) that bridges browsers to the TUI through a PTY-WebSocket architecture:

1. Browser connects via WebSocket to the ExoAtlas server
2. Server spawns exo atlas in a PTY (pseudo-terminal) for each session
3. Terminal I/O is streamed bidirectionally: keystrokes from browser to PTY, screen output from PTY to browser
4. xterm.js renders the terminal output in the browser with full keyboard and mouse support

This architecture means there is no separate web frontend to maintain – improvements to the TUI are immediately available in the browser.

Authentication

In web mode, authentication is handled server-side:

• Users authenticate via device-flow OAuth displayed in the browser
• JWT tokens are managed in memory and injected into spawned processes via EXO_TOKEN
• Token refresh happens automatically without user interaction
• Sessions expire after an idle timeout (default 8 hours)

Browser-Side Downloads

File downloads in web mode bypass the server entirely:

• The TUI signals download requests through OSC escape sequences over the PTY
• The server intercepts these and generates presigned S3 URLs
• URLs are sent to the browser via WebSocket control messages
• The browser downloads files directly from S3

Deployment

ExoAtlas web mode is designed for container deployment:

# Run locally
exo serve --addr :8080 --url https://charon.example.com/v1/mydb

# Behind a reverse proxy at /atlas
exo serve --addr :8080 --base-path /atlas

The Docker image bundles the exo binary with xterm.js assets and can be deployed as a standalone service or behind a reverse proxy.