Metadata-Version: 2.5
Name: runtop
Version: 0.1.0
Summary: A terminal workspace for containers and their machines
Project-URL: Homepage, https://github.com/bcivitcioglu/runtop
Project-URL: Issues, https://github.com/bcivitcioglu/runtop/issues
License-Expression: MIT
License-File: LICENSE
Keywords: containers,monitor,terminal,tui,workspace
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.11
Requires-Dist: httpx>=0.28.1
Requires-Dist: textual<9,>=8.2.8
Requires-Dist: typing-extensions>=4.4.0
Description-Content-Type: text/markdown

# runtop

A terminal workspace for containers and their machines.
MIT licensed for personal and commercial use.

![Full workspace](https://raw.githubusercontent.com/bcivitcioglu/runtop/master/assets/runtop/demo.gif)

Choose the **full edition** for a machines sidebar, grouped containers, an inspector,
project logs, archive recording, search, and mouse-driven workspace controls.
Choose **lite** for a compact screen, fast startup, and a small standalone executable.
Both editions work with existing local engines and read-only remote contexts.

## Install

Full edition, requiring Python 3.11 or later:

```sh
uv tool install 'runtop>=0.1.0'
runtop --demo
```

Lite edition:

```sh
cargo install --locked runtop
rt --demo
```

Prebuilt lite executables are attached to the repository’s releases. Extract the
archive, verify its checksum, and place `rt` and `runtop` on your executable path.

`rt` always opens lite. When both editions are installed in separate executable
locations on your path, `runtop` opens full. The lite launcher recognizes the full
entry point and hands over the original arguments. `rt` remains the direct route
to lite. `--version` and `--edition` identify the executable you are running.

## Full workspace

- Browse machines and containers grouped by project. `/` filters; `attention`
  finds unhealthy, restarting, dead, and failed containers.
- Inspect ports, mounts, networks, restart counts, memory failures, and health
  output. `1`, `2`, `3` select Info, Logs, and Stats; `i` opens narrow-mode details.
- Select a project and press `l` for combined logs. `s`, `x`, `R` start, stop, or
  restart the listed existing members after a preview. Filters limit membership.
- `D` opens storage accounting on demand. Shared layers, unknown usage, and
  machine capacity are presented separately.
- `ctrl+p` opens the command palette; `?` lists keys. Use the mouse to navigate,
  select tabs, and resize panes. `t` changes theme.

## Lite workspace

![Compact workspace](https://raw.githubusercontent.com/bcivitcioglu/runtop/master/assets/rt/glance.gif)

One target header, one grouped list, and one footer. Columns adapt to terminal
width. Container statistics and project totals remain close to their rows.

- `↑↓` / `jk` move; `[` / `]` switch machines; Space folds a section.
- `/` filters, `o` sorts by name, CPU, or memory, and `r` refreshes.
- `i` inspects, `l` opens container or project logs, and `D` shows storage.
- `s`, `x`, `R`, `X` start, stop, restart, or remove selected containers; actions
  preview the captured selection and require confirmation.
- `e` opens a shell; `p` previews dangling-image pruning; `?` shows all keys.
- In logs, `f` toggles following, `w` wraps, and Esc returns to the list.
- `--read-only` disables all mutations. `--no-mouse` disables mouse capture.

Lite keeps at most 2,000 log lines and 2 MiB of log text, and follows at most 64
selected sources. Archive recording, export, and archive search belong to full.

## Listings and diagnostics

```sh
runtop ps -a --json
rt ps -a --stats
rt ps --images
runtop --doctor
rt --doctor
runtop --dump lima:docker
```

`ps` lists local targets by default. Add `--contexts` to include remote targets,
or select one explicitly with `--target KEY`. `--json` uses the shared
[snapshot contract](https://github.com/bcivitcioglu/runtop/blob/master/spec/SPEC.md). Exit codes are 0 for success, 1 for no targets
or a discovery failure, 2 for invalid input, and 3 for unavailable or partial data.

Failed interactive refreshes retain the last successful data with a stale warning
and disable actions. Image-list failures leave containers usable. Remote contexts
are always read-only. No engine is installed and no machine is created on startup.

## Record and search logs

![Log archive controls](https://raw.githubusercontent.com/bcivitcioglu/runtop/master/assets/runtop/archives.png)

In full, `L` opens Log archives for the selected container or project. Choose a
folder and limits, then press **Record**. **Stop** ends capture. Closing the
controls keeps recording active until the app exits; an indicator stays visible.
**Export tail** saves recent output without following.

```sh
runtop logs record --target lima:docker --project shop --directory ~/logs/shop \
  --max-mib 64 --file-mib 8 --keep-days 7
runtop logs export --target lima:docker --container api --directory ~/logs/api --tail 500
runtop logs search error -i --directory ~/logs/shop --limit 200 --json
runtop logs status --directory ~/logs/shop --json
```

Recording is off by default. Defaults are 64 MiB total, 8 MiB per file, and seven
days retention. Rotation removes only owned archive files; one writer may use a
folder at a time. Search streams saved files with bounded results. Exit codes
are 0 for matches, 1 for none, and 2 for invalid input or an archive error.

Archives retain capture time, source identity, output stream, message, and
truncation markers. `--since` filters capture time. Queue or disk errors stop
capture visibly. Recording follows existing container IDs and does not reconnect
across their recreation. Saved output may contain application secrets.

## Develop

```sh
uv sync --locked
uv run ruff check
uv run ty check --error-on-warning
uv run pytest
cargo fmt --check
cargo clippy --locked --all-targets -- -D warnings
cargo test --locked
cargo build --locked --release
```

Both editions share normalization fixtures. Interface recordings use synthetic
`--demo` data. Local runtime workloads and development measurements are kept
outside distributed packages.
