SweatStack Tools¶
SweatStack Tools hosts tools that run entirely in the browser, each at its own address, under one network policy that keeps a person's data in their browser and within SweatStack.
Beta
SweatStack Tools is in beta and is subject to breaking changes. If you plan to use it in production, email [email protected] before you integrate, so we can tell you about changes in advance and help you migrate.
A tool is a static site: HTML, JavaScript, CSS, WebAssembly and data files. SweatStack serves every file of every tool from https://{slug}.sweatstack.tools, and the browser enforces the same policy on all of them. Nobody who uses a tool has to trust its author with their data, because the tool cannot send it anywhere.
A tool does not have to use SweatStack data. It can read a file the person opens, software on their own computer, a Bluetooth or USB device, or nothing at all. The policy is the same.
What a tool can reach¶
| Destination | Allowed |
|---|---|
| The tool's own files, at its own address | Yes |
The SweatStack API, https://app.sweatstack.no |
Yes, with fetch |
SweatStack Maps, https://maps.sweatstack.dev |
Yes, with fetch. See Maps |
Software on the person's computer, http://localhost and http://127.0.0.1 on any port |
Yes, with fetch only, after the browser asks the person. Safari blocks it |
| Bluetooth and USB devices | Yes, in Chromium, after the person picks the device |
| Any other website: a CDN, a font service, analytics, a third-party API, a map tile host | No |
The SweatStack API and SweatStack Maps are allowed for fetch only. A <script>, a stylesheet, an image or a font from them is blocked like any other site. Everything a tool loads comes from its own files.
What SweatStack Tools does to your files¶
- Every response gets the policy's headers. A file can't change them, so
_headers,_redirectsand.htaccessare served as plain files. - SweatStack Tools signs people in before it serves a page of a tool that uses SweatStack data. See Sign-in.
- SweatStack adds two things to every HTML page: a script, first in
<head>, that makes WebRTC unavailable, and a small "Report" link in a corner of the page. A tool can't remove either. - SweatStack removes speculative loading from HTML:
<script type="speculationrules">, and<link>elements whoserelispreconnect,dns-prefetchorprerender. They would make the browser reach other sites without the policy's check. - A tool's files work only on its own address. Another site can't embed a tool's scripts, images or fonts, or read its files. A link to a tool's page works from anywhere.
- Files are revalidated on every load. Each response has
Cache-Control: no-cacheand the file's hash as itsETag, so a new deploy reaches everyone on their next load.
What a tool can't do¶
- Load anything from another site. Download each library into the tool. Dependencies shows how, including DuckDB-WASM and Pyodide.
- Use WebRTC.
new RTCPeerConnection()throwsNotSupportedError. - Sign people in itself. SweatStack Tools signs people in, and your tool reads a token from a cookie. See Sign-in.
- Call a third-party API. If your tool uses SweatStack data and needs another service, build a SweatStack app with its own hosting instead.
Using navigation, WebRTC or a helper program to send a person's data out of the browser breaks the developer terms, and SweatStack takes the tool down.
Create and deploy a tool¶
sweatstack tool create
sweatstack tool serve
sweatstack tool deploy
tool create asks for the tool's name, title, description and the data it needs, then:
- creates the tool at
https://{name}-{handle}.sweatstack.tools. On your first tool it also asks for your handle and public name. Your handle is part of every tool's address, and neither it nor a tool's name can change later. - writes
sweatstack.toml, which the other commands read. - puts a working tool in
public/: one page that signs you in, loads your latest activity's data with DuckDB-WASM, and plots it. Every file it needs is in the folder.
tool deploy checks the folder, uploads only the files that changed, and makes them live. A new tool is private: only you can open it, after signing in. To serve an earlier version again, tool deploys lists the versions SweatStack keeps, and tool rollback serves the previous one, or the one you name.
Opening a tool to everyone comes when SweatStack Tools leaves beta. Until then, every tool is private.
Every option has a flag, so an AI agent can run these commands too. tool create --help lists them.
Check a tool before you deploy it¶
Run the tool on your computer under the same policy:
sweatstack tool serve public/
tool serve sends the same headers as SweatStack Tools, except reporting and HSTS. It makes the same changes to HTML, and signs people in the same way. See Sign-in. Open the address it prints. A request that the policy blocks shows in the browser's console with its file and line.
Find what a tool loads from other sites without running it:
sweatstack tool check public/
tool check lists every reference that loads from another site, with its file, line and kind, and exits with status 1. It can't see a URL that the tool builds while it runs. tool serve shows those in the console.
tool serve and tool check are in SweatStack CLI 0.16.0 and later, and tool create, tool deploy, tool deploys and tool rollback in 0.17.0 and later.
Read a blocked request¶
The browser writes one console message for each blocked request. Chrome writes, for example:
Loading the script 'https://cdn.jsdelivr.net/npm/[email protected]/dist/uPlot.iife.min.js' violates
the following Content Security Policy directive: "script-src 'self' ...".
The quoted URL is what the tool tried to load. The directive tells you the kind of load: script-src for scripts, connect-src for fetch, img-src for images. Download the file into the tool and change the URL to a relative path.
Limits¶
- 50 MB per file.
- 99 MB and 20,000 files per tool.