How It Works

  • Sandstorm's server-side sandboxing is based on the same underlying Linux kernel features as LXC and Docker. We use the system calls directly for finer-grained control.
  • The kernel attack surface is reduced using seccomp-bpf to block system calls.
  • procfs, sysfs, etc. are not mounted in the sandbox, and only a minimal set of devices are available.
  • (Planned) On the client side, apps run in a sandboxed iframe employing the Content-Security-Policy header to prevent them from sending any kind of network communication to any server other than their own.
  • All communication between the sandboxed server and the outside world takes place through a single Cap'n Proto RPC socket which the app's root process receives as file descriptor #3. We've provided a program, sandstorm-http-bridge, which can receive HTTP-over-RPC requests on this socket and proxy them to a regular HTTP server running in the sandbox.
  • Every object (e.g., each document) that you create with an application runs in a separate isolated sandbox. We sandbox per-object rather than per-app so that it is easy and safe to share one object without also sharing everything created using the same app.
  • An application package (.spk file) is essentially an archive containing an entire chroot environment in which the application runs.
  • The application runs with the contents of its package mounted read-only, so that multiple instances of the same app can share disk space for the package.
  • The application may store persistent state in the /var directory.
  • App servers are aggressively killed off as soon as the user closes the browser tab, then restarted when the user returns later.
  • Packages are cryptographically signed. Packages signed with the same key represent versions of the same app, and are thus allowed to replace older versions -- although the user must still confirm these upgrades.

To read more about how Sandstorm works from an system administrator's perspective, see the Sandstorm administrator's guide.

HTTP Communication Overview

While web clients speak HTTP to Sandstorm, all communications between Sandstorm and the grain occur over the Cap'n Proto WebSession format. With existing applications, the Sandstorm HTTP bridge is used to translate between Cap'n Proto and HTTP.

communication_overview_http_app cluster_sandstorm Sandstorm cluster_grain Grain client Web client (eg. browser) proxy Proxy (proxy.js) client--proxy websession WebSession Serialization (HTTP over Cap'n Proto, web-session.capnp) proxy--websession bridge Sandstorm HTTP Bridge (sandstorm-http -bridge.c++) websession--bridge app HTTP App bridge--app

When an application can speak Cap'n Proto directly to Sandstorm, the HTTP bridge is not needed.

communication_overview_native_app cluster_sandstorm Sandstorm cluster_grain Grain client Web client (eg. browser) proxy Proxy (proxy.js) client--proxy websession WebSession Serialization (HTTP over Cap'n Proto, web-session.capnp) proxy--websession app Native Sandstorm App (speaks Cap'n Proto ) websession--app