The Problem

Carbonyl brings a full Chromium-based browser into a terminal, allowing web rendering without a window server. It is useful for SSH‑based remote work, head‑less environments, or any scenario where a GUI is unavailable but web content must be displayed.

What This Does

The project splits into a Rust core (libcarbonyl) and a modified Chromium head‑less shell (carbonyl executable). The core is built with cargo build and provides a small API; the runtime loads the core and handles the browser UI. Key files and their responsibilities (from the responsibility map) are:

  • src/lib.rs – entry point that wires the core and runtime.
  • src/cli/cli.rs – parses command‑line arguments (parse, CommandLine, EnvVar).
  • src/browser/bridge.rs – the Rust‑to‑Chromium bridge (20 functions, 9 types).
  • src/input/tty.rs – terminal I/O setup (setup, teardown, stdin, enter_alt_screen).
  • src/output/renderer.rs – renders frames to the terminal (enable_true_color, keypress, mouse events).

The repository supports virtually all Web APIs—WebGL, WebGPU, audio, video— and starts in under a second, idling at 0 % CPU.

How It Is Wired

Execution starts at main in build.rs:42, which reaches 19 functions and is called from one place. From main the control flow goes through parse (src/cli/cli.rs:39), called from eight locations, then into the browser bridge and input handling. The internal call graph contains 84 resolved edges; the most‑connected functions are parse (8 callers), render (7 callers), and cast (5 callers).

A traced path to the filesystem: main → stdin [File::open] and setup → open_raw [Self::open]. No other edges leave the process beyond these two routes. The module graph shows no circular dependencies; the most connected modules are .refloat/config and scripts/npm-package, both with zero importers and importers.

How To Use It

Setup

  • Clone the repository:
git clone https://github.com/moses-y/carbonyl
  • For the Rust core:
cd carbonyl
cargo build          # builds libcarbonyl
  • For the runtime binary (requires a full Chromium build, >1 hour):
scripts/build.sh     # orchestrates the Chromium build

Configuration

  • Environment variables are read from scripts/env.sh; the .refloat/config.js file holds runtime preferences.
  • The Dockerfile uses rust:1.67 and debian:bullseye-slim (mutable base image; see the “Code Health & Issues” section).

Running it

  • Via Docker (no local build needed):
docker run --rm -ti fathyb/carbonyl https://youtube.com
  • From the built binary:
./target/release/carbonyl https://github.com
  • npm global install (if the npm package is published):
npm install --global carbonyl
carbonyl https://example.com

Real‑World Use

A developer SSH‑ed into a head‑less server can launch carbonyl https://internal‑dashboard.com and view the UI directly in the terminal, without X11 or VNC. Because the core is a shared library, it can also be embedded by other Rust projects that need a lightweight web view (e.g., documentation renderers or remote‑debugging tools).

Code Health & Issues

Measured static‑analysis findings (11 total, 5 high, 6 medium, 0 low, 1 distinct kind):

  • [HIGH/cognitive_load] Deep nesting across 11 instances in src/browser/bridge.rs, src/browser/host_display_client.cc, and src/cli/cli.rs. Maximum indentation depth 8 makes control‑flow hard to follow. Remedy: flatten with early returns/guard clauses and extract inner blocks.

SDLC observations (from the code‑health audit):

  • [HIGH] Add a test suite – the repo has 47 source files and no test files; without tests regressions go undetected.
  • [HIGH] Add a CI/CD workflow that builds and tests on push/pull_request – currently no pipeline exists.
  • [HIGH] Add a build gate for deployable artifacts (Dockerfile) – the Dockerfile has not been validated by an automated step.
  • [MEDIUM] Enable Dependabot or Renovate – two manifests (Cargo.toml, package.json) are present but no update bot is configured.
  • [MEDIUM] Pin the container base image by digest in the Dockerfile – currently rust:1.67 and debian:bullseye-slim are mutable.
  • [LOW] Add repository convention files – missing .editorconfig, .gitattributes (text=auto eol=lf), and a formatter config.

The Bottom Line

Carbonyl delivers a surprisingly capable Chromium experience inside a terminal, with low overhead and no window‑server requirement. The codebase is functional but lacks tests, CI, and image‑pinning safeguards; those gaps should be addressed before production use. It is well‑suited for developers, sysadmins, and anyone needing a lightweight web view in constrained environments.