DEV Community: jstash

Save JSON from a cron job or GitHub Action

jstash — Sun, 18 Oct 2026 11:32:26 +0000

Save a JSON result from a scheduled job to a stable URL, then read it from a static page or another script. This guide uses jstash JSON Bins for a server report from cron or repository stats from GitHub Actions.

Create a bin once

A bin is 1 JSON document at its own URL. Create it once, then replace its contents whenever your job has a new result. The URL stays the same.

Sign in with GitHub or Google at the dashboard and create an API key. The Free plan needs no card. The key starts with js_live_…, is shown once and works on every bin in your account. Store it in an environment variable or CI secret. Never commit it or put it in front-end code.

With JSTASH_API_KEY set, create an empty bin containing {}:

curl -H "Authorization: Bearer $JSTASH_API_KEY" -d '{}' https://api.jstash.app/v1/bins

Keep both response fields: id identifies the bin for updates and url is its public read URL on j.jstash.app.

Use an API key for automation. Trial bins created without one are deleted after 7 days unless claimed. If the key is missing, a POST /v1/bins without Authorization doesn't fail: it creates a public trial bin. That's why the scripts check for a key before making requests.

Anyone with a public bin's URL can read it. Don't put secrets or personal data in it.

Save from a cron job

The example save-report.sh needs bash, curl 7.76 or later and jq. It stops with a clear message if JSTASH_API_KEY or JSTASH_BIN_ID isn't set.

It uses jq to build JSON containing the host name, a UTC timestamp and disk use percentage. Replace this with your own data.

#!/usr/bin/env bash
# Save a small JSON report to a jstash bin. Run it from cron, CI or by hand.
# Needs: bash, curl 7.76+, jq. Set JSTASH_API_KEY and JSTASH_BIN_ID first.
set -euo pipefail

: "${JSTASH_API_KEY:?Set JSTASH_API_KEY (an API key from https://app.jstash.app)}"
: "${JSTASH_BIN_ID:?Set JSTASH_BIN_ID (the id of the bin to replace)}"
API="${JSTASH_API:-https://api.jstash.app/v1}"

report="$(mktemp)"
trap 'rm -f "$report"' EXIT

# Build the document. Replace this with your own data.
jq -n \
  --arg host "$(uname -n)" \
  --arg checked_at "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --argjson disk_used_percent "$(df -P / | awk 'NR==2 {gsub("%", "", $5); print $5}')" \
  '{host: $host, checked_at: $checked_at, disk_used_percent: $disk_used_percent}' > "$report"

# PUT replaces the whole document and keeps the same URL. It's safe to retry.
# The header is read from a file descriptor, so the key never appears in `ps`.
curl --fail-with-body --silent --show-error --retry 3 \
  -X PUT \
  -H @<(printf 'Authorization: Bearer %s\n' "$JSTASH_API_KEY") \
  --data-binary @"$report" \
  "$API/bins/$JSTASH_BIN_ID"
echo

The script sends the document to https://api.jstash.app/v1/bins/$JSTASH_BIN_ID. PUT /v1/bins/{id} replaces the whole document and is safe to retry. The script uses curl's --fail-with-body --retry 3 and exits non-zero on any error, so cron logs or CI show the failure.

Bodies must be JSON. Use curl's --data-binary @file.json; plain -d @file strips newlines.

Next, configure the environment and schedule:

# ~/.jstash.env (then: chmod 600 ~/.jstash.env)
export JSTASH_API_KEY='js_live_…'
export JSTASH_BIN_ID='your-bin-id'
export PATH="/usr/local/bin:/usr/bin:/bin"  # cron's default PATH is short: add where jq lives

# crontab -e: run every 15 minutes
*/15 * * * * . "$HOME/.jstash.env" && "$HOME/bin/save-report.sh" >> "$HOME/save-report.log" 2>&1

The example stores the key and bin ID in ~/.jstash.env, made readable only by you with chmod 600. Cron starts with a minimal environment and PATH, so the cron line sources that file before running the script.

The job runs every 15 minutes and appends output and errors to ~/save-report.log. Check that log when a report stops changing.

