Open-source, self-hostable remote control and remote access.
Website: https://controlr.app
Docker: https://hub.docker.com/r/translucency/controlr
Discussions: https://github.com/bitbound/ControlR/discussions
Project Board: https://github.com/users/bitbound/projects/1
Go to https://controlr.app and create an account.
wget https://raw.githubusercontent.com/bitbound/ControlR/main/docker-compose/docker-compose.yml
sudo docker compose up -d
At minimum, you will need to supply values for the variables at the top of the compose file. By default, they're expected to be passed in via the environment variables shown to the right of the variables.
See the comments in the compose file for additional configuration info.
Afterward, ControlR should be available on port 5120 (by default). Running curl http://127.0.0.1:5120/health should return "Healthy".
Some ControlR features require forwarded headers. These concepts are not unique to ASP.NET Core, so it's important to understand them when self-hosting.
When using a reverse proxy, including Cloudflare proxying, the proxy IPs must be trusted by the service receiving the forwarded traffic. By default, ControlR will trust the Docker gateway IP. If EnableCloudflareProxySupport option is enabled, the Cloudflare IP ranges will automatically be trusted too.
Every proxy server IP needs to be added to the X-Forwarded-For header, creating a chain of all hops until it reaches the service that handles the request. Each proxy server in the chain needs to trust all IPs that came before it. When the request reaches the servce, the header should have a complete chain of all proxy servers.
If you have another reverse proxy in front of Docker (e.g. Nginx, Caddy, etc.), it must trust the IPs of any proxies that came before it (e.g. Cloudflare). Likewise, your service in Docker (i.e. ControlR) must also trust the IP of your reverse proxy. If the reverse proxy is on the same machine as the service, and is forwarding to localhost, the service will automatically trust it.
Additional proxy IPs can be added to the KnownProxies list in the compose file.
If the public IP for your connected devices are not showing correctly, the problem is likely due to a misconfiguration here.
By default, the server is single-tenant. The first user created will be the server and tenant administrator, and subsequent accounts must be explicitly created by the tenant admin.
Setting ControlR_AppOptions__EnablePublicRegistration to true in the compose file will allow anyone to create a new account on the server. A new tenant is created for each account that is created this way.
The database uses EF Core's Global Query Filters feature to isolate tenant data (devices, users, etc.);
- Remote control
- Terminal uses PowerShell 7+ (pwsh.exe) if detected, otherwise PowerShell 5.1 (powershell.exe)
- No remote control
- Terminal uses Bash
Permissions are implemented via a combination of role-based and resource-based authorization. When the first account is created, all roles are assigned. Subsequent accounts must be explicitly assigned roles.
To access a device, a user must have either the DeviceSuperuser role or a matching tag. Tags can be assigned to both users and devices to grant access.
Role Descriptions:
AgentInstaller- Able to deploy/install the agent on new devices
DeviceSuperuser- Able to access all devices
TenantAdministrator- Able manage users and permissions for the tenant
ServerAdministrator- Able to manage and see stats for the server
- This does not allow access to other tenants' devices or users
Logs, traces, and metrics will be sent to the Aspire Dashboard container. The web interface is exposed on port 18888, and it's secured by the aspireToken value.
The dashboard also supports OpenIdConnect authentication. See their readme for more information.
You can also add a connection string for Azure Monitor to see your data there. This can be used in combination with the Aspire Dashboard (OTLP) or on its own.
ControlR has the ability to integrate with another of my projects (WebSocketBridge) and transfer remote control sessions to a server closest to you. See the comments in the Docker Compose file for configuration information.
Relay servers are currently disabled on the public server (https://controlr.app), which is located in Seattle, WA.
