cephas 0.1.3

Privacy-first GTK/WebKit browser with local agent tooling.
Documentation

Cephas

Cephas is a privacy-first Rust browser shell packaged as the Cargo binary cephas. It uses a native GTK/WebKit desktop window, local profile storage, internal browser pages, deterministic reader extraction, and auditable agent-control surfaces.

The default desktop experience opens a fast local Start page with Paper as the default light theme. The Start page can cycle themes with cephas://start/theme, and Settings exposes Paper-like OS/browser-inspired variants such as macOS Paper, Glass, AI Inspect, Edge Paper, Brave Blue, Vivaldi Green, and Ubuntu Rose.

Highlights

  • Native GTK/WebKit browser window with tabs, address bar, downloads, history, bookmarks, reader mode, startup session restore, and profile persistence.
  • Internal pages for Start, Settings, Diagnostics, Plugins, Agent control, and Agent docs: cephas://start, cephas://settings, cephas://diagnostics, cephas://plugins, cephas://agent, and cephas://agent/docs.
  • Site Armour privacy protections: HTTPS upgrades, Global Privacy Control, Do Not Track, WebKit request privacy headers, tracking-query stripping, Firefox-inspired Strip-on-Share clean-link copy, redirect debouncing, normalized tracker host blocking, De-AMP, and per-site controls.
  • Settings page for Paper-style themes, Glass and AI Inspect modes, custom theme colors/radius/density, privacy defaults, search provider, home URL, plugin registry cards, PDF handling posture, and WebKit GPU acceleration policy.
  • WebKit media/PDF policy for modern playback, MediaSource, encrypted media, fullscreen, inline video, optional capture prompts, and browser-surface PDF navigation when the runtime supports it.
  • Agent control page for delegation, Agent Vision context, browser-window human control, reader tools, visual recording controls, command manifest, window context JSON, and audit paths.
  • Agent reader artifacts with UUIDv7 IDs: brief, full text, outline, link map, data signals, JSON artifact, and source/content truncation flags.
  • Bounded UUIDv7 plugin registry with bundled project modules for content blockers, themes, media helpers, tools, Agent hooks, and reader extensions.
  • Visual screenshot CLI for agents and smoke tests: render URLs or internal pages to PNG.
  • One-command visual smoke suite for core internal pages.
  • Bounded long-running resources for tabs, closed tabs, history, bookmarks, downloads, sessions, terminal navigation, and response bodies.

Requirements

  • Rust toolchain with Cargo.
  • GTK 3 and WebKitGTK 2 development/runtime libraries available on the system.
  • A desktop/session environment capable of running GTK windows for GUI and screenshot commands.

Quick Start

Run the desktop browser:

cargo run

Launch with a URL, internal page, or search terms:

cargo run -- launch https://example.com
cargo run -- launch cephas://agent

Build and run the compiled binary directly:

cargo build
target/debug/cephas

Use a separate profile path:

cargo run -- --profile ./profile.json launch

Internal Pages

  • cephas://start: local Start page with profile-selected search, shortcuts, stats, Armour summary, theme toggle, AI browsing toggle, and Agent entry.
  • cephas://start/theme: cycle to the next saved browser theme and persist it locally.
  • cephas://settings: full Settings page for themes, startup behavior, search provider, privacy defaults, GPU policy, and home URL.
  • cephas://settings/theme-preset?id=<preset-id>: apply a bounded built-in custom theme preset to the active profile.
  • cephas://diagnostics: local bounded-resource diagnostics page with live GTK runtime counters and CLI JSON guidance.
  • cephas://plugins: full local UUIDv7 plugin registry page with bundled-module install cards, capability labels, permission labels, and registry limits.
  • cephas://agent: full Agent control page for delegation, Agent Vision context, browser-window human control, reader tools, recording, screenshots, manifest, context, and audit state.
  • cephas://agent/docs: local agentic integration guide for command discovery, JSON/JSONL surfaces, smoke workflows, human-control safety, and code-tool porting.

