openwork/services/openwork-share/README.md

OpenWork Share Service (Publisher)

This is a tiny publisher service for OpenWork "share link" bundles.

It is designed to be deployed on Vercel and backed by Vercel Blob.

Endpoints

• POST /v1/bundles

  • Accepts JSON bundle payloads.
  • Stores bytes in Vercel Blob.
  • Returns { "url": "https://share.openwork.software/b/<id>" }.

• GET /b/:id

  • Returns an HTML share page by default for browser requests.
  • Includes an Open in app action that opens openwork://import-bundle with:
    • ow_bundle=<share-url>
    • ow_intent=new_worker (default import target)
    • ow_source=share_service
  • Also includes a web fallback action that opens PUBLIC_OPENWORK_APP_URL with the same query params.
  • Returns raw JSON for API/programmatic requests:
    • send Accept: application/json, or
    • append ?format=json.
  • Supports ?format=json&download=1 to download the bundle as a file.

Bundle Types

• skill
  • A single skill install payload.
• skills-set
  • A full skills pack (multiple skills) exported from a worker.
• workspace-profile
  • Full workspace profile payload (config, MCP/OpenCode settings, commands, and skills).

Required Environment Variables

• BLOB_READ_WRITE_TOKEN
  • Vercel Blob token with read/write permissions.

Optional Environment Variables

• PUBLIC_BASE_URL

  • Default: https://share.openwork.software
  • Used to construct the returned share URL.

• MAX_BYTES

  • Default: 5242880 (5MB)
  • Hard upload limit.

• PUBLIC_OPENWORK_APP_URL

  • Default: https://app.openwork.software
  • Target app URL for the Open in app action on bundle pages.

Local development

This repo is intended for Vercel deployment. For local testing you can use:

cd services/openwork-share
pnpm install
vercel dev

Quick checks

# Human-friendly page
curl -i "http://localhost:3000/b/<id>" -H "Accept: text/html"

# Machine-readable payload (OpenWork parser path)
curl -i "http://localhost:3000/b/<id>?format=json"

Notes

• Links are public and unguessable (no auth, no encryption).
• Do not publish secrets in bundles.