Save from GitHub Actions

For repository stats, use the workflow. Store JSTASH_API_KEY as an Actions secret and JSTASH_BIN_ID as an Actions variable.

gh secret set JSTASH_API_KEY            # prompts for the key
gh variable set JSTASH_BIN_ID --body your-bin-id

The secret command prompts for the key. You can also set both values in Settings → Secrets and variables → Actions.

Place the workflow at .github/workflows/publish-stats.yml:

name: Publish repo stats to jstash

on:
  schedule:
    - cron: '17 * * * *' # hourly at minute 17 (UTC); GitHub can run it late
  workflow_dispatch:

permissions:
  contents: read

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - name: Build the JSON
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          gh api "repos/$GITHUB_REPOSITORY" --jq '{
            repo: .full_name,
            stars: .stargazers_count,
            forks: .forks_count,
            open_issues: .open_issues_count,
            pushed_at: .pushed_at
          }' > stats.json
          cat stats.json

      - name: Save it to jstash
        env:
          JSTASH_API_KEY: ${{ secrets.JSTASH_API_KEY }}
          JSTASH_BIN_ID: ${{ vars.JSTASH_BIN_ID }}
        run: |
          # Without a key, POST would make a public trial bin; PUT would fail. Stop early either way.
          if [ -z "$JSTASH_API_KEY" ] || [ -z "$JSTASH_BIN_ID" ]; then
            echo "Add the JSTASH_API_KEY secret and the JSTASH_BIN_ID variable to this repository." >&2
            exit 1
          fi
          curl --fail-with-body --silent --show-error --retry 3 \
            -X PUT \
            -H "Authorization: Bearer $JSTASH_API_KEY" \
            --data-binary @stats.json \
            "https://api.jstash.app/v1/bins/$JSTASH_BIN_ID"

The first step uses gh api with the built-in github.token to build stats.json from the repository's own details: stars, forks, open issues and last push. The second checks that the secret and variable exist, then saves stats.json to the bin with curl. The workflow uses permissions: contents: read.

It runs hourly at minute 17 and supports workflow_dispatch. Use the Actions tab to run it by hand for the first test.

GitHub schedules use cron syntax and run in UTC by default, with a shortest interval of every 5 minutes. Scheduled runs can be delayed at busy times or dropped under high load. The top of the hour is busiest; an odd minute like 17 helps.

Scheduled workflows run from the default branch only. In public repositories, GitHub automatically disables them after 60 days without repository activity. Use cron on your own server or another scheduler when precise timing matters.

Read it from a static site

Use the public url returned when you created the bin. This page fetches the repository stats and displays stars and open issues:

<!doctype html>
<meta charset="utf-8">
<title>Repo stats</title>
<p><span id="repo">…</span>: <span id="stars">…</span> stars, <span id="issues">…</span> open issues</p>
<script type="module">
  // A public bin's URL, exactly as jstash returned it. No key in the page: reads need none.
  const BIN_URL = 'https://j.jstash.app/your-bin-id';

  const res = await fetch(BIN_URL);
  if (!res.ok) throw new Error(`Could not load stats: HTTP ${res.status}`);
  const stats = await res.json();
  document.querySelector('#repo').textContent = stats.repo;
  document.querySelector('#stars').textContent = stats.stars;
  document.querySelector('#issues').textContent = stats.open_issues;
</script>

Set BIN_URL to your bin's public URL. The module script checks res.ok before using the response. There is no API key in the page.

Public reads need no key and aren't metered. They send Access-Control-Allow-Origin: *, so any website can fetch them. Don't send custom headers to j.jstash.app: CORS preflight isn't supported.

After a save, servers and scripts get the new copy at once. A browser reading from a website can get the old copy for up to 5 minutes. Allow for that delay when displaying the result.

Keep a history safely

To keep recent runs inside the document, append-run.sh reads /v1/bins/{id}/content with the API key, saves the ETag header, appends an entry with jq and keeps the newest 50.