Desktop Controls

  • Ctrl+T: new tab.
  • Ctrl+W: close tab.
  • Ctrl+L: focus the address bar.
  • Ctrl+F: find in page.
  • Ctrl+H: history dialog.
  • Ctrl+J: downloads dialog.
  • Ctrl+D: bookmark current page.
  • Ctrl+Shift+T: reopen closed tab.
  • Ctrl+Shift+D: duplicate active tab.
  • Ctrl+Shift+P: new private tab.
  • Ctrl+Shift+B: toggle bookmarks bar.
  • Ctrl+plus, Ctrl+minus, Ctrl+0: zoom active tab.

CLI Commands

Open the terminal browser mode:

cargo run -- browse

Open one page and print reader-mode output:

cargo run -- open https://example.com

Print an AI-ready reader packet:

cargo run -- ai-reader https://example.com

Print a deterministic agent-reader artifact:

cargo run -- agent-reader data-signals https://example.com

Print the agent browser-command manifest:

cargo run -- agent-commands
cargo run -- agent-commands --jsonl

Print the portable manifest for code tools and agentic processes:

cargo run -- agent-tooling

Run the read-only MCP stdio bridge for code tools:

cargo run -- mcp

Print bounded resource diagnostics:

cargo run -- diagnostics
cargo run -- diagnostics --json
cargo run -- diagnostics --json --strict

The diagnostics CLI reports the persisted/offline subset using schema cephas.diagnostics.v1. Use cephas://diagnostics, agent-screenshot cephas://diagnostics --output <png> --json, or agent-smoke --output-dir <dir> --case diagnostics --json when live GTK/WebKit counters matter, including open tabs, closed-tab snapshots, active downloads, save queue state, active recording, pending human-control waits, and RSS.

Run fast built-in self checks for route policy, cap clamps, and unsafe home migration:

cargo run -- self-test
cargo run -- self-test --json

Print the UUIDv7 plugin registry:

cargo run -- plugins
cargo run -- plugins --jsonl
cargo run -- plugins available
cargo run -- plugins check
cargo run -- plugins check --strict
cargo run -- plugins install <plugin-id-or-module-id>
cargo run -- plugins install-all
cargo run -- plugins sync <plugin-id-or-module-id>
cargo run -- plugins sync-all
cargo run -- plugins enable <plugin-id-or-module-id>
cargo run -- plugins disable <plugin-id-or-module-id>
cargo run -- plugins remove <plugin-id-or-module-id>

Bundled plugin modules are metadata-only local project modules. plugins available only lists modules not already installed in the selected profile and includes each module source path for review. plugins check emits a machine-readable registry health report; add --strict or --fail-on-warning when CI should fail on warnings as well as errors. Bundled actions accept either the UUID plugin ID or the module ID, such as reader-outline. Installing, enabling, or syncing them updates the profile registry; it does not execute plugin code or download packages.

Capture a visual screenshot of a URL or internal page:

cargo run -- agent-screenshot cephas://agent --output /tmp/cephas-agent.png
cargo run -- agent-screenshot cephas://agent --output /tmp/cephas-agent.png --json

Run the visual Agent smoke suite:

cargo run -- agent-smoke --output-dir /tmp/cephas-smoke
cargo run -- agent-smoke --output-dir /tmp/cephas-smoke --json
cargo run -- agent-smoke --output-dir /tmp/cephas-smoke --case agent --json

Print the profile location and profile counts:

cargo run -- profile

Agent Features

The Agent page is intentionally a full internal page, not a popover. It is designed to be inspected by humans and agents, captured as a screenshot, and audited through JSONL logs.

