If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/immense/Remotely shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 1y ago

• 5 active contributors
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 1y ago
• ⚠ Single-maintainer risk — top contributor 84% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live immense/Remotely repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/immense/Remotely.

What it runs against: a local clone of immense/Remotely — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in immense/Remotely | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 538 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of immense/Remotely. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/immense/Remotely.git
#   cd Remotely
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of immense/Remotely and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "immense/Remotely(\\.git)?\\b" \\
  && ok "origin remote is immense/Remotely" \\
  || miss "origin remote is not immense/Remotely (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Agent/Program.cs" \\
  && ok "Agent/Program.cs" \\
  || miss "missing critical file: Agent/Program.cs"
test -f "Agent/Services/AgentHubConnection.cs" \\
  && ok "Agent/Services/AgentHubConnection.cs" \\
  || miss "missing critical file: Agent/Services/AgentHubConnection.cs"
test -f "Desktop.Core/Conductor.cs" \\
  && ok "Desktop.Core/Conductor.cs" \\
  || miss "missing critical file: Desktop.Core/Conductor.cs"
test -f "Desktop.Core/Services/ScreenCaster.cs" \\
  && ok "Desktop.Core/Services/ScreenCaster.cs" \\
  || miss "missing critical file: Desktop.Core/Services/ScreenCaster.cs"
test -f "Agent/Services/ScriptExecutor.cs" \\
  && ok "Agent/Services/ScriptExecutor.cs" \\
  || miss "missing critical file: Agent/Services/ScriptExecutor.cs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 538 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~508d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/immense/Remotely"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Remotely is a .NET 8 + Blazor + SignalR-based remote desktop and scripting platform that lets operators control and script Windows, Linux, and macOS machines from a centralized web UI. It solves the problem of managing multiple devices across platforms with a unified control surface, handling real-time communication via SignalR and supporting both interactive remote control and unattended script execution. Modular monorepo structure: Agent/ contains the cross-platform client agent (Windows/Linux/macOS subdirectories with platform-specific implementations), Server/ (inferred from SignalR/Blazor setup) hosts the web UI and hub logic, with shared services for device info generation, script execution (PsCoreShell, ExternalScriptingShell), and chat. Configuration and logging handled via ConfigService and FileLogsManager.

Systems administrators and DevOps engineers who need to manage heterogeneous device fleets (Windows/Linux/macOS) remotely and execute scripts at scale without installing multiple tools. Also relevant for MSP/RMM vendors looking for an open-source alternative to commercial remote management solutions.

