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 7O-E — long-gap session continuity: PASS

The real GitHub dummy profile github-manual-local remained authenticated after a full S22 power-off/restart and approximately one week offline. It was reused headlessly without starting VNC/noVNC and without logging in again.

Current engineering phase:

Phase 7P — operator-quality profile lifecycle helpers

Implementation status:

• session:profile:status: added

• session:profile:probe: added

• session:profile:ensure: added

• session:profile:self-test: added

• static JavaScript and shell syntax checks: PASS

• local file-state classifier test: PASS

• live S22 Debian/Chromium verification: pending operator run

Phase 7P is therefore implemented but not yet marked fully PASS.

Related MCP server: Playwright MCP

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

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.

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/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 kill Termux under heavy runtime load.

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

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

• 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.