svc.nz

Recipes

These recipes use capabilities to read and write existing boxes. Creating a new box or account is currently invite-only.

Agent inbox

Each agent uses an existing box with an _inbox file. Senders hold write capabilities, and the owner holds a read capability.

CI artifact handoff

CI uploads artifacts to an existing box and passes a read capability to deployment jobs.

Cron output

Each scheduled run writes its output to the same file name. Every PUT creates a separate version of that output.

Webhook receiver

A metadata-only webhook can notify a worker when a PUT arrives.

Mobile clipboard

Devices exchange text or files through an existing box using its capability token.

Model cache

A scoped read capability gives clients access to stored model weights.

Temporary file upload

A client uses PUT to upload files to an existing anonymous box before it expires.

Scoped capability handoff

A sender writes a scoped capability into the recipient's _inbox file.

Agent resume token

A worker stores its restart cursor under _resume for a replacement worker to read.

Tool-result cache

A client hashes each input to locate a stored result and avoid repeating deterministic calls.

Encrypted file transfer

The client can encrypt bytes before upload while keeping the encryption key on the client. The server stores ciphertext, and a capability controls access to those stored bytes.

Single-flight quota refresh

A PUT with If-None-Match: * lets exactly one instance claim a piece of work before any instance contacts the upstream API. That claiming PUT carries only a small marker body, so a losing instance never triggers an upstream call.

The instance that wins the claim calls the upstream API and stores the real value with a second PUT that carries no conditional header. Every losing instance sends a GET with after=1 and wait=20 so it blocks until that real value exists, and it decides for itself whether to call upstream if that wait times out. The object name carries the refresh window, because a conditional write succeeds only while the name holds no version at all, which would otherwise make a fixed name claimable exactly once rather than once per cycle.

  1. Each instance sends a PUT with If-None-Match: * and a small claim marker body, without calling the upstream API first.
  2. A 201 response means this instance won the claim. It calls the upstream API and stores the real value with a plain PUT that carries no If-None-Match header.
  3. A 412 response means another instance already claimed the work. This instance sends a GET with after=1 and wait=20 that blocks until the winner's value exists, and if that wait returns 204 the instance decides for itself whether to call upstream.
#!/usr/bin/env bash
# Every instance claims the work first; only the winner calls upstream.
CAP="$CAP_ACCESS"        # Every instance holds the capability for this box.
BOX="cachebox"

# One object per refresh window. A conditional write succeeds only while
# the name holds no version, so a fixed name is claimable exactly once.
WINDOW=$(date -u +%Y%m%dT%H)
NAME="quota-$WINDOW.json"

claim_status=$(curl -s -o /dev/null -w "%{http_code}" -X PUT \
  "https://in.svc.nz/$BOX/$NAME" \
  -H "Authorization: Capability $CAP" \
  -H "Content-Type: application/json" \
  -H "If-None-Match: *" \
  --data '{"state":"claimed"}')

if [ "$claim_status" = "201" ]; then
  quota=$(get_upstream_quota)   # Only the winner calls upstream.
  curl -s -o /dev/null -X PUT \
    "https://in.svc.nz/$BOX/$NAME" \
    -H "Authorization: Capability $CAP" \
    -H "Content-Type: application/json" \
    --data "$quota"
  echo "This instance won the claim and stored the real value."
else
  echo "Claim PUT returned $claim_status; waiting for the winner."
  body=$(mktemp)   # Instances can share a host, so do not share a path.
  wait_status=$(curl -s -o "$body" -w "%{http_code}" \
    "https://out.svc.nz/$BOX/$NAME/latest?after=1&wait=20" \
    -H "Authorization: Capability $CAP")
  if [ "$wait_status" = "204" ]; then
    echo "The wait timed out with no winner value; call upstream now."
  else
    cat "$body"
  fi
fi
$ ./refresh.sh   # Instance A claims the work and calls upstream.
This instance won the claim and stored the real value.

$ ./refresh.sh   # Instance B loses the claim and waits instead.
Claim PUT returned 412; waiting for the winner.
{"remaining":42}

One-off handoff code

The owner creates a short code for one stored object. Redeeming that code invalidates it and returns a capability for one read, plus a write capability for a reserved reply slot.

The recipient redeems the code without supplying an existing capability. The returned capabilities grant access only to the named object and the reserved reply slot.

  1. The owner creates a code for one object in an existing box.
  2. The recipient redeems the code without an existing capability.
  3. The recipient sends cap_read in the Authorization header to read the object once.
# The owner uses the box capability to create a code for report.pdf.
curl -s -X POST "https://svc.nz/api/boxes/$BOX/handoff" \
  -H "Authorization: Capability $CAP" \
  -H "Content-Type: application/json" \
  -d '{"name":"report.pdf","ttlSeconds":300,"message":"here is the report"}'
{
  "ok": true,
  "box": "hoffboxx",
  "code": "2X2AB9KGF9",
  "name": "report.pdf",
  "replyName": "_handoff/dgLwnkzmPJfd",
  "expiresAt": "2026-08-26T14:19:09.414Z"
}
# The recipient redeems the code without an Authorization header.
curl -s -X POST "https://svc.nz/api/boxes/$BOX/handoff/redeem" \
  -H "Content-Type: application/json" \
  -d '{"code":"2X2AB9KGF9"}'
{
  "ok": true,
  "box": "hoffboxx",
  "name": "report.pdf",
  "message": "here is the report",
  "cap_read": "cap_access_att_an8mtDNN3Yq6Igr520h03d8B3g09Sn_2yRjI6kERhNQ",
  "reply_name": "_handoff/dgLwnkzmPJfd",
  "cap_write": "cap_access_att_xC3wzJfsZfZu-yyck_r5IOJRLOTBHPmgAvmJAi86XGA"
}
# The recipient uses the returned capability for one read.
# A second read with the same capability returns HTTP 401.
curl -s "https://out.svc.nz/$BOX/report.pdf/latest" \
  -H "Authorization: Capability cap_access_att_an8mtDNN3Yq6Igr520h03d8B3g09Sn_2yRjI6kERhNQ"
the quarterly report bytes