for attempt in 1 2 3; do
  # Read the current document and its ETag.
  status="$(curl --silent --show-error -w '%{http_code}' \
    -H @<(printf 'Authorization: Bearer %s\n' "$JSTASH_API_KEY") \
    -D "$dir/headers" -o "$dir/current.json" \
    "$API/bins/$JSTASH_BIN_ID/content")"
  if [ "$status" != 200 ]; then
    echo "Read failed with HTTP $status:" >&2; cat "$dir/current.json" >&2; exit 1
  fi
  etag="$(awk 'tolower($1) == "etag:" {sub(/\r$/, ""); print $2}' "$dir/headers")"

  # Start a list if the bin doesn't hold one yet, append, keep the newest 50.
  jq --argjson entry "$entry" \
    '(if type == "array" then . else [] end) + [$entry] | .[-50:]' \
    "$dir/current.json" > "$dir/next.json"

  status="$(curl --silent --show-error -o "$dir/response.json" -w '%{http_code}' \
    -X PUT \
    -H @<(printf 'Authorization: Bearer %s\n' "$JSTASH_API_KEY") \
    -H "If-Match: $etag" \
    --data-binary @"$dir/next.json" \
    "$API/bins/$JSTASH_BIN_ID")"

  case "$status" in
    200) cat "$dir/response.json"; echo; exit 0 ;;
    412) echo "Bin changed since it was read; retrying ($attempt)" >&2
         sleep $((RANDOM % 3 + 1)) ;;
    *) echo "Save failed with HTTP $status:" >&2; cat "$dir/response.json" >&2; exit 1 ;;
  esac
done

It sends the updated document with If-Match and the last ETag. HTTP 412 ETAG_MISMATCH means someone else saved first: read again, reapply the change and retry. The script retries up to 3 times with a short random pause. Without this check, the last write wins. The full script is in the example repo.

This list of runs is part of your document. jstash has no version history: a replaced document can't be recovered. Keep your own copy of anything that matters.

When the data shouldn't be public

Private bins require Pro. Set X-Bin-Visibility: private when creating the bin, then read it with the API key via /content:

# Pro: create a private bin (no public URL)
curl -H "Authorization: Bearer $JSTASH_API_KEY" -H "X-Bin-Visibility: private" \
  -d '{}' https://api.jstash.app/v1/bins

# Read it with the API key
curl -H "Authorization: Bearer $JSTASH_API_KEY" https://api.jstash.app/v1/bins/<id>/content

A private bin has no public URL, and visibility can't be changed later. Keep authenticated reads in a server job or script.

Pro is US$5 a month, billed monthly. It's open to everyone; subscribe from the dashboard Plan page and cancel any time.

How often you can save

Check both daily limits and monthly allowances when choosing a schedule:

Free: 100 bins, 10 MB total, 100 KB per bin, 100 new bins a day and 1,000 updates a day.
Pro: 1,000 bins, 1 GB total, 1 MB per bin, 10,000 updates a day and private bins.
Each API key: 60 updates each minute. Daily limits reset at 00:00 UTC.
Monthly allowances per account: Free has 5,000 writes and 50,000 reads; Pro has 40,000 writes and 400,000 reads.

The monthly read allowance counts reads of private bins with an API key via /content. Reads of public bins aren't metered, whether by URL or via /content. Monthly allowances will not be enforced before 17 November 2026, and jstash will announce enforcement before it starts. Saving identical content doesn't count towards the daily update limit but still counts as a monthly write.

Every 15 minutes means 96 saves a day, about 3,000 in a month: it fits Free. Every 5 minutes is approximately 8,900 a month, over Free's monthly allowance and within Pro's. Hourly means 24 a day, about 750 a month.

Use a database for many records, queries, search or partial updates. A bin is read and replaced whole.

We ran each script, the cron line and both workflow steps against a local build of the jstash API before publishing. We haven't yet run the workflow file itself on GitHub-hosted runners.

Get an API key, then use the full example (MIT).

Also on jstash.app. OpenAI Codex wrote this jstash post without human editing. Claude, jstash’s AI assistant, assembled code, checked facts against jstash’s code and docs, and published. A separate AI reviewed code and claims. Code was tested.

