{"id":43388402,"url":"https://github.com/my-devices/sdk","last_synced_at":"2026-02-02T12:02:50.357Z","repository":{"id":62631787,"uuid":"67033141","full_name":"my-devices/sdk","owner":"my-devices","description":"macchina.io REMOTE provides secure remote access via web (HTTP), shell (SSH), remote desktop (VNC, RDP) and other protocols to IoT devices behind routers or firewalls. No port forwarding, scarce public IPv4 addresses, or complex and inflexible VPNs required. This SDK contains the Device Agent and client tools.","archived":false,"fork":false,"pushed_at":"2026-01-12T12:23:46.000Z","size":8586,"stargazers_count":45,"open_issues_count":0,"forks_count":16,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-01-12T19:40:43.117Z","etag":null,"topics":["edge-device","iot","iot-device","poco-libraries","remote-access","sdk","tunnel-connection","tunneling","tunneling-client","virtual-private-internet"],"latest_commit_sha":null,"homepage":"https://macchina.io/remote.html","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/my-devices.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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":"2016-08-31T11:55:53.000Z","updated_at":"2026-01-12T12:23:50.000Z","dependencies_parsed_at":"2024-11-10T14:20:00.011Z","dependency_job_id":"662530a9-a972-44c4-a362-8d0c7812c06d","html_url":"https://github.com/my-devices/sdk","commit_stats":null,"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/my-devices/sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/my-devices%2Fsdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/my-devices%2Fsdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/my-devices%2Fsdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/my-devices%2Fsdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/my-devices","download_url":"https://codeload.github.com/my-devices/sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/my-devices%2Fsdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29012204,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-02T10:37:29.253Z","status":"ssl_error","status_checked_at":"2026-02-02T10:37:28.644Z","response_time":58,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["edge-device","iot","iot-device","poco-libraries","remote-access","sdk","tunnel-connection","tunneling","tunneling-client","virtual-private-internet"],"created_at":"2026-02-02T12:02:49.484Z","updated_at":"2026-02-02T12:02:50.351Z","avatar_url":"https://github.com/my-devices.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# The macchina.io REMOTE SDK and Tools\n\n## About macchina.io REMOTE\n\n[macchina.io REMOTE](https://macchina.io/remote) provides secure remote access to connected devices\nvia HTTP or other TCP-based protocols and applications such as secure shell (SSH),\nsecure file transfer (SFTP), Virtual Network Computing (VNC) or remote desktop (RDP).\nWith macchina.io REMOTE, any network-connected device\nrunning the macchina.io REMOTE Device Agent software (`WebTunnelAgent`, contained in this SDK)\ncan be securely accessed remotely over the internet from browsers, mobile apps, desktop,\nserver or cloud applications.\n\nThis even works if the device is behind a NAT router, firewall or proxy server.\nThe device becomes just another host on the internet, addressable via its own URL and\nprotected by the macchina.io REMOTE server against unauthorized or malicious access.\nmacchina.io REMOTE is a great solution for secure remote support and maintenance,\nas well as for providing secure remote access to devices for end-users via web or\nmobile apps.\n\nVisit [macchina.io/remote](https://macchina.io/remote) to learn more and to register for a free account.\nSpecifically, see the [Getting Started](https://macchina.io/remote_signup.html) page and the\n[Frequently Asked Questions](https://macchina.io/remote_faq.html) for\ninformation on how to use this SDK and the included `WebTunnelAgent` executable.\n\nThere is also a [blog post](https://macchina.io/blog/?p=257) showing step-by-step instructions to connect a Raspberry Pi.\n\n\n## About This SDK\n\nThe macchina.io REMOTE SDK is based on the\n[POCO C++ Libraries](https://pocoproject.org). You may want to read README_POCO\nas well as it contains important information regarding the directory structure\nand the build system of the SDK.\n\nThe SDK contains the `WebTunnel` library, which implements the tunnel protocol used by macchina.io REMOTE.\nFurthermore, the following executables are included:\n\n  - [`WebTunnelAgent`](WebTunnel/WebTunnelAgent/README.md): This executable, also known as\n    **macchina.io REMOTE Device Agent**, runs on the device and creates the secure tunnel between the device\n    and the macchina.io REMOTE server. This is the most important component of the macchina.io REMOTE SDK.\n  - [`remote-client`](WebTunnel/WebTunnelClient/README.md): This executable can run on a client machine\n    (Windows, macOS or Linux) to create a secure tunnel from the client machine to the remote device, via\n    the macchina.io REMOTE server. It is required for tunneling TCP-based protocols not directly supported by\n    macchina.io REMOTE, such Modbus/TCP, OPC-UA, database connections, etc.\n  - [`remote-ssh`](WebTunnel/WebTunnelSSH/README.md): This is a variant of `remote-client` that first\n    creates a tunnel connection from your local machine (Windows, macOS or Linux) to the remote device,\n    then launches a SSH client using that tunnel connection.\n  - [`remote-scp`](WebTunnel/WebTunnelSCP/README.md): This is a variant of `remote-client` that first\n    creates a tunnel connection from your local machine (Windows, macOS or Linux) to the remote device,\n    then launches a SCP (Secure/SSH File Copy) client (`scp`) using that tunnel connection.\n  - [`remote-sftp`](WebTunnel/WebTunnelSFTP/README.md): This is a variant of `remote-client` that first\n    creates a tunnel connection from your local machine (Windows, macOS or Linux) to the remote device,\n    then launches a SFTP (Secure/SSH File Transfer Protocol) client using that tunnel connection.\n  - [`remote-vnc`](WebTunnel/WebTunnelVNC/README.md): This is a variant of `remote-client` that first\n    creates a tunnel connection from your local machine (Windows, macOS or Linux) to a remote device\n    running a VNC (Virtual Network Computing) server, then launches a VNC remote desktop client using\n    that tunnel connection.\n  - [`remote-rdp`](WebTunnel/WebTunnelRDP/README.md): This is a variant of `remote-client` that first\n    creates a tunnel connection from your local machine (Windows, macOS) to a remote Windows device\n    (which must have the remote desktop feature enabled), then launches a Microsoft Remote Desktop (RDP)\n    client using that tunnel connection.\n\nThere are also [`WebTunnelAgentLib`](WebTunnel/WebTunnelAgentLib/README.md) and \n[`WebTunnelClientLib`](WebTunnel/WebTunnelClientLib/README.md), which provide the functionality of \n`WebTunnelAgent` and `remote-client`, respetively, in a C API, suitable for integration into applications (not written in C++).\n\nThe macchina.io REMOTE SDK, like the [POCO C++ Libraries](https://github.com/pocoproject/poco) the SDK is based on, \nis licensed under the [Boost Software License](https://spdx.org/licenses/BSL-1.0).\n\n\n## Pre-Built Executables\n\nPre-built executables for Windows, macOS and some Linux distributions\n(including Raspberry Pi OS) are available from the [macchina.io website](https://macchina.io/remote_downloads.html).\n\n\n## Easy Install from Source (Linux and macOS)\n\nThe easiest way to install the above mentioned executables on a Linux or macOS system\nfrom source is to download and run the\n[installer script](https://github.com/my-devices/agent-installer/blob/master/install.sh)\nwith the following command:\n\n```\n$ curl https://raw.githubusercontent.com/my-devices/agent-installer/master/install.sh | bash\n```\n\nThe script should work on most Debian and RedHat-based Linux distributions including\nUbuntu and Raspberry Pi OS. On macOS, [Homebrew](https://brew.sh) must be installed.\n\nThe script will install all required dependencies, then get the sources from\nGitHub and run the steps necessary (see below) to build and install the binaries in `/usr/local/bin/`.\n\nIf you do not want to or cannot run the installer script, please see the following\ninstructions.\n\n\n## External Dependecies\n\n### Libraries\n\nThe macchina.io REMOTE SDK requires OpenSSL 1.0 or newer\non Linux and macOS systems.\nWe recommend using OpenSSL version 1.1.1l or newer (including OpenSSL 3).\n\nMost Unix/Linux systems already have OpenSSL preinstalled. If your system\ndoes not have OpenSSL, please get it from \u003chttps://www.openssl.org\u003e or\nanother source. You do not have to build OpenSSL yourself - a binary\ndistribution is fine. For example, via Debian APT:\n\n```\n$ apt-get install openssl libssl-dev\n```\n\nOn macOS, the easiest way to install OpenSSL is via [Homebrew](https://brew.sh):\n\n```\n$ brew install openssl\n```\n\nOn Windows, OpenSSL is optional. The default (with CMake) is to build using\nWindows native SSL/TLS support. However, it's also possible to use OpenSSL instead.\nThe easiest way to install OpenSSL on Windows is to use a binary\n(prebuild) release, for example the one from Shining Light\nProductions that comes with a\n[Windows installer](https://www.slproweb.com/products/Win32OpenSSL.html).\n\n### Toolchain\n\nA C++ compiler (C++14 or newer) is required to build the SDK and applications.\nThe system's default compiler (gcc on Linux, clang on macOS) should be fine on\nreasonably recent systems.\nOn Windows, Visual C++ is recommended (any version from 2015 to 2019 will do).\n\n[CMake](https://cmake.org) 3.2 (or newer) is the recommended way to build the SDK.\n\n### Installing All Dependencies (Linux and macOS)\n\nAll dependencies can be installed with the following commands:\n\n#### Debian Linux (including Ubuntu and Raspberry Pi OS)\n\n```\n$ sudo apt-get -y update \u0026\u0026 sudo apt-get -y install git g++ make cmake libssl-dev\n```\n\n#### RedHat Linux\n\n```\n$ sudo yum install -y git gcc-c++ make cmake3 openssl-devel\n```\n\n#### macOS (with Homebrew)\n\n```\n$ brew install cmake openssl\n```\n\n## Building with CMake (Linux, macOS, Windows)\n\n[CMake](https://cmake.org) (version 3.2 or newer) is the recommended build system for\nbuilding the macchina.io REMOTE SDK.\n\n```\n$ git clone https://github.com/my-devices/sdk.git\n$ cd sdk\n$ mkdir cmake-build\n$ cd cmake-build\n$ cmake ..\n$ cmake --build . --config Release\n```\n\nOn macOS, it's necessary to tell CMake where to find the OpenSSL headers\nand libraries by setting the `OPENSSL_ROOT_DIR` CMake variable.\nFor example, if OpenSSL 1.1.x has been installed with Homebrew,\nthe `cmake` invocation becomes:\n\n```\n$ cmake .. -DOPENSSL_ROOT_DIR=/usr/local/opt/openssl\n```\n\nOn an Apple Silicon Mac, Homebrew installs packages in `/opt/homebrew`,\nso the command becomes:\n\n```\n$ cmake .. -DOPENSSL_ROOT_DIR=/opt/homebrew/opt/openssl\n```\n\nIf you want to link statically with OpenSSL libraries (recommended on\nmacOS), add the `-DOPENSSL_USE_STATIC_LIBS=TRUE` option, e.g.:\n\n```\n$ cmake .. -DOPENSSL_ROOT_DIR=/usr/local/opt/openssl@1.1 -DOPENSSL_USE_STATIC_LIBS=TRUE\n```\n\nOther common ways of building with CMake (e.g., `cmake-gui`) will also work.\n\nThere are also a number of project-specific CMake variables that can be changed,\ne.g., to build with OpenSSL on Windows.\n\n\n### Cross-Compiling\n\nWith a proper CMake toolchain file (specified via the `CMAKE_TOOLCHAIN_FILE` CMake variable),\nthe SDK can be cross-compiled for embedded Linux systems:\n\n```\n$ cmake .. -DCMAKE_TOOLCHAIN_FILE=/path/to/mytoolchain.cmake -DCMAKE_INSTALL_PREFIX=/path/to/target\n```\n\nIf the cross-compiling toolchain does not contain OpenSSL, you'll also have to build\nit prior to building this project. See [Cross Compiling with CMake](https://github.com/my-devices/sdk/wiki/Cross-Compiling-with-CMake)\nfor instructions.\n\nNote: The resulting executables may contain debug information, which significantly\nincreases their size.\nYou should run `xxx-yyy-linux-strip` on the resulting executables to reduce their\nsize before deploying them to the device.\n\nNOTE: See [README_iOS.md](README_iOS.md) for iOS builds \nand [README_Android.md](README_Android.md) for Android builds.\n\n### Installing\n\nThe SDK can be optionally be installed by building the `install` target. However,\nin most cases this is not necessary. The resulting executables in the `cmake-build/bin`\ndirectory are statically linked per default and can be moved to any directory desired.\n\nIf required, the SDK header files and libraries can be installed with:\n\n```\n$ sudo cmake --build . --target install\n```\n\nThe default install location is `/usr/local/` on Linux and macOS and\n`C:\\Program Files (x64)\\` on Windows and can be overridden by setting\nthe `CMAKE_INSTALL_PREFIX` CMake variable.\n\n_WARNING_: Be careful when installing to the default location if you also\nhave the POCO C++ Libraries installed there, as both install locations are\nthe same. If you need to install (e.g., in order to build the Remote\nManager Gateway), specify an appropriate `CMAKE_INSTALL_PREFIX`.\n\n\n## Building on Linux and macOS with GNU Make\n\nIn addition to CMake, the GNU Make based build system from the\nPOCO C++ Libraries is also supported.\n\n### The Easy Way\n\nThe easy way to build the SDK on Linux or macOS is to run the\n`buildsdk.sh` script:\n\n```\n$ git clone https://github.com/my-devices/sdk.git\n$ cd sdk\n$ ./buildsdk.sh\n```\n\nIt will make the necessary invocations of\nthe configure script and GNU make to build `WebTunnelAgent` and\nthe client command-line tools, along with the required libraries. With this\nbuild, the required POCO libraries (`Foundation`, `Net`, `Util`, `WebTunnel`,\n`Crypto` and `NetSSL_OpenSSL`) will be linked statically into the final\napplications. If you don't want this, because you want to use other\nparts of POCO in your project and link the shared libraries, you'll\nhave to run the necessary commands manually. You'll also have to\ndo a manual build if your target does not have OpenSSL.\n\nThe resulting executables will be located in the *bin* directory.\n\nFor cross-compiling for an embedded platform, pass the name of a\nbuild configuration to the `buildsdk.sh` script. For example, to build\nfor Angstrom:\n\n```\n$ ./buildsdk.sh Angstrom\n```\n\nSee the build/config directory for available build configurations. If\nthere's no build configuration that fits your target, you'll have to\ncreate one yourself. This is best done by copying an existing one,\nmaking the necessary changes (typically, changing the name of the\ncompiler and linker executables to match your particular toolchain,\nand modifying compiler/linker settings if necessary).\nSpecify the name of your new build configuration in the call to `buildsdk.sh`.\n\nFor more information regarding the build system, see the POCO C++\nLibraries documentation at \u003chttps://docs.pocoproject.org/\u003e.\n\nA final note: `buildsdk.sh` only builds the release configuration.\nIf you need a debug build, see below.\n\n\n### Customizing The SDK Build\n\nTo customize the SDK build, invoke the configure script and GNU make\nmanually, as described in README_POCO.\n\n```\n$ ./configure --cflags=-DPOCO_UTIL_NO_XMLCONFIGURATION --no-tests --no-samples --static\n$ make -s -j8 DEFAULT_TARGET=static_release\n$ export POCO_BASE=`pwd`\n$ cd WebTunnel/WebTunnelAgent\n$ make -s DEFAULT_TARGET=shared_release\n```\n\nA few notes on the arguments:\n\n  * `--cflags=-DPOCO_UTIL_NO_XMLCONFIGURATION` instructs the build system to omit support\n    for XML configuration files. The result is that the PocoXML library does not\n    need to be linked into the application, saving a few 100Ks of executable size.\n  * `--no-tests` and `--no-samples` instruct the build system not to build the\n    POCO sample applications and the testsuites.\n  * `--static` instructs the build system to build static libraries.\n  * `DEFAULT_TARGET=static_release` instructs the build system to only build\n    the release configuration.\n  * `DEFAULT_TARGET=shared_release` (in the second call to GNU make for building the\n    `WebTunnelAgent` and command-line client executables) instructs the build system to\n    link against the shared runtime libraries (C and C++ standard libraries, OpenSSL),\n    but use the static POCO libraries (since only these are available).\n  * `WEBTUNNEL_ENABLE_TLS=1` enables SSL/TLS support for WebTunnelAgent and\n    the command-line client tools.\n\nIf your system does not have OpenSSL, run configure and GNU make as follows:\n\n```\n$ ./configure --cflags=-DPOCO_UTIL_NO_XMLCONFIGURATION --omit=Crypto,NetSSL_OpenSSL --no-tests --no-samples --static\n$ make -s -j8 DEFAULT_TARGET=static_release\n$ export POCO_BASE=`pwd`\n$ cd WebTunnel/Agent\n$ make -s WEBTUNNEL_DISABLE_TLS=1 DEFAULT_TARGET=shared_release\n```\n\nFor a cross-build for an embedded target, you must specify the build configuration in the\ncall to `./configure` and the final call to GNU make.\n\n```\n$ ./configure --cflags=-DPOCO_UTIL_NO_XMLCONFIGURATION --no-tests --no-samples --static --config=Angstrom\n$ make -s -j8 DEFAULT_TARGET=static_release\n$ export POCO_BASE=`pwd`\n$ cd WebTunnel/WebTunnelAgent\n$ make -s POCO_CONFIG=Angstrom DEFAULT_TARGET=shared_release\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmy-devices%2Fsdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmy-devices%2Fsdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmy-devices%2Fsdk/lists"}