Agent-facing tools include:

  • agent-commands for a stable command manifest.
  • agent-commands --jsonl for one manifest entry per line.
  • agent-tooling for a portable manifest covering CLI forms, browser commands, routes, smoke cases, reader tools, resource caps, diagnostics surfaces, and schemas.
  • mcp for a read-only stdio MCP server exposing cephas_agent_tooling, cephas_agent_commands, cephas_diagnostics, and cephas_plugins tools.
  • diagnostics --json --strict for bounded resource counts, cap-ID-keyed resource_checks, and unobserved_resource_caps using schema cephas.diagnostics.v1, with non-zero exit when diagnostics are not ok.
  • self-test --json for fast pure checks of launch route policy, profile/plugin cap clamps, and unsafe home migration using schema cephas.self-test.v1.
  • agent-reader <tool> <target> for deterministic text and metadata artifacts, including source_body_truncated and content_truncated in JSON artifacts.
  • agent-screenshot <target> --output <png> --json for visual inspection with a machine-readable result and duration_ms timing.
  • agent-smoke --output-dir <dir> --json for repeatable visual and browser-policy smoke checks with a machine-readable report.
  • plugins, plugins --jsonl, and plugins available for the bounded UUIDv7 plugin registry and bundled local module catalog.
  • cephas://agent for the in-browser control panel.
  • cephas://agent/docs for the local code-tool integration guide.
  • cephas://agent#emulation for a visual dry-run lab covering every registered agent command.
  • cephas.agent-vision.v1 in the Agent page context JSON for screenshot, recording, reader, emulation, and human-control routes.

Browser-window human control is session-only and opt-in from cephas://agent. It uses WebKit page evaluation to dispatch events into the active normal page; it does not control the OS desktop and it is rejected on private tabs and internal pages.

For AI-readable visuals, switch to the AI Inspect theme from Settings. It uses high-contrast, color-coded borders around navigation, address, cards, rows, and action regions so screenshots are easier to segment. The Glass theme keeps translucent surfaces, opacity, and shadows for a polished human-facing mode. The Custom theme is profile-local and lets you start from bounded built-in presets, then tune chrome, page, surface, text, muted, accent, corner radius, and density values. Settings computes custom-theme contrast guidance on render so unreadable palettes are visible before long sessions.

The Agent Emulation Lab on cephas://agent lets you click every command from the manifest and inspect the dry-run request JSON, current integration surface, and expected result. It is intentionally non-destructive and is meant for planning better agentic integrations. When visual recording is active, emulation events request frames with agent-emulation:<command-id> reasons, and completed human-control actions request human-control:<action> frames so the local replay is watchable and backend-ready without uploading anything by default.

Example human-control routes after opt-in:

cephas://agent/human/move?x=320&y=240
cephas://agent/human/click?x=320&y=240
cephas://agent/human/type?text=hello%20from%20Cephas
cephas://agent/human/key?key=Enter
cephas://agent/human/scroll?dy=600
cephas://agent/human/wait?ms=1000

Visual Smoke Tests

Use agent-smoke when changing internal pages, Start page controls, Agent page layout, navigation interception, WebKit loading, themes, or screenshot behavior.

target/debug/cephas agent-smoke --output-dir /tmp/cephas-smoke
target/debug/cephas agent-smoke --output-dir /tmp/cephas-smoke --json

The command writes:

  • /tmp/cephas-smoke/agent.png
  • /tmp/cephas-smoke/agent-docs.png
  • /tmp/cephas-smoke/agent-document.png
  • /tmp/cephas-smoke/start.png
  • /tmp/cephas-smoke/settings.png
  • /tmp/cephas-smoke/diagnostics.png
  • /tmp/cephas-smoke/plugins.png
  • /tmp/cephas-smoke/internal-route-trust.json
  • /tmp/cephas-smoke/launch-unsafe-home.json
  • /tmp/cephas-smoke/launch-unknown-internal.json

It fails if a screenshot cannot be rendered, if WebKit reports a load failure, if a PNG output looks suspiciously small, if the PNG header or dimensions are invalid, if an untrusted local web page can trigger a mutating internal route, or if isolated launch-safety checks cannot start safely. JSON output includes suite-level and per-case duration_ms for basic regression tracking.