Keep localStorage, add per-user sync with jstash

jstash — Sun, 18 Oct 2026 11:18:07 +0000

Your app already saves to localStorage. It loads quickly, survives a refresh and works offline. Then someone signs in on another device and their notes are missing.

Keep localStorage as the fast local copy and offline fallback. When someone signs in, sync their data to per-user cloud storage.

The request is straightforward. Choosing whose data to upload, merge or clear takes more care.

Set up per-user storage

jstash Apps stores private JSON documents per signed-in user. The browser sends the user's existing login token from Clerk, Google, Supabase Auth or Firebase Auth. jstash checks it, so each person can only read and write their own documents. There is no jstash API key in the page.

In the dashboard at app.jstash.app, choose New app, pick your login and tick Allow localhost to test locally.

The document endpoint is:

https://api.jstash.app/v1/apps/{appId}/me/{name}

PUT replaces the whole document with any JSON. GET returns it, or 404 DOC_NOT_FOUND if nothing is saved.

The Free plan includes 1 app, up to 100 users, documents up to 100 KB and 200 documents per user, with no card. Write limits are 100 saves per user per day and 500 per app per day across all users, plus a per-minute rate limit of 60 saves. The Free plan also has a monthly allowance of 5,000 writes and 50,000 reads per jstash account; these monthly allowances will not be enforced before 17 November 2026. Pro (US$5 a month) raises the limits.

Clerk was tested end to end with a Clerk development instance, and Google sign-in was tested end to end. Supabase Auth and Firebase Auth have so far only been tested with simulated tokens.

Decide what happens at sign-in

For a notes list, use this rule:

If the cloud has nothing, upload local notes.
Otherwise, load cloud notes and merge by id. If local changes have not been saved to the cloud, local notes win when ids match. Otherwise, cloud notes win.

For other data, choose an explicit merge or replace rule.

Store the user id beside the local data too. On a shared browser, a different user must never inherit the previous user's notes. Clear that local copy before loading theirs.

This example assumes each note has a unique id. It uses the starter helpers save(name, value) and load(name), plus currentUserId() from your auth library.

The starter load returns null for 404 DOC_NOT_FOUND and throws for other failures. Keep editing disabled until sign-in sync finishes, and handle rejected promises in your UI.

let timer;
let session = 0;
let ready = false;
let queue = Promise.resolve();

function queueSave(userId, run, json) {
  queue = queue.catch(() => {}).then(async () => {
    if (run !== session || currentUserId() !== userId) return;

    await save('notes', JSON.parse(json));

    if (
      run === session &&
      currentUserId() === userId &&
      localStorage.getItem('notes') === json
    ) {
      localStorage.removeItem('notes_dirty');
    }
  });

  return queue;
}

async function syncOnSignIn(userId) {
  clearTimeout(timer);
  const run = ++session;
  ready = false;

  // Let any request already sent finish before loading cloud notes.
  await queue.catch(() => {});

  if (run !== session || currentUserId() !== userId) return;

  const owner = localStorage.getItem('notes_owner');

  if (owner !== null && owner !== userId) {
    localStorage.removeItem('notes');
    localStorage.removeItem('notes_dirty');
  }

  localStorage.setItem('notes_owner', userId);
  const local = JSON.parse(localStorage.getItem('notes') || '[]');
  const dirty = localStorage.getItem('notes_dirty') === 'true';
  const cloud = await load('notes');

  if (run !== session || currentUserId() !== userId) return;

  const notes = cloud === null
    ? local
    : [...new Map(
        (dirty ? [...cloud, ...local] : [...local, ...cloud])
          .map(note => [note.id, note])
      ).values()];

  const json = JSON.stringify(notes);
  localStorage.setItem('notes', json);
  localStorage.setItem('notes_dirty', 'true');
  await queueSave(userId, run, json);

  if (run === session && currentUserId() === userId) {
    ready = true;
  }
}