Production-ready and actively maintained. The codebase is substantial (1.5M+ lines of C#, organized CI/CD via Azure Pipelines and GitHub Actions, comprehensive test workflows), with multi-platform support and Docker deployment ready. Recent activity visible in Azure Pipeline and GitHub Actions setups indicates ongoing development and bug fixes.

Single-maintainer risk is present (immense/immybot organization), though the codebase is well-structured. Network security configuration is complex—the README explicitly warns that only Caddy is supported as a reverse proxy due to forwarded header handling complexity, and misconfiguration could expose security issues. No obvious stale dependencies indicated, but cross-platform support (Windows/Linux/macOS) means platform-specific bugs can be subtle.

CI/CD pipelines active for both release builds (Azure Pipelines) and pull request validation (GitHub Actions: build.yml, run_tests.yml). The presence of .gitmodules suggests integration with external modules. Power management features (WakeOnLanService) and chat functionality (ChatClientService, ChatSession) appear to be recent or ongoing work areas.

Check README for instructions.

Daily commands: Server: dotnet run --project Server/Server.csproj (assumes SQL Server or configured database in appsettings.json). Agent: dotnet run --project Agent/Agent.csproj connects via AgentHubConnection to the server hub. Docker (recommended): docker-compose up -d from docker-compose directory. Access server UI at configured HTTPS endpoint (Caddy reverse proxy included in docker-compose).

• Agent/Program.cs — Agent entry point that initializes dependency injection, configuration, and the SignalR hub connection—all agent nodes must understand this bootstrap sequence.
• Agent/Services/AgentHubConnection.cs — Core SignalR client orchestrating bidirectional communication between agent and server; essential for understanding the remote control protocol.
• Desktop.Core/Conductor.cs — Desktop viewer/caster orchestrator managing screen capture, input injection, and file transfer—the central coordinator for remote desktop sessions.
• Desktop.Core/Services/ScreenCaster.cs — Screen capture and streaming service that encodes frames and sends them to viewers; critical for understanding video transmission.
• Agent/Services/ScriptExecutor.cs — Script execution engine handling PowerShell/Bash invocation and result streaming; required for remote scripting feature comprehension.
• Desktop.Core/Services/DtoMessageHandler.cs — Dispatcher for deserialized remote command DTOs to appropriate handlers; key to understanding message routing and extensibility.
• Agent/Services/ConfigService.cs — Configuration management for agent settings, connection strings, and persistence; foundation for customization and deployment.

Add a new remote script command

1. Define command DTO in shared models (e.g., MyCommandDto with properties) (Agent/Models/ (create new file, e.g., MyCommandDto.cs))
2. Implement handler in Agent that receives the DTO and executes logic (Agent/Services/ (create handler class inheriting from base))
3. Register handler in AgentHubConnection message dispatcher (Agent/Services/AgentHubConnection.cs)
4. Add UI button/form in Blazor Server to send the command via SignalR hub method (Server/Pages/ (create Blazor component or update existing page))

Add platform-specific functionality (e.g., new OS service)

1. Create interface in Agent/Interfaces (e.g., INewFeatureService.cs) with cross-platform contract (Agent/Interfaces/INewFeatureService.cs)
2. Implement Windows version (Agent/Services/Windows/NewFeatureServiceWin.cs)
3. Implement Linux version (Agent/Services/Linux/NewFeatureServiceLinux.cs)
4. Implement macOS version (Agent/Services/MacOS/NewFeatureServiceMac.cs)
5. Register implementations in Program.cs with platform detection (Agent/Program.cs)

Add a new desktop viewer feature (e.g., clipboard sync)

1. Define interface for the feature (Desktop.Core/Interfaces/INewFeature.cs)
2. Implement core logic in Desktop.Core/Services (Desktop.Core/Services/NewFeatureService.cs)
3. Register service in Desktop.Core/ServiceContainer.cs (Desktop.Core/ServiceContainer.cs)
4. Add platform-specific implementation (Windows, Linux, macOS) (Desktop.Linux/Services/NewFeatureLinux.cs (or Desktop.Win, Desktop.Mac equivalents))
5. Hook into Conductor.cs lifecycle to initialize/cleanup the feature (Desktop.Core/Conductor.cs)

• .NET 8 + C# — Cross-platform runtime; unified codebase for agent, server, and desktop apps; strong type safety and async/await for I/O-heavy operations.
• SignalR Core — Bidirectional, low-latency WebSocket communication between server and agents; automatic reconnection and message queuing; supports both browser and .NET clients.
• Blazor Server — Interactive web UI without JavaScript; server-side event handling; seamless SignalR integration for real-time updates to control panels.
• Avalonia UI — Cross-platform desktop framework (Windows, Linux, macOS); XAML-based; supports hardware-accelerated video rendering for screen streaming.
• WebSocket + custom protocol — Low-overhead frame streaming; adaptive bitrate and compression; avoids HTTP request overhead for high-frequency screen updates.

• Agent runs as standalone .NET console app, not as OS service by default

  • Why: Simpler deployment and debugging; no service manager integration complexity.
  • Consequence: Users must manually start agent or add startup scripts; no automatic restart on crash without external tools.

• SignalR Hub for command dispatch instead of REST API

  • Why: Persistent connection allows server to push commands without polling; real-time bidirectional messaging.
  • Consequence: Increased server memory per agent connection; requires SignalR configuration tuning for scale (sticky sessions, backplane).

• Screen frames encoded in ScreenCaster before transmission

  • Why: Reduces bandwidth 10–100×; adaptive quality based on network conditions.
  • Consequence: CPU overhead on caster; requires FFmpeg or codec library; adds latency (typically <100ms).

• Platform-specific implementations for screen capture, input injection, process launching

  • Why: Leverages native APIs for performance and feature completeness (e.g., Windows GDI, Linux X11/Wayland, macOS Quartz).
  • Consequence: High maintenance burden; platform parity gaps; bugs may be platform-specific.

• Caddy-only reverse proxy support documented

  • Why: Caddy handles HTTP/2, WebSocket, and TLS seamlessly out of the box; simplifies ASP.NET Core configuration.
  • Consequence: nginx, Apache, IIS users must manually configure WebSocket and SignalR affinity; unsupported config may fail silently.

• Does not provide end-to-end encryption at the application layer (relies on HTTPS/TLS).
• Does not support connection pooling or load balancing across multiple servers without a backplane (Redis, Azure Service Bus).
• Does not include built-in user authentication or RBAC

Reverse proxy complexity: Only Caddy is supported; misconfigured X-Forwarded-{Proto,Host,For} headers will break device connectivity. Add non-standard proxy IPs to KnownProxies in Server Config or HTTPS breaks. SignalR state: AgentHubConnection holds connection state that must survive platform-specific event (suspend/wake); WakeOnLanService hints this is a known concern. Cross-platform path handling: Script execution paths differ (C:\Windows vs /usr/bin); paths in scripts may not be portable. No explicit database migration shown: Server project (not visible) likely has EF Core migrations; missing or wrong migrations will break deployment. PowerShell Core dependency: PsCoreShell assumes pwsh is in PATH; fallback to ExternalScriptingShell may silently degrade on unsupported platforms.

• SignalR Real-Time Bidirectional Communication — Remotely uses SignalR hubs for command delivery and status feedback between server and agents; understanding connection lifecycle, hub methods, and reconnection logic is essential for debugging remote control latency or connection drops
• Platform Abstraction via Interface Implementation — IAppLauncher, IDeviceInformationService, and IScriptingShell abstract platform differences; grasping this pattern is critical for adding support for new OS variants or capabilities
• X-Forwarded-* Header Forwarding in Reverse Proxies — Remotely requires X-Forwarded-Proto, X-Forwarded-Host, and X-Forwarded-For headers from reverse proxies; misconfiguration breaks agent connectivity and device IP detection, a major operational gotcha
• PowerShell Core vs External Shell Execution — PsCoreShell wraps pwsh for Windows/cross-platform scripts while ExternalScriptingShell invokes bash/sh; the factory pattern selects between them, requiring understanding of shell differences for troubleshooting script failures
• Cross-Platform Device Information Collection — DeviceInfoGeneratorBase with platform-specific subclasses (Windows/Linux/macOS) collect heterogeneous system data; understanding WMI (Windows), /proc (Linux), and system_profiler (macOS) is necessary for extending device telemetry
• Blazor Server vs WebAssembly Deployment Models — The Server project (inferred from docker-compose and SignalR presence) likely uses Blazor; deciding between server-side rendering and WASM affects latency, scalability, and offline capabilities
• Configuration Service Pattern with File Persistence — ConfigService persists agent settings (server URL, device identity, etc.) to disk; understanding config lifecycle is critical for troubleshooting agent identity loss or orphaned connections

• rustdesk/rustdesk — Direct competitor solving the same remote desktop + scripting problem, but in Rust; useful for comparing architecture and feature parity
• MeshCentral/MeshCentral — Similar open-source RMM/remote management platform written in Node.js; shares device management and scripting goals but different tech stack
• PowerShell/PowerShell — Core dependency for Windows script execution; understanding PowerShell Core integration is essential for extending script capabilities
• dotnet/aspnetcore — ASP.NET Core and Blazor framework underpinning the entire server; source of SignalR Hub patterns and Blazor component lifecycle
• caddyserver/caddy — Sole supported reverse proxy; understanding Caddy's forwarded header handling and TLS termination is critical for production deployments

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for ScriptExecutor and ScriptingShellFactory

The Agent/Services directory contains critical scripting infrastructure (ScriptExecutor.cs, ScriptingShellFactory.cs, PsCoreShell.cs, ExternalScriptingShell.cs) but no corresponding test files in the repo. Given that script execution is a core security-sensitive feature, comprehensive unit tests would catch regressions and validate behavior across Windows/Linux/MacOS platforms.

• [ ] Create Agent.Tests project (if not exists) with test structure mirroring Agent/Services
• [ ] Add unit tests for ScriptExecutor.cs covering script parsing, validation, and execution error handling
• [ ] Add unit tests for ScriptingShellFactory.cs validating correct shell selection per platform
• [ ] Add integration tests for PsCoreShell.cs and ExternalScriptingShell.cs with mocked shell processes
• [ ] Update .github/workflows/run_tests.yml to include Agent.Tests in the test suite

Add platform-specific integration tests in CI/CD pipeline

The .github/workflows/run_tests.yml exists but the file structure shows platform-specific implementations (Services/Windows, Services/Linux, Services/MacOS) for DeviceInfoGenerator, AppLauncher, and Updater. Currently, CI likely only tests on one platform. Adding matrix builds would validate each platform's implementations independently.

• [ ] Review current .github/workflows/run_tests.yml to identify existing matrix strategy
• [ ] Extend workflow with strategy.matrix for [windows-latest, ubuntu-latest, macos-latest]
• [ ] Create platform-specific test projects or conditional test classes for Windows/Linux/MacOS services
• [ ] Add tests for DeviceInfoGeneratorWin.cs, DeviceInfoGeneratorLinux.cs, DeviceInfoGeneratorMac.cs
• [ ] Add tests for UpdaterWin.cs, UpdaterLinux.cs, UpdaterMac.cs to validate platform-specific update logic

Add ChatClientService and ChatSession integration tests

Agent/Models/ChatSession.cs and Agent/Services/ChatClientService.cs represent chat functionality but lack visible test coverage. The Desktop.Core also references IChatClientService and IChatUiService interfaces. Adding comprehensive tests would validate chat session management, message routing, and client-server synchronization.

• [ ] Create test class for ChatClientService.cs covering session initialization, message queuing, and connection lifecycle
• [ ] Add tests for ChatSession.cs validating session state transitions and participant management
• [ ] Create mock implementations of dependent interfaces (IScriptingShell, IAppLauncher, etc.) for isolation
• [ ] Add integration tests validating ChatClientService interaction with AgentHubConnection.cs
• [ ] Document chat protocol expectations in Tests/ChatClientService.Tests.cs for future maintainers

• Add unit tests for ScriptingShellFactory.cs: Critical path for script execution but no test file visible; add xUnit tests covering shell selection logic for Windows (pwsh), Linux (bash), macOS (zsh/bash) scenarios
• Document IDeviceInformationService implementation checklist for new platforms: Three platform implementations exist but no checklist visible; create a CONTRIBUTING guide listing required properties (CPU, memory, OS version, etc.) that must be collected for each platform
• Add error resilience tests for AgentHubConnection reconnection: Hub connection is critical but no visible tests for SignalR disconnect/reconnect scenarios; add integration test for network interruption recovery

• High · Insufficient Input Validation in Remote Script Execution — Agent/Services/ScriptExecutor.cs, Agent/Services/PsCoreShell.cs, Agent/Services/ExternalScriptingShell.cs. The presence of ScriptExecutor.cs and multiple scripting shell implementations (PsCoreShell.cs, ExternalScriptingShell.cs) suggests execution of remote scripts. Without visible input sanitization in the file structure, there is a risk of command injection attacks where malicious scripts could be executed with elevated privileges. Fix: Implement strict input validation and sanitization for all script parameters. Use allowlists for permitted commands and scripts. Execute scripts in sandboxed environments with minimal privileges. Consider implementing code signing verification for remote scripts.
• High · Potential Unencrypted Remote Desktop Protocol Communication — Desktop.Core/Services/ScreenCaster.cs, Desktop.Core/Services/Viewer.cs, Desktop.Core/Services/CasterSocket.cs. The codebase includes ScreenCaster, Viewer, and CasterSocket services for remote desktop functionality. Without visible encryption enforcement in the file structure, there is a risk that screen capture and input data could be transmitted without proper encryption, exposing sensitive information. Fix: Enforce TLS/SSL encryption for all remote desktop communications. Implement end-to-end encryption for screen data and input events. Verify that SignalR connections use secure WebSocket (WSS) protocol exclusively in production.
• High · Missing Authentication/Authorization Validation in File Transfer — Desktop.Core/Interfaces/IFileTransferService.cs, Desktop.Core/Services/. The IFileTransferService interface suggests file transfer capabilities. Without visible authentication checks in the codebase structure, there is a risk of unauthorized file access or exfiltration. Fix: Implement robust authentication and authorization checks for all file operations. Validate user permissions before allowing file read/write operations. Implement file access logging and restrict file operations to designated directories only.
• High · Inadequate Session Management — Agent/Models/ChatSession.cs, Agent/Services/AgentHubConnection.cs, Desktop.Core/Services/CasterSocket.cs. ChatSession and multiple service connections (AgentHubConnection, CasterSocket) are present without visible session timeout and revocation mechanisms in the file structure analysis. Fix: Implement session timeout mechanisms with automatic disconnection. Create session revocation capabilities for administrators. Use secure session tokens with short expiration times. Implement proper session state management and validation.
• Medium · Potential Insecure Deserialization — Desktop.Core/Services/DtoMessageHandler.cs. The presence of DtoMessageHandler.cs and multiple service communication layers suggests data deserialization. Without visible type validation, there is a risk of insecure deserialization attacks. Fix: Implement strict type validation for all deserialization operations. Use type-safe deserialization with allowlists. Avoid using BinaryFormatter or other unsafe deserialization methods. Consider using JSON schema validation for all incoming messages.
• Medium · Missing Security Headers and Content Security Policy — Server application configuration (not fully visible in file structure). This is a Blazor/ASP.NET application with web interface. Without visible configuration files showing security header implementation, CORS, and CSP policies are likely missing or misconfigured. Fix: Implement comprehensive HTTP security headers (Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, Strict-Transport-Security). Configure CORS restrictively. Implement CSP with inline script restrictions.
• Medium · Insecure Docker Deployment Configuration — docker-compose/docker-compose.yml (referenced but not provided), README.md. Docker-compose deployment is mentioned in README with quickstart instructions. The README references Caddy as the only supported reverse proxy but appears to have incomplete documentation ('only when it is directl...'). This incomplete guidance could lead to misconfiguration. Fix: Provide complete, secure Docker configuration examples. Ensure default configurations enforce HTTPS/TLS. Validate that all services run with minimal privileges. Implement network segmentation in docker-compose files. Document security requirements comprehensively.
• Medium · Potential Privilege Escalation via App Launcher Services — undefined. Platform-specific AppLauncher implementations (AppLauncherWin Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.