S22 Web Agent

S22 Web Agent repurposes a Samsung Galaxy S22 into a controlled, self-hosted MCP and browser-automation execution node.

Samsung S22
  -> Termux
  -> Node.js API and MCP servers
  -> SQLite local persistence
  -> Debian proot
  -> Playwright + Chromium
  -> VNC/noVNC for human-controlled login
  -> controlled tunnels when intentionally enabled

The project is a learning and portfolio proof for applied AI automation, MCP tool development, secure browser workflows, and constrained-device engineering.

Current status

Latest completed runtime proof:

Phase 7V — Automatic Protected On-Demand noVNC Handoff: PASS

Phase 7V confirmed automatic local noVNC and protected Cloudflare startup during a browser-control handoff, automatic return of the full public noVNC control URL, cleanup of the temporary public gateway after handoff, and preservation of the same persistent Chromium session.

The normal MCP HTTP surface remains the intended eight tools: five Job Radar tools plus browser_task_run, browser_task_handoff, and browser_task_status.

Project status:

S22 Web Agent v1 — COMPLETE

The functional runtime, unified operator lifecycle, automatic protected browser handoff, operator documentation, and fresh-device setup guidance are complete for the demonstrated Samsung S22 implementation.

Current operator and reproducibility documentation:

docs/operator-quickstart.md
docs/manual-service-commands.md
docs/installation-and-setup.md

Repository closure checkpoint:

checkpoint-phase-7v-documentation-closure

Remaining items in TODO.md are optional future enhancements, reliability improvements, additional regression coverage, or cross-device reproducibility work. They are not blockers for S22 Web Agent v1 completion.

Related MCP server: browser-mcp-server

Android runtime note

The first heavy public-login trials repeatedly ended with Android signal 9 around approximately 35 to 36 visible monitored processes even though MemAvailable was still about 3 GiB. This did not resemble straightforward Linux RAM exhaustion.

For the demonstrated successful full-stack proof, the Android phantom-process limit was raised to 256 through ADB. The operator also used one primary SSH session, tmux, Termux wake lock, and RAM Plus set to 8 GB. With that controlled configuration, Cloudflare, MCP, Debian proot, Chromium, VNC, noVNC, and the manual-login workflow ran together without the previous signal-9 failure.

This is strong operational evidence, not a perfectly isolated laboratory proof, because the SSH/tmux operating procedure also changed. The Android setting is outside this repository and cannot be enforced by the Node.js code.

Detailed result:

docs/android-phantom-process-runtime-result.md
docs/phase-7q-c2r-runtime-diagnostics.md

Current capabilities

• CLI and HTTP webpage scanning

• SQLite-backed scan history

• Markdown report generation

• MCP stdio and Streamable HTTP

• stateful MCP HTTP sessions

• optional bearer-token protection

• Cloudflare Route A public MCP proof

• OpenAI Secure MCP Tunnel proof

• Debian proot Playwright/Chromium worker

• browser-rendered inspection through MCP

• manual login through VNC

• stable tmux-held VNC

• local noVNC gateway

• temporary public noVNC proof protected by Cloudflare Access

• Playwright storageState capture

• named local session profiles

• domain-allowlisted authenticated scans

• MCP browser_scan_with_profile

• real GitHub dummy-account login and reuse

• session continuity after S22 restart and a long offline gap

• explicit saved-profile lifecycle states

• secret-safe runtime doctor and diagnostic watcher

• full-stack runtime proof with Android phantom-process limit set to 256

Project positioning

S22 Web Agent is not intended to become a broad personal-agent framework. It is a controlled execution node that exposes approved MCP tools while keeping local services and browser session artifacts private.

ChatGPT / Codex / another MCP client
  -> approved MCP tools
  -> S22 Web Agent
  -> local scanner or browser workflow

See docs/why-custom-s22-web-agent.md for the detailed rationale.

Architecture

Scanner path

CLI or local HTTP request
  -> scanner module
  -> SQLite
  -> Markdown report

Browser path

MCP browser tool or local helper
  -> Termux wrapper
  -> Debian proot Playwright worker
  -> Chromium

Authenticated session path

Human-controlled login through VNC/noVNC
  -> Playwright storageState saved under .runtime/
  -> named profile with domain allowlist
  -> future headless authenticated scans

Passwords, cookies, tokens, MFA codes, and storageState contents are not passed to the AI assistant.

Route A public MCP path

Remote MCP client
  -> https://s22agent.aidesk.rest/mcp
  -> Cloudflare Named Tunnel
  -> 127.0.0.1:3003/mcp

Only the MCP HTTP server is exposed in Route A.

Temporary public noVNC path

Remote browser
  -> Cloudflare Access protected temporary hostname
  -> cloudflared connector on S22
  -> 127.0.0.1:6080 noVNC
  -> 127.0.0.1:5901 VNC
  -> Debian Chromium

This route is separate from the MCP hostname. It must remain temporary, protected, human-controlled, and intentionally started.

Ports and exposure policy

Security boundary

• Never request or print passwords.

• Never request or print cookies.

• Never request or print session tokens.

• Never request or print MFA codes.

• Never print or paste storageState.json contents.

• Keep .runtime/sessions/ out of Git.

• Keep ports 3001, 3002, and 5901 local-only.

• Expose port 3003 only through an intentional controlled MCP route.

• Keep public noVNC temporary and intentionally started.

• Never auto-start public noVNC as a fallback.

• Keep tunnel tokens and MCP tokens out of the repository.

• Rotate the Cloudflare tunnel token before future public tests because it appeared in early raw logs before helper hardening.

• Do not upgrade npm to a new major version during this phase merely because an update notice appears.

• The current Termux installation is from Google Play; do not propose F-Droid migration by default.

