{"id":20790001,"url":"https://github.com/runreflect/agent","last_synced_at":"2025-05-05T19:54:27.973Z","repository":{"id":103744215,"uuid":"516393663","full_name":"runreflect/agent","owner":"runreflect","description":"The Reflect Agent allows secure connections between Reflect's cloud browsers and private web applications.","archived":false,"fork":false,"pushed_at":"2024-05-31T01:26:13.000Z","size":29,"stargazers_count":5,"open_issues_count":4,"forks_count":0,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-03-30T23:12:26.709Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/runreflect.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","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}},"created_at":"2022-07-21T13:58:39.000Z","updated_at":"2024-05-31T01:26:14.000Z","dependencies_parsed_at":"2024-05-31T01:57:01.764Z","dependency_job_id":null,"html_url":"https://github.com/runreflect/agent","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runreflect%2Fagent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runreflect%2Fagent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runreflect%2Fagent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runreflect%2Fagent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/runreflect","download_url":"https://codeload.github.com/runreflect/agent/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252567757,"owners_count":21769296,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-11-17T15:31:02.448Z","updated_at":"2025-05-05T19:54:27.950Z","avatar_url":"https://github.com/runreflect.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Reflect Agent\n\n[Reflect](https://reflect.run) is a regression testing platform for web applications,\nwhich replaces manual and code-based testing with automated test runs and failure notifications.\n\nThe Reflect Agent is a networked deamon that establishes a secure tunnel\nfrom an internal local area network back to Reflect.\nThis allows customers to use Reflect's cloud-based platform\nto create and run tests against private, non-publicly-accessible applications.\n\nThe Reflect Agent runs as a docker container (or directly on the host) within the private network.\nIt establishes a [Wireguard](https://www.wireguard.com/) tunnel via Reflect's API\nthrough which the Reflect browsers can reach applications in the private network.\n\n## Background\n\nReflect is a cloud-based platform where users can instantiate browser instances and\ninteract with their own web applications through those cloud browsers.\nFrom these interactions, Reflect automatically generates repeatable test cases.\nThen, users can run those test cases against their applications without manual intervention.\nReflect notifies users if the test cases were succesfully performed or not.\n\nSince Reflect's browsers run on the public Internet, the web application under test must be publicly accessible.\nHowever, some web applications are not publicly-accessible on the Internet.\nIn these cases, users run the Reflect Agent to establish a secure network connection\nbetween their environment and the Reflect platform.\nThis allows private web applications to be accessible, but only to Reflect's cloud browsers.\n\n## Installation\n\nThe default installation assumes a Linux host with kernel version 5.6 or later,\nwhich means the Wireguard network module is included in the kernel.\nHowever, when running in `--local` mode (see below),\na Mac OS X host with the Wireguard utilities installed can also be used.\n\n### Docker\n\nWhen running the agent as a container (again, the default),\nit requires Docker or Podman to be installed on the host.\nTypically, the host will have a restricted network ACL as well.\n\nThe agent binds to a UDP port on the host's network interface and\nestablishes a websocket to the Reflect API to be notified when new browser sessions are launched in Reflect.\nFor each agent-based browser session in Reflect,\nthe agent initiates a secure connection over Wireguard.\n\nTo install the agent, you'll need `docker` installed, and then run:\n\n```\n$ ./build-agent.sh\n```\n\nNOTE: On Windows, the bash script above will likely not work.\nTo build the agent for Windows, run the Docker command directly:\n```\ndocker build -t agent .\n```\n\n(In the future, Reflect may release an official container image publicly.)\n\n### Local\n\nAlternatively, you can run the agent directly on your host machine running Mac OS X.\nIn this mode, the agent runs as a collection of bash scripts,\nbut requires several utility program dependencies to be installed.\n\nYou can check whether the dependencies are installed using:\n\n```\n$ ./local/check-dependencies.sh\n```\n\nMost dependencies are easily installed using a package manager, such as `brew`.\nHowever, there are installation scripts for some dependencies, such as:\n\n```\n$ ./local/install-dependency-3proxy.sh\n```\n\n## Running the Agent\n\nTo run the agent, you'll need your Reflect account API key,\nwhich can be found on the __Settings__ page in the Reflect web UI.\n\nAdditionally, you can optionally specify the public UDP port that the agent\nwill bind to in order to listen for connections from Reflect cloud browsers.\n\nThen, run the agent using the following command usage options:\n\n```\n$ ./run-agent.sh [--local] -k \u003creflect_api_key\u003e [-p \u003cpublic_port\u003e]\n\tRuns the Reflect Agent and connects to the specified Reflect account\n\n\t--local\n\t\tRuns the agent without Docker isolation directly on the host machine.\n\t\tThis requires installing several utility program dependencies.\n\t\tSee the `local/check-dependency.sh` and `local/install...` scripts.\n\t\tNOTE: this mode requires 'sudo' since it modifies network interfaces.\n\n\t-k reflect_api_key\n\t\tThe API key for the Reflect account\n\n\t-p public_port\n\t\tThe public port on the host machine, default 10009\n```\n\nNOTE: On Windows, the bash script above will likely not work.\nTo run the agent for Windows, run the Docker command directly:\n```\ndocker run --rm --cap-add net_admin -d --name agent -e ReflectApiKey=\u003cAPI_KEY\u003e -e PublicPort=10123 -p 10123:10123/udp agent\n```\n\nThe agent will generate a new keypair when it launches and\nregister with Reflect using your account API key.\nThen, it will listen for messages from the Reflect API to learn of new agent-based browser sessions\nand establish a connection to the browser sessions directly.\n\nNOTE: Reflect only supports a single agent per account.\nAs a result, you should not run multiple agents at once.\nIn all cases, the last agent to register is the only agent that Reflect recognizes.\n\n## Stopping the Agent\n\nTo stop the agent, run:\n\n```\n$ ./stop-agent.sh\n```\n\nor, press CTRL+C to terminate the agent when you're running in `--local` mode.\n\n## Support\n\nFor questions about using the Reflect Agent with your Reflect account,\nplease email us at support@reflect.run and we'll be glad to assist.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frunreflect%2Fagent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frunreflect%2Fagent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frunreflect%2Fagent/lists"}