TogetherHelp

TogetherHelp is a small self-hosted helper for colleague-to-colleague support in Windows Remote Desktop / Citrix environments.

A user who needs help creates a short one-time code. A permitted helper enters that code. TogetherHelp resolves the target Windows server, user and session ID and starts the built-in Windows Remote Assistance client (msra.exe /offerra). The person receiving help must explicitly approve the connection and remote control.

TogetherHelp does not implement a remote-desktop protocol and the broker never receives screen contents, keyboard input or mouse input.

Components

• Windows client: C# / WinForms / .NET 10
• Broker: C# / ASP.NET Core / .NET 10
• Deployment: Docker + any HTTPS reverse proxy
• Remote-control transport: Windows Remote Assistance

Flow

1. The requester starts TogetherHelp.exe inside their Windows/Citrix session.
2. The requester chooses Create connection code.
3. The broker stores a short-lived mapping of server + user + session and returns an 8-digit code.
4. A helper enters the code in the same client.
5. The code is consumed once and the broker returns the target metadata.
6. The helper client starts:

msra.exe /offerra <server> "<DOMAIN\\user>:<session-id>"

7. Windows asks the target user to approve the support session.

Security model

• 8-digit cryptographically random one-time codes
• default lifetime: 5 minutes
• codes are stored only as HMAC-SHA256 values
• all pending requests are kept only in RAM
• broker restart intentionally invalidates every pending code
• rate limiting is enabled
• allowed server names can be restricted by regular expression
• the broker has no remote-control capability itself
• Windows policy decides which AD users/groups may offer assistance
• the target user must explicitly approve Remote Assistance

Important limitation

The MVP broker does not authenticate API clients. Deploy it only behind an HTTPS reverse proxy and preferably restrict access to trusted internal networks/VPN. Do not expose the broker directly to the public Internet without adding authentication and stronger abuse controls.

Broker logs contain Windows user identities and session metadata. Treat those logs according to your organization's privacy and retention policy.

Quick start

1. Windows policy

Configure Offer Remote Assistance on all Windows session hosts and allow a dedicated helper group. See docs/windows-gpo.md.

2. Broker

cp .env.example .env
openssl rand -base64 48
# put the generated value into CODE_PEPPER in .env

docker compose up -d --build
curl http://127.0.0.1:8095/healthz

Add the example reverse-proxy configuration from deploy/nginx-example.conf to your HTTPS virtual host.

3. Client

Set the broker URL, then run the client:

$env:TOGETHERHELP_API = 'https://support.example.org/remote-assistance/api/'
.\TogetherHelp.exe

For build and deployment details see docs/deployment.md.

Build

The repository includes GitHub Actions for the Windows client and broker. Locally:

dotnet build src/TogetherHelp.Broker/TogetherHelp.Broker.csproj -c Release

Windows client:

dotnet publish src/TogetherHelp.Client/TogetherHelp.Client.csproj `
  --configuration Release `
  --runtime win-x64 `
  --self-contained true `
  --output artifacts/client

Scope

TogetherHelp is intended for interactive, consent-based support. It is not intended for unattended access, hidden monitoring, privilege elevation, or endpoint administration.

License

Apache License 2.0.