• Treat the phantom-process setting as an explicit Android operator configuration, not an application default.

Runtime artifacts ignored by Git:

.runtime/
data/
reports/
*.log
.env

Main operating modes

Local CLI/API

node src/index.js scan example.com
npm run api:start
npm run api:status
npm run api:stop

Default API endpoint:

http://127.0.0.1:3001

MCP stdio

npm run mcp

MCP Streamable HTTP

npm run mcp:http:start
npm run mcp:http:status
npm run mcp:http:stop

Default endpoint:

http://127.0.0.1:3003/mcp

Route A Cloudflare MCP

npm run route:a:start
npm run route:a:status
npm run route:a:stop

Public endpoint:

https://s22agent.aidesk.rest/mcp

OpenAI Secure MCP Tunnel

npm run openai:tunnel:start
proot-distro login debian
cd /data/data/com.termux/files/home/projects/mobile-job-radar-agent
npm run openai:tunnel:client:debian

Status and stop:

npm run openai:tunnel:status
npm run openai:tunnel:stop

The runtime key is prompted locally and is not stored in the repository.

Session helpers

VNC and noVNC

npm run session:vnc:start
npm run session:vnc:status
npm run session:vnc:stop

npm run session:vnc:start:stable
npm run session:vnc:stop:stable

npm run session:novnc:start:local
npm run session:novnc:status:local
npm run session:novnc:stop:local

Human-controlled local login

SESSION_LOGIN_TIMEOUT_MS=1200000 npm run session:manual-login:novnc:start -- <profile> <login-url>
npm run session:manual-login:novnc:status -- <profile>
SESSION_SCAN_SUPPRESS_EXCERPT=1 npm run session:manual-login:novnc:complete -- <profile> <authenticated-url> "<expected-text>"
npm run session:manual-login:novnc:cancel -- <profile>

Existing profile scan

SESSION_SCAN_SUPPRESS_EXCERPT=1 npm run session:profile:scan -- <profile> <url> "<expected-text>"

Phase 7P profile lifecycle

A profile file existing locally does not prove that the remote website session is still authenticated.

States

missing
present_unverified
valid
expired_or_logged_out
domain_mismatch
runtime_error

Exit codes:

Lightweight status

Does not launch Chromium:

npm run session:profile:status -- <profile> [target-url]

An existing readable profile normally returns:

present_unverified

Live authenticated probe

Launches headless Chromium inside Debian proot and requires an authenticated marker:

npm run session:profile:probe -- <profile> <authenticated-url> "<expected-text>"

marker found     -> valid
marker not found -> expired_or_logged_out

Page text excerpts are suppressed by design.

Reuse-first ensure

npm run session:profile:ensure -- <profile> <authenticated-url> "<expected-text>" [login-url]

ensure checks local status first and then performs a live probe. When refresh is required, it prints safe local manual-login guidance with URL placeholders. It does not echo supplied URLs and does not start VNC, noVNC, Cloudflare, or any public route.

Local self-test

npm run session:profile:self-test

The disposable test covers:

missing
present_unverified
domain_mismatch
runtime_error

It does not touch a real profile.

Detailed implementation and test instructions:

docs/phase-7p-profile-lifecycle-helpers.md

Required S22 verification

After pulling the latest main branch:

cd ~/projects/mobile-job-radar-agent
git pull --ff-only
npm run session:profile:self-test
npm run session:profile:status -- github-manual-local https://github.com/settings/profile
npm run session:profile:probe -- github-manual-local https://github.com/settings/profile "Public profile"
npm run session:profile:ensure -- github-manual-local https://github.com/settings/profile "Public profile" https://github.com/login
git status --short

Expected while the GitHub dummy session remains authenticated:

self-test -> PASS
status    -> present_unverified
probe     -> valid
ensure    -> valid
git status --short -> no output

These checks do not require VNC, noVNC, or a public tunnel.

MCP tools

job_radar_health
job_radar_scan
job_radar_list_pages
job_radar_get_page
job_radar_get_report
browser_inspect_url
browser_scan_url
browser_scan_with_profile
browser_start_manual_login
browser_manual_login_status
browser_complete_manual_login
browser_cancel_manual_login

The authenticated profile MCP tool accepts only a named profile, target URL, and optional expected text. It does not accept passwords, cookies, tokens, or an arbitrary storageState path.

Session-gateway milestones

Important documentation

docs/android-phantom-process-runtime-result.md
docs/phase-7q-c2r-runtime-diagnostics.md
docs/phase-7o-e-long-gap-session-continuity.md
docs/phase-7p-profile-lifecycle-helpers.md
docs/phase-7o-agent-continuity-proof.md
docs/phase-7n-temporary-cloudflare-access-novnc-proof.md
docs/phase-7m-local-novnc-assisted-manual-login.md
docs/session-gateway-design.md
docs/why-custom-s22-web-agent.md

For AI-assisted repository navigation, see llm-index.yaml.

Known limitations

• Android may still kill Termux under heavy runtime load; the demonstrated configuration raised the phantom-process limit to 256, but this is not an application-level guarantee.

• tmux protects against SSH disconnect but not Android terminating Termux.

• AnyDesk, multiple SSH sessions, VNC, noVNC, and Chromium together can make the S22 unstable.

• The phantom-process setting is device and firmware dependent and may need operator verification after Android updates.

• A small orphan websockify/proot pair may remain after some noVNC shutdown paths.

• A saved profile may exist while the remote session is expired.

• Websites can revoke or challenge sessions independently.

• An absent expected marker can also mean the target page content changed; expired_or_logged_out is deliberately a fail-safe classification.

• Browser performance is limited by phone hardware, thermal behavior, and proot overhead.

• The project is a controlled engineering proof, not a production-grade managed server.