{"id":51711851,"url":"https://github.com/redstone-md/agentium","last_synced_at":"2026-07-16T22:06:30.590Z","repository":{"id":356208883,"uuid":"1183768791","full_name":"redstone-md/agentium","owner":"redstone-md","description":"Agentium is an AI-native browser engine written in Go. It drives Chromium through CDP using go-rod, exposes a REST API for browser sessions, and also ships MCP tools for agent-native integrations.","archived":false,"fork":false,"pushed_at":"2026-05-07T03:15:41.000Z","size":94,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-07T05:17:13.367Z","etag":null,"topics":["ai-native","browser","cdp","chromium","mcp","mcp-server","playwright","puppeteer"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/redstone-md.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-16T23:51:21.000Z","updated_at":"2026-05-07T03:15:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/redstone-md/agentium","commit_stats":null,"previous_names":["redstone-md/agentium"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/redstone-md/agentium","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redstone-md%2Fagentium","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redstone-md%2Fagentium/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redstone-md%2Fagentium/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redstone-md%2Fagentium/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/redstone-md","download_url":"https://codeload.github.com/redstone-md/agentium/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redstone-md%2Fagentium/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35559897,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-16T02:00:06.687Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-native","browser","cdp","chromium","mcp","mcp-server","playwright","puppeteer"],"created_at":"2026-07-16T22:06:29.965Z","updated_at":"2026-07-16T22:06:30.585Z","avatar_url":"https://github.com/redstone-md.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agentium\n\nAgentium is an AI-native browser engine written in Go. It drives Chrome or Chromium through CDP with `go-rod`, exposes a REST API for browser sessions, and ships MCP tools for agent-native integrations.\n\n## Quick Start\n\nBuild:\n\n```bash\ngo build -o agentium ./cmd/agentium\n```\n\nRun REST + MCP SSE in the default headful mode:\n\n```bash\n./agentium\n```\n\nRun headless:\n\n```bash\n./agentium -headless=true\n```\n\nRun MCP over stdio:\n\n```bash\n./agentium -mode mcp-stdio\n```\n\nPrint the effective startup config:\n\n```bash\n./agentium -print-config\n```\n\n## Runtime Controls\n\nAgentium supports both environment variables and CLI flags. CLI flags override env values.\n\n### CLI flags\n\n- `-mode=http|mcp-stdio`\n- `-http-addr=:8080`\n- `-chrome-bin=/absolute/path/to/chrome`\n- `-headless=true|false`\n- `-leakless=true|false`\n- `-viewport-width=1280`\n- `-viewport-height=800`\n- `-print-config`\n\n### Environment variables\n\n- `AGENTIUM_HTTP_ADDR` default: `:8080`\n- `AGENTIUM_CHROME_BIN` default: empty\n- `AGENTIUM_HEADLESS` default: `false`\n- `AGENTIUM_LEAKLESS` default: `true`\n- `AGENTIUM_VIEWPORT_WIDTH` default: `1280`\n- `AGENTIUM_VIEWPORT_HEIGHT` default: `800`\n- `AGENTIUM_GEOIP_ENDPOINT` default: `https://ipwho.is/`\n- `AGENTIUM_GEOIP_TIMEOUT_SECONDS` default: `8`\n\nA ready-to-copy example is available in [`agentium.env.example`](D:\\code\\Agentium\\examples\\agentium.env.example).\n\n## Session Modes\n\nSession creation supports two isolation modes:\n\n- `incognito`: default. Lightweight isolated browser contexts.\n- `persistent`: dedicated browser profile directory per session. Use this for stealth-sensitive work and sites that penalize incognito mode.\n\nRecommended:\n\n- Use `persistent` for Pixelscan, BrowserScan, login flows, and long-lived profiles.\n- Use `incognito` for short isolated tasks when stealth quality matters less than throughput.\n\n## Local Run\n\nHeadful HTTP server on a custom port:\n\n```bash\n./agentium -http-addr :9090 -headless=false\n```\n\nHeadless MCP stdio server:\n\n```bash\n./agentium -mode mcp-stdio -headless=true\n```\n\nUse a specific Chrome binary:\n\n```bash\n./agentium -chrome-bin \"/usr/bin/google-chrome\"\n```\n\nOn Windows PowerShell:\n\n```powershell\n$env:AGENTIUM_CHROME_BIN=\"C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe\"\n.\\agentium.exe -headless=false\n```\n\n## Docker Run\n\nThe runtime image is based on Debian bookworm, not Ubuntu. Ubuntu 24.04 moves Chromium to a snap-oriented package flow, which is a poor fit for this minimal Xvfb container.\n\nBuild:\n\n```bash\ndocker build -t agentium:latest .\n```\n\nRun headful:\n\n```bash\ndocker run --rm -p 8080:8080 agentium:latest\n```\n\nRun headless:\n\n```bash\ndocker run --rm -p 8080:8080 -e AGENTIUM_HEADLESS=true agentium:latest\n```\n\nThe container starts `Xvfb` only when `AGENTIUM_HEADLESS=false`.\n\n## REST API\n\nHealth check:\n\n```bash\ncurl http://127.0.0.1:8080/healthz\n```\n\nCreate session:\n\n```bash\ncurl -X POST http://127.0.0.1:8080/v1/sessions \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"session_mode\": \"persistent\",\n    \"timezone_id\": \"Europe/Prague\",\n    \"locale\": \"cs-CZ\"\n  }'\n```\n\nGet snapshot:\n\n```bash\ncurl http://127.0.0.1:8080/v1/sessions/\u003csession_id\u003e/snapshot\n```\n\nPerform action:\n\n```bash\ncurl -X POST http://127.0.0.1:8080/v1/sessions/\u003csession_id\u003e/action \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"action\": \"navigate\",\n    \"value\": \"https://example.com\"\n  }'\n```\n\nClose session:\n\n```bash\ncurl -X DELETE http://127.0.0.1:8080/v1/sessions/\u003csession_id\u003e\n```\n\n## MCP\n\n### Stdio mode\n\nAvailable tools:\n\n- `agentium_create_session`\n- `agentium_get_snapshot`\n- `agentium_perform_action`\n- `agentium_close_session`\n\nLaunch:\n\n```bash\n./agentium -mode mcp-stdio -headless=false\n```\n\n### SSE mode\n\nWhen Agentium runs in HTTP mode, MCP SSE is exposed under:\n\n- `GET /mcp`\n- `POST /mcp/*`\n\n## Agent Instructions\n\nThe recommended agent workflow is documented in [`agent-playbook.md`](D:\\code\\Agentium\\docs\\agent-playbook.md).\n\nReady-made Claude Desktop configs:\n\n- headful: [`claude_desktop_config.json`](D:\\code\\Agentium\\examples\\claude_desktop_config.json)\n- headless: [`claude_desktop_config.headless.json`](D:\\code\\Agentium\\examples\\claude_desktop_config.headless.json)\n\n## Smoke Tests\n\nREST smoke test:\n\n```powershell\npwsh ./scripts/smoke-http.ps1\n```\n\nMCP stdio smoke test:\n\n```powershell\npwsh ./scripts/smoke-mcp-stdio.ps1 -BinaryPath .\\agentium.exe\n```\n\nMCP SSE smoke test:\n\n```powershell\npwsh ./scripts/smoke-mcp-sse.ps1\n```\n\nLocal HTTP + SSE smoke run:\n\n```powershell\npwsh ./scripts/run-local-http-smokes.ps1 -BinaryPath .\\agentium.exe\n```\n\nIf local Windows antivirus blocks Rod's `leakless` helper:\n\n```powershell\npwsh ./scripts/run-local-http-smokes.ps1 -BinaryPath .\\agentium.exe -DisableLeakless\n```\n\nStealth validation against `bot.sannysoft.com`:\n\n```powershell\npwsh ./scripts/run-local-http-smokes.ps1 -BinaryPath .\\agentium.exe -DisableLeakless -TargetUrl https://bot.sannysoft.com/ -DelayAfterNavigateMs 8000\n```\n\nStealth validation against `browserscan.net`:\n\n```powershell\npwsh ./scripts/run-local-stealth-browserscan.ps1 -BinaryPath .\\agentium.exe -DisableLeakless\n```\n\nStealth validation against `pixelscan.net`:\n\n```powershell\npwsh ./scripts/run-local-stealth-pixelscan.ps1 -BinaryPath .\\agentium.exe -DisableLeakless\n```\n\n## Notes\n\n- Browser pooling is keyed by proxy configuration.\n- `persistent` sessions launch dedicated browser profiles and intentionally trade some startup cost for better real-world browser parity.\n- `wait_network_idle` focuses on XHR and Fetch activity, which is usually the useful signal for form submissions and SPA mutations.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredstone-md%2Fagentium","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fredstone-md%2Fagentium","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredstone-md%2Fagentium/lists"}