Use --case agent, --case agent-docs, --case agent-document, --case start, --case settings, --case diagnostics, --case plugins, --case internal-route-trust, --case launch-unsafe-home, or --case launch-unknown-internal for targeted checks. Use --min-bytes <n> to tune the suspicious PNG threshold for a specific environment.

Development Checks

Run the standard checks before handing off changes:

cargo fmt --all
cargo check
cargo test
cargo clippy --all-targets -- -D warnings
cargo build
target/debug/cephas agent-smoke --output-dir /tmp/cephas-smoke

Useful cleanup check after launch smoke tests:

pgrep -af '[t]arget/debug/cephas|[W]ebKit|[D]inas'

No output means there are no leftover Cephas/WebKit processes.

Troubleshooting

If a web page link to a mutating cephas:// action does nothing, that is expected. Ordinary web pages cannot trigger profile mutations such as theme changes, plugin actions, Agent delegation, recordings, or human control. Use the matching Cephas internal page, browser chrome control, or a direct trusted launch target instead.

If a download action says Download command is not available, check the retained download path. Cephas only opens, shows, or deletes files that resolve inside the downloads directory and rejects symlink escapes. Risky executable extensions require an explicit Open anyway confirmation before Cephas asks the OS to open them.

Terminal Browser Commands

Terminal mode uses aligned sections and ANSI color when the terminal supports it. Set NO_COLOR=1 or use TERM=dumb for plain output.

  • open <url/search> opens a URL or search terms.
  • back, forward, and reload navigate the session.
  • read prints reader-mode text again.
  • privacy shows the Armour report.
  • armour on or armour off toggles protections for the current site.
  • bookmark and bookmarks manage bookmarks.
  • history lists recent visits.
  • diagnostics shows bounded resource counts.
  • forget deletes history for the current site.
  • save writes the profile.
  • quit saves and exits.

Resource Policy

  • History: 500 entries by default.
  • Bookmarks: 1,000 entries by default.
  • Open tabs: 100 per window.
  • Closed-tab snapshots: 25 per window.
  • Session restore: 4 windows and 100 tabs per window.
  • Session restore file read: 512 KiB before restore sanitation and caps apply.
  • Download records: 500 retained records by default.
  • Active downloads: 16 concurrent downloads.
  • Download registry file read: 2 MiB before download sanitation and caps apply.
  • Terminal navigation stacks: 100 entries each.
  • Terminal response bodies: 5 MiB per loaded page.
  • GUI reader response bodies: 5 MiB per fetched page.
  • MCP stdio bridge: 1 MiB per JSON-RPC request line and 32 requests per batch.
  • Plugins: 128 UUIDv7 plugin records.
  • Agent event buffer: 1,000 in-memory events.
  • Agent delegations: 64 retained delegations.
  • Agent audit log: 5 MiB active JSONL file plus 5 rotated archives.
  • Visual recording: 10,000 events and 1,200 frames per recording.
  • Visual recording retention: 25 local recording directories.
  • Armour allowlist: 512 hosts.
  • Armour blocked host rules: 2,048 hosts, including preserved built-in tracker rules.
  • Diagnostics expose profile, persisted session, downloads, plugins, audit-log size, recording directories, Armour host sets, resource caps, a cap-ID-keyed resource_checks object, and unobserved_resource_caps for live/per-artifact caps that persisted diagnostics cannot check.

Long-running features must define ownership, maximum size, eviction or rotation behavior, and diagnostics before merge. Avoid unbounded collections, unbounded channels, orphaned tasks, and cache growth without an explicit lifecycle.

Architecture

Cephas is a native Rust browser shell and does not vendor Chromium C++ code. The project focuses on practical desktop-browser features: local browser pages, Armour privacy controls, reader extraction, bounded resources, and auditable agent workflows.