function flushSave() {
  clearTimeout(timer);
  const userId = currentUserId();

  if (!userId || !ready) return;
  if (localStorage.getItem('notes_dirty') !== 'true') return;

  const json = localStorage.getItem('notes');
  if (json === null) return;

  return queueSave(userId, session, json).catch(error => {
    console.error('Cloud save failed; local notes remain.', error);
  });
}

function saveSoon(notes) {
  const userId = currentUserId();
  if (userId && !ready) return;
  if (!userId && localStorage.getItem('notes_owner') !== null) return;

  const json = JSON.stringify(notes);
  localStorage.setItem('notes', json);
  localStorage.setItem('notes_dirty', 'true');
  clearTimeout(timer);

  if (!userId) return;

  localStorage.setItem('notes_owner', userId);
  timer = setTimeout(flushSave, 2000);
}

document.addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'hidden') {
    flushSave();
  }
});

function onSignOut() {
  clearTimeout(timer);
  ++session;
  ready = false;
}

Call syncOnSignIn(userId) after sign-in, when a saved session is restored on page load, and on account changes. If it rejects, show an error and offer a retry that calls it again. Call onSignOut() as sign-out begins.

An unowned local list is treated as this device's existing data and claimed by the first account that signs in. That is a product decision: explain it if people may share the browser.

The owner stays beside the local notes after sign-out, so the next sign-in can distinguish returning users from different users. Owned notes remain in localStorage while signed out. Your app must hide them and disable editing whenever notes_owner is set and nobody is signed in, including immediately when sign-out begins. The guard in saveSoon prevents signed-out edits to owned notes; it does not hide them in your UI. Clearing a pending timeout cannot undo a request already sent.

Save after edits

Call saveSoon(notes) when notes change. When editing is allowed, it writes localStorage immediately and marks the notes as unsaved, then waits about 2 seconds before saving to the cloud if someone is signed in. Another edit restarts that wait. When the page becomes hidden, the visibilitychange handler queues any unsaved notes without waiting for the debounce. A request started then is not guaranteed to finish before the page closes.

Debounce saves instead of saving on every keystroke. Never save on a timer that runs regardless of edits. The longer debounce reduces saves, but it does not guarantee that a notes app stays within the Free write limits. Sign-in syncs and saves when the page is hidden count too.

The promise queue runs cloud saves one at a time. After each save, it clears the dirty flag only if the session still matches and the saved JSON still matches localStorage. Newer local edits stay marked as unsaved. Sign-in sync also waits for earlier saves to finish before loading cloud notes.

If a cloud request fails, including because a write limit has been reached, local notes remain available to their owner and stay marked as unsaved. Show that sync failed and provide a retry action. This snippet queues saves but does not retry failed requests automatically. A retry can call flushSave() once the limit allows another save.

localStorage reads, parsing and writes can also fail. Handle those errors in your app.

Protect changes from another device

A debounce does not prevent two devices from overwriting each other. The sample uses ordinary saves, so it still has that risk.

jstash supports conditional writes with ETags. GET returns an ETag header. Send that value with PUT using If-Match. If someone else saved first, the request returns 412 ETAG_MISMATCH.

Use that response to fetch the latest document and resolve the conflict before trying again. The list merge above cannot distinguish a deleted note from one that should be restored.

Let people delete their cloud data

Treat the cloud copy as the user's data. Give people a way to delete it: DELETE …/me removes everything that person saved. Clear the local copy too if your deletion action is meant to remove both; otherwise the next sign-in sync uploads them again.

jstash keeps no old versions.

Start with the working examples (MIT) and the docs.

OpenAI Codex wrote jstash’s post without human editing. Claude, jstash’s AI assistant, assembled code, checked facts against jstash’s code and docs, and published. Separate AI reviewed code and claims; code wasn’t run end to end.

Save per-user app data with Clerk and jstash

jstash — Thu, 15 Oct 2026 06:26:05 +0000

Your static site or single-page app already has Clerk sign-in. Next, you need to save each person's settings, drafts or progress in the cloud.

localStorage stays on one device, and clearing storage removes its contents. Clerk's user metadata is meant for small amounts of data, not app documents. The usual next step is a backend, a database and access rules for each user.

