Skip to main content

hop3-tui

Terminal User Interface for Hop3 PaaS.

Overview

A modern, keyboard-driven terminal interface for managing Hop3 applications, built with turbodesk.

Features

  • Dashboard overview: System stats, app summary, recent activity
  • Application management: List, filter, start/stop/restart apps
  • Environment variables: View, add, edit, delete with sensitive value hiding
  • Live log polling: Filter logs, pause/resume, auto-scroll
  • Chat interface: Interactive command line with tab completion
  • System monitoring: CPU, memory, disk usage and service status
  • Addon management: Create, attach, detach PostgreSQL, Redis, MySQL
  • Backup management: Create, restore, delete app backups
  • Connection status indicator: Visual feedback for server connectivity

Installation

pip install hop3-tui

Quick Start

# Set your server URL
export HOP3_SERVER_URL="https://hop3.example.com"
export HOP3_TOKEN="your-api-token"

# Run the TUI
hop3-tui

Configuration

Configuration via environment variables or ~/.config/hop3/tui.toml:

Variable Description Default
HOP3_SERVER_URL Server URL http://localhost:5000
HOP3_TOKEN API authentication token -
HOP3_TUI_THEME Color theme (dark/light) dark

Config File

[server]
url = "https://hop3.example.com"
token = "your-api-token"

[display]
theme = "dark"
refresh_interval = 5

Keyboard Shortcuts

Global

Key Action
d Dashboard
a Apps list
s System status
o Addons
b Backups
c Chat interface
? Help
q Quit

Navigation

Key Action
j/Down Move down
k/Up Move up
Enter Select
Escape Go back
/ Filter
R Refresh

Apps

Key Action
s Start app
S Stop app
r Restart app
l View logs
e Environment variables

Architecture

hop3-tui/
├── src/hop3_tui/
│   ├── __main__.py       # Entry point
│   ├── app.py            # Main Hop3TUI class with connection state
│   ├── config.py         # Configuration loading (env vars + TOML)
│   ├── api/
│   │   ├── client.py     # JSON-RPC client with error handling
│   │   └── models.py     # Pydantic data models
│   ├── screens/          # One `render(ui, hop3, size, ...) -> View` per screen
│   │   ├── _common.py    # bind(), halves(), rows(), fill() — what CSS used to do
│   │   ├── _logview.py   # The pane behind both logs.py and system_logs.py
│   │   ├── dashboard.py  # Overview with app counts
│   │   ├── apps.py       # App list and management
│   │   ├── app_detail.py # Single app view
│   │   ├── logs.py       # Live log polling
│   │   ├── env_vars.py   # Environment variable editor
│   │   ├── system.py     # System status
│   │   ├── addons.py     # Addon management
│   │   ├── backups.py    # Backup management
│   │   ├── processes.py  # Running processes
│   │   ├── system_logs.py# System-wide logs
│   │   └── chat.py       # Command interface
│   └── widgets/
│       ├── chrome.py        # Header, footer, panel frames
│       ├── status_panel.py  # Resource meters
│       ├── status_badge.py  # Status indicators
│       └── util.py          # Bar gauges, and the "not reported" marker
└── tests/                # pytest test suite (235 tests)

Immediate mode

There is no widget tree. The app is a function (UI) -> View that turbodesk re-runs whenever a frame is marked dirty, and a screen is a function of its arguments — so there is no compose(), no reactive/watch_*, no query_one, and no stylesheet. Layout is arithmetic (halves, rows), and state lives in ui.state hooks matched between frames by call order. Each screen renders inside its own ui.scope, which is what keeps those slots from being handed to the next screen on a switch.

Rendering has no side effect on the screen, so a test calls the app function at any size and asserts on what came out — no pilot, no event loop, no async harness:

to_text(render(app(hop3), size=Size(90, 26)))

Nothing is invented

A panel shows what the server reported or says that it does not know (not reported by the server); it never shows a plausible-looking constant. The log pane's heading drops from LIVE to UNREACHABLE when a poll fails, rather than going on looking live over a dead connection. tests/test_no_fabricated_data.py holds that line.

Connection Handling

The TUI tracks connection state to the Hop3 server:

  • Connected (green indicator): Server is reachable
  • Disconnected (red indicator): Connection lost, will retry
  • Connecting (yellow indicator): Attempting to connect

Connection failures are tracked and the state updates automatically. The UI continues to show cached data while disconnected.

Development

# Run it
uv run hop3-tui

# Run tests (from the workspace root)
uv run pytest packages/hop3-tui/tests

# Lint and format
uv run ruff check src/
uv run ruff format src/

Documentation

  • hop3-server - The server that hop3-tui communicates with
  • hop3-cli - Alternative command-line interface

License

Apache-2.0 - Copyright (c) 2024-2026, Abilian SAS

Metadata

Release files for hop3-tui 0.8.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hop3-tui 0.8.2
File Size Uploaded Provenance Actions
hop3_tui-0.8.2.tar.gz 32.8 kB Without provenance Details for hop3_tui-0.8.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hop3-tui 0.8.2
File Interpreter ABI Platform Actions
hop3_tui-0.8.2-py3-none-any.whl Python 3 none any Details for hop3_tui-0.8.2-py3-none-any.whl

Total release size: 83.1 kB

Release files / hop3_tui-0.8.2.tar.gz

Download URL hop3_tui-0.8.2.tar.gz
Size 32.8 kB
Tags Source
SHA-256 checksum
How to use checksums
a1aa376e5d4a32aeef6380716e4e0fc8b76b756f110c571f25862c0cbd325b19
BLAKE2b-256 checksum
How to use checksums
f69a1b7988dfa9974682b7f8fbe87897ccbdffd5f8d0571bd24d627af43a5cee
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Release files / hop3_tui-0.8.2-py3-none-any.whl

Download URL hop3_tui-0.8.2-py3-none-any.whl
Size 50.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c648d6fdb54b5c85a287329c954099b8667d3c87271030987465bfd785aa2c29
BLAKE2b-256 checksum
How to use checksums
2fd9f18a3191ae84e382e1c104dfbc049dad3071ca025f7e9edf3e0df2527674
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Security for hop3-tui 0.8.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page