# 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, native WebKit tracking prevention, Global Privacy Control, Do Not Track, WebKit request privacy headers, expanded tracking-query stripping, Firefox-inspired Strip-on-Share clean-link copy, redirect debouncing, live tracker subresource 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, capture/WebRTC only when explicitly enabled, 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:
```bash
cargo run
```
Launch with a URL, internal page, or search terms:
```bash
cargo run -- launch https://example.com
cargo run -- launch cephas://agent
```
Build and run the compiled binary directly:
```bash
cargo build
target/debug/cephas
```
Use a separate profile path:
```bash
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:
```bash
cargo run -- browse
```
Open one page and print reader-mode output:
```bash
cargo run -- open https://example.com
```
Print an AI-ready reader packet:
```bash
cargo run -- ai-reader https://example.com
```
Print a deterministic agent-reader artifact:
```bash
cargo run -- agent-reader data-signals https://example.com
```
Print the agent browser-command manifest:
```bash
cargo run -- agent-commands
cargo run -- agent-commands --jsonl
```
Print the portable manifest for code tools and agentic processes:
```bash
cargo run -- agent-tooling
```
Run the read-only MCP stdio bridge for code tools:
```bash
cargo run -- mcp
```
Print bounded resource diagnostics:
```bash
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:
```bash
cargo run -- self-test
cargo run -- self-test --json
```
Print the UUIDv7 plugin registry:
```bash
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:
```bash
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:
```bash
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:
```bash
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:
```text
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.
```bash
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:
```bash
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:
```bash
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.
- Profile file read: 4 MiB before profile sanitation and caps apply.
- Open tabs: 100 per window.
- Closed-tab snapshots: 25 per window.
- Terminal command input: 64 KiB per line before oversized input is discarded.
- 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 retained text: 4 KiB per label, task, message, action, detail, or command target.
- Agent retained metadata: 16 KiB after bounded depth and item normalization.
- 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 retained text: 4 KiB per title, message, frame reason, or page title.
- Visual recording retained details: 16 KiB after bounded depth and item normalization.
- 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.