jstash Apps provides document storage for this setup. Your browser sends the signed-in person's Clerk session token. jstash checks it against your Clerk instance, and each person can only read and write their own documents.

Here's how to connect it.

1. Create a jstash app

Open the jstash dashboard at app.jstash.app and sign in with GitHub or Google.

Create an app, choose Clerk and paste your Clerk publishable key. jstash reads the Frontend API URL from that key.

Tick Allow localhost for local testing. For production, website addresses must be listed: https, exact match, up to 5.

The Free plan includes 1 app and up to 100 users, with no card.

Don't put a jstash API key in the page: it would be refused. Requests use the signed-in person's Clerk session token instead.

2. Add save and load functions

The document endpoint is:

https://api.jstash.app/v1/apps/{appId}/me/{name}

'clerk' is your Clerk instance after 'await clerk.load()' (in the example it's exported from src/clerk.js).

A PUT creates or replaces the whole document, which can be any JSON value. A GET returns it. A 404 with code DOC_NOT_FOUND means nothing has been saved yet.

Use your jstash app ID as APP_ID in the following code:

const JSTASH = `https://api.jstash.app/v1/apps/${APP_ID}/me`;

async function token() {
  const t = await clerk.session?.getToken();
  if (!t) throw new Error('Not signed in');
  return t;
}

export async function save(name, value) {
  const res = await fetch(`${JSTASH}/${name}`, {
    method: 'PUT',
    headers: { Authorization: `Bearer ${await token()}` },
    body: JSON.stringify(value),
  });
  if (!res.ok) throw await failure(res);
}

export async function load(name) {
  const res = await fetch(`${JSTASH}/${name}`, {
    headers: { Authorization: `Bearer ${await token()}` },
  });
  if (res.ok) return res.json();
  const err = await failure(res);
  if (err.code === 'DOC_NOT_FOUND') return null;
  throw err;
}

async function failure(res) {
  const { error } = await res.json()
    .catch(() => ({ error: { message: `jstash returned ${res.status}` } }));
  return Object.assign(new Error(error.message), { code: error.code });
}

Clerk tokens last 60 seconds. Get one right before each request with clerk.session.getToken(). Clerk returns the current token while it's valid, so call it for each request rather than keeping a token yourself.

Use the default session token, not a JWT template. In React, use getToken from useAuth().

Errors are JSON, with code and message inside an error object. The helper keeps the error code available to the caller. It treats DOC_NOT_FOUND as an empty starting point and throws other errors.

3. Load after sign-in, save on change

After sign-in, load the person's notes:

const notes = (await load('notes')) ?? { text: '' };

When the notes change, save them:

await save('notes', notes);

Debounce rapid edits, and drop a pending save when the user signs out.

Because save() replaces the whole document, pass the notes document you want stored, rather than just a changed field.

On Free, documents can be up to 100 KB, with 200 documents per user. Keep those limits in mind when deciding what belongs in each document.

4. Handle deletion and storage limits

For a “delete my account” flow, this request removes everything that person saved in the app:

DELETE https://api.jstash.app/v1/apps/{appId}/me

jstash keeps no old versions. A PUT or DELETE can't be undone.

Don't store sensitive personal data such as health information.

Run the working example

The working Clerk and Vite example is MIT licensed.

In the example directory, copy the environment file:

cp .env.example .env.local

Fill in VITE_JSTASH_APP_ID and VITE_CLERK_PUBLISHABLE_KEY, then run:

npm install
npm run dev

Open http://localhost:5173.

The Apps docs cover the setup.

Before choosing it for your app, keep the service's stage in mind: jstash is an early-stage, small hosted service, and it is not open source. Clerk was tested end to end with a Clerk development instance (production Clerk instances not yet tested). Google sign-in is tested end to end. Supabase Auth and Firebase Auth have so far only been tested with simulated tokens.

OpenAI Codex wrote this jstash post without human editing. Claude, jstash’s AI assistant, assembled code, checked facts against jstash’s code and docs, and published. A separate AI reviewed code and claims. Code was tested.