GrStack / Documentation
From your first deploy
to your next release.
A practical guide to deploying sites, managing project services, and keeping control of your releases.
GrStack is also known as Stackr. This guide uses the Stackr name for CLI commands and integration URLs.
Open a free workspace with your Grasany account to deploy a prebuilt static site or managed starter. Each workspace includes three projects and 10,000 shared requests per UTC calendar month. Review a preview before sending it live.
Open a free workspace Static website hosting Migrate from Vercel
Open Workspace export to save project settings and a release inventory, or download available site ZIPs, starter configurations, records, and inquiries separately. Replace credentials at your destination using its secret store. See how Stackr handles data.
Install Stackr
Choose Install Stackr in the dashboard or use your browser’s install menu. In Safari on iPhone and iPad, choose Share, Add to Home Screen, and Open as Web App when offered.
The installed app opens Projects when you’re signed in. Switch between grid and list views, filter by project status, or open a project’s deployments or live app from its card.
Build a business site
Open Stackr Builder from your workspace. Prepare your business site, stage a release, and preview it in deployment history. Choose Make live when it’s ready.
Enable inquiries in Builder before staging a site. Once the release is live, visitors can send messages. Open Inquiries to filter by New, Contacted, or Closed and save a status after following up. You can delete inquiries or export them as CSV. Each project can hold 250 inquiries and receive up to 20 per UTC day.
Under Inquiries → Queue notifications, choose a queue for new submissions. Your worker receives type: inquiry.received, inquiryId, and receivedAt in Unix milliseconds. Names, email addresses, and messages stay in the owner inbox. Notification delivery uses the queue allowance and may wait for capacity for up to 24 hours. The inbox shows pending and skipped notifications.
For a trusted CRM worker, use Inquiries → Connect a CRM worker to issue a separate read token. Send it as a bearer credential on GET /api/inquiry-records/PROJECT_ID/INQUIRY_ID, using the ID from the job. The endpoint supports new notification jobs while they are retained and returns one inquiry per request. Tokens expire in 30 days, allow up to 100 reads per project per UTC day, and are revoked when queue notifications are disabled. Store the token in your worker’s secrets.
Publish a starter
Choose a starter for a business site, landing page, or JSON status API. Sign in with Grasany, create a project, and publish your starter. Open the project URL to see the active release.
Leave the address blank for a generated name. Enter a repository URL to use its name when available. You can change the address in the project dashboard.
Deploy from a terminal or Git CI
Install with Node.js 22 or later on Windows, macOS, or Linux. On Android, install Node.js and npm in Termux with pkg install nodejs-lts npm.
npm install -g https://stackr.grasany.com/grasany-stackr-cli-0.13.0.tgz
stackr --help
In deployment history, create a project token. Store the endpoint and token in your CI system as STACKR_DEPLOY_URL and STACKR_DEPLOY_TOKEN. Run this from a checkout of any Git host on pushes to your deployment branch.
stackr deploy launch.json --tag v1 --stage
A landing page uses this launch.json configuration.
{
"template": "landing-page-v1",
"title": "My app",
"message": "We are live."
}
Supported templates are business-site-v1, landing-page-v1, and status-api-v1. The CLI can run in GitHub Actions, GitLab CI, Bitbucket Pipelines, or another CI runner.
For a starter ZIP, archive just the root launch.json. The ZIP can be up to 64 KiB and the configuration up to 4 KiB. Upload through the dashboard Console, or run stackr deploy starter.zip --stage.
Upload a prebuilt static website
Build the site locally or in CI. From a terminal with the project deploy URL and token set, pass the build output directory containing index.html. Only include public assets in that directory. Use relative URLs for assets. For Vite, set base to ./. For single-page apps, prefer hash routing when you need relative assets to work from nested routes.
stackr launch dist --tag v1
stackr preview RELEASE_ID
stackr smoke RELEASE_ID
stackr promote RELEASE_ID
The command packages the directory and stages a preview. Use --publish to make the new release live immediately. For an existing archive, open Deployments → Upload a ZIP in your project or run stackr deploy-static site.zip. Preview the staged release before choosing Make live.
Preview links expire after 10 minutes. Each upload can contain up to 40 files, 512 KiB compressed and 1 MiB unpacked, with at most 256 KiB per file and 5 MiB retained per project. The browser sandbox supports self-contained sites with local scripts and assets.
Preview, promote and roll back
A staged release leaves live traffic on the current version. Open Details to preview it, then choose Make live. Choose Restore release on a previously published version to roll back, or Resume release on the active version of a paused project. The confirmation names the release being replaced and tells you if publication ends a traffic split. If the live release or split status changes while you review, Stackr reloads the details and asks you to confirm again. Release tags are unique within a project.
Open Deployments in the workspace navigation to search across your projects by name, address slug, release ID, tag, or Git commit. Combine search with project, state, and runtime filters. Bookmark the URL to reopen the same view.
Choose Details beside a deployment to review its state, release tag, and Git commit when available. Release activity shows up to 20 events from the project’s retained history. Both a promotion and a rollback appear as Made live. You can search the files in a static release and download them as a ZIP. The release shows the SHA-256 of the uploaded archive or the imported Git file manifest. The download is rebuilt from the retained files. Select SPA routing again if you re-upload the files for a single-page app.
In a project’s Deployments section, open Compare releases to see which files changed and how the unpacked size and SPA routing setting differ. Choose Compare with live from a staged static release to fill in both versions.
Stage a copy of a static release
Open a retained static release’s Details and choose Copy as new release. Stackr copies the retained files, Git commit and SPA setting into a private release. Give it a new tag if you want to find it by name. The copy counts toward the project’s release and storage limits. Its details link to the source release. Review the copy before publishing.
stackr copy-release RELEASE_ID --tag review-v2
To retry a CLI request after an interrupted connection, use its operation ID with --operation-id and repeat the same source and tag. The full project deploy token can stage a copy through the CLI or API.
Press Ctrl+K or ⌘+K in the workspace to find a project or open a control. On mobile, tap Search in the top bar.
stackr releases
stackr promote RELEASE_ID
stackr usage
stackr status https://YOUR_APP_URL
Browser console, API and AI tools
See Deploy with AI tools for Codex, Kiro, Gemini CLI, and browser assistant setup. The guide covers staging, testing, publishing, and rollback.
Open Console in the signed-in dashboard to run stackr commands. Press ↑ or ↓ to recall commands, or use stackr clear to clear the transcript. Open Deployment inputs for starter ZIPs and JSON configuration. Import the OpenAPI specification into tools that support authenticated HTTP actions and supply a project deploy token in the tool’s credential settings. The web dashboard handles project deletion.
To connect an MCP client, open Console, select your project, and create an Agent token. Configure the project URL below as a Streamable HTTP server and save the Agent token as its bearer credential. Use the Console to revoke access. CI uses its own deploy token.
https://stackr.grasany.com/api/projects/PROJECT_ID/mcp
MCP clients can stage a business website, landing page, or status API, list releases, and read usage. Review staged work in the dashboard before publishing.
Publish a public status link in Console to share deployed apps, monthly response bytes, requests, errors, and Stackr charges. Replace the link to revoke the previous URL or unpublish the page.
Use Console → Manage incidents to post an incident and add customer-facing updates until it is resolved. Retract an incident to remove it from the shared page. Stackr publishes only updates you post.
Build, preview, and route releases
Open Import from Git in Projects. Choose Connect GitHub when available, authorize Stackr, then pick a personal account or organization and an allowed repository. If a repository is missing, manage the GitHub App’s repository access and reload the list. Choose Use an access token instead as a fallback. GitLab.com and Bitbucket Cloud use read tokens.
Once connected, your GitHub authorization follows your Stackr account across sessions. Choose Disconnect GitHub to remove the saved connection from Stackr. GitHub may ask you to reconnect if access expires or is revoked.
After selecting a repository, open Browse branches to choose a branch and inspect its build settings. Search the branches already loaded or load more results. The public GitHub URL form also has a branch picker. Choosing a branch there stages the commit shown in the picker. You can enter a branch or commit manually when lookup is unavailable.
Stackr checks the selected branch and suggests a framework and build defaults. In a monorepo, enter the app directory and check again. Review the suggested framework, branch, install command, build command, and output directory before saving. You can edit the saved defaults in Delivery. An enabled command override left blank skips that step.
To stage a release directly, commit stackr.zip with index.html at its root, or commit a supported launch.json. Both files go at the repository root. Open Stage files from Git in Delivery, choose the file, and enter a branch or commit. The saved token needs permission to read repository contents. Review the private preview before publishing.
Deploy a static folder from Git
To deploy a site whose HTML, CSS, JavaScript, and assets are already committed, choose a dedicated folder such as public that contains index.html. From Import from Git, use the public GitHub URL option, or choose Ready-to-serve folder in a linked project’s Delivery settings. Public GitHub URLs work without a repository credential. Private repositories use the selected connection.
Stackr stages the exact commit as a private preview. Include only files you intend to publish. A folder can contain up to 20 regular web files, up to 256 KiB each and 1 MiB total. Public GitHub imports use a source archive of up to 8 MiB. Saved connections inspect up to six directory listings. For larger sites or apps that need a build, use a prepared ZIP or the generated CI workflow.
Open a project and choose Delivery to generate a GitHub Actions, GitLab CI, or Bitbucket Pipelines workflow. The workflow builds on your CI runner and stages the site's ZIP from the branch you choose. Use a protected branch. Scope STACKR_DEPLOY_TOKEN to the named deployment environment so the build job cannot access it. Add the workflow to your repository and push to that branch.
Stage GitHub pull request previews
In Delivery → Build settings and CI workflow, select GitHub Actions and a static framework. Enable Generate GitHub pull request previews. Commit both generated preview workflows to the repository’s default branch. The workflows target pull requests from branches in the same repository into the configured branch.
In GitHub, create the stackr-pr-preview environment and limit its deployment branches to the default branch. Keep changes to the staging workflow under trusted review. Create the token in Stackr and save it as the STACKR_PREVIEW_TOKEN environment secret. Tokens expire after 30 days and can be rotated or revoked in Delivery. Private repositories require a GitHub plan with environment secrets and branch rules.
The generated build workflow uses the pull request’s exact commit and passes no Stackr secrets. Keep any existing Stackr credentials in protected environments, with trusted deployment branches. The staging workflow uploads the build artifact as a private release. Its job summary links to Release Details for signed-in reviewers. Publishing remains a separate action in Stackr. Your repository’s GitHub Actions usage applies.
Environment variables
Open Environment variables in your project. Choose Preview, Production, or Development, then save the names and values your build needs. Values are encrypted and the dashboard shows only names. Create a 30-day build token for that environment.
In Delivery, select the same Stackr build environment and generate your static workflow. Store STACKR_BUILD_ENV_TOKEN as a secured variable in the displayed build environment. Use a trusted, protected branch. For Bitbucket, set the build environment type to Test so it runs before staging. For GitHub, the repository plan must support environment secrets. The staging step continues to use STACKR_DEPLOY_TOKEN separately.
Other runners can use the Node build helper. Set STACKR_BUILD_ENV_URL to https://stackr.grasany.com/api/projects/PROJECT_ID/build-environment/preview and set the corresponding build token in the runner's secret store.
node stackr-build-env-v1.mjs -- npm run build
Build code can read its variables. Keep secrets out of public framework prefixes, generated browser assets, and logs. Update your CI secret whenever you rotate a token.
Choose Vite, Astro, Next.js static export, SvelteKit static adapter, a prebuilt site, or a custom build. Set the app directory for a monorepo and the folder containing index.html. The default Vite build uses relative asset paths. For other frameworks and custom commands, configure static output and relative assets for Stackr preview URLs. Verify nested routes before publishing. You can also build on any Git host and send the ZIP with stackr deploy-static.
Stage a prebuilt ZIP from any CI provider
In a static project’s Delivery settings, download stackr-stage-preview.sh and issue a CI preview token. Store the token as STACKR_PREVIEW_TOKEN in a trusted staging job that receives a reviewed ZIP. Run with Bash, curl, jq, and the original 40-character commit SHA. The script prints an owner-only link for reviewing the new release. The preview token can stage releases and expires after 30 days.
bash stackr-stage-preview.sh site.zip "$COMMIT_SHA"
Migrate a site from another host
In Delivery, choose Migrate a site. Select Vercel, Netlify, or Cloudflare Pages to review the source project’s Git repository, build settings, and domains. Use a short-lived token. Cloudflare Pages accepts a token with Pages Read access. You can link the reviewed Git repository or upload a ZIP directly to create a private preview.
Review functions, forms, routes, and data bindings used by the existing site before you publish. Check netlify.toml for Netlify build and context overrides. For Pages, check wrangler.jsonc or wrangler.toml and any Functions routes. Test nested pages, assets, and forms in the preview before moving DNS. Vercel migration guide · Netlify configuration · Pages configuration
Review redirects, rewrites, and headers
Open Review routing rules in the migration screen. Choose or paste vercel.json, _redirects, or _headers for the selected source, up to 16 KiB per file. Review the proposed rules alongside any source entries that need manual changes. Cloudflare Pages and Netlify file formats and Vercel JSON use different matching rules. Vercel project configuration · Netlify routing · Pages redirects
Stackr can carry over compatible local redirects, static rewrites, and supported site-wide security headers. Confirm each group you want to apply. Stackr keeps your saved rules and checks their revisions before saving. Project rules take effect on live traffic. Check redirects and response headers on your published Stackr test address before switching DNS. The private ZIP preview tests the build contents.
Test routes against a staged release
In Delivery → Migrate a site → Test routes, choose a retained static release and enter up to 20 paths. Stackr checks the files in that release and shows how the saved rules and any reviewed changes would resolve each path. The results show missing rewrite targets, local redirects and their final status, folder redirects, SPA fallback, and paths blocked by traffic rules.
The check reads release metadata and project settings. It models a public browser GET request. Managed endpoints and visitor-specific IP rules need a live test, along with DNS, application behavior, and response timing. Use POST /api/projects/{projectId}/routing-import/test with the release ID, paths, and optional changes from a routing review. If a settings revision changed, run the review again.
When a managed runner is available, Managed builds can build an exact commit from the project's linked public GitHub repository and stage the output. Node and Vite builds use cached dependencies. Use your CI workflow for private repositories or builds that need network access.
Stackr can generate static CI workflows for Create React App and manually configured Nuxt 3 or 4 sites. Create React App needs a react-scripts build script. For Nuxt, set the app base for the intended host in your repository and run nuxt generate or nuxi generate. A root-based Nuxt export needs a domain rooted at the app. Stackr’s default previews are served under a path, so root-based assets may fail there.
Deploy hooks
Open Deploy hooks in a project’s Deployments tab. Choose the branch or commit and a public GitHub directory, or stage a prepared stackr.zip or launch.json using a saved Git connection. Save the URL when it appears and send it a POST without a request body from your CMS or scheduler.
A successful hook stages a private release and returns its deployment ID. Publish the release separately. Keep the URL in your service’s secret settings and revoke it from Stackr if it is exposed. If Stackr reports an unknown outcome, check Deployments before triggering again.
Release event feed
Open Release events from a project to see staged, published, failed, and removed releases and project pauses. An integration can poll the feed using its own read-only bearer token. Process events in order and save nextCursor. Pass it as after on the next GET and use the event ID to deduplicate.
The feed covers release events within the latest 100 project activity entries. If the saved cursor falls outside that window, HTTP 410 includes resetCursor. Record the gap before resuming from that cursor. Replacing or revoking the token removes access for the old token.
In project MCP, use stackr_list_release_events to read this activity with a project agent token. Pass the saved nextCursor as after and optionally set limit from 1 to 50. If the MCP tool reports release_event_cursor_expired, record the gap and resume with its resetCursor.
Send release events to a webhook
In Release events → Release webhooks, add an HTTPS endpoint on a supported vercel.app, netlify.app, or Supabase Edge Function address. Save the signing secret when it appears. Generate a verification value, then configure the receiver to return it as the exact response body on a GET with x-stackr-challenge: 1. Select Verify endpoint to start delivery for the event types you chose. A release restored to production emits release-published.
Callbacks are JSON POST requests with id, event, at, projectId, and a nullable releaseId. Use the Standard Webhooks headers to verify freshness and the HMAC-SHA256 over webhook-id.webhook-timestamp.rawBody. Decode the base64 bytes after whsec_ when importing the key. Deduplicate by webhook-id and return 2xx only after accepting the event. Standard Webhooks specification
Stackr retries HTTP 429 up to twice. Timeouts and ambiguous outcomes appear as Unconfirmed in delivery history. Respond with 429 only when you have rejected the delivery before processing. Stackr keeps up to 20 pending deliveries per endpoint and expires them after one day. Delivery attempts are limited to eight per workspace and 24 across Stackr per UTC day. Use the release event feed to reconcile missed events.
Select Rotate secret to pause a verified webhook and replace its signing secret. Save the new value, update the receiver, and resume the webhook. The endpoint and its history stay in place. Requests already in flight can still carry the previous signature. Events that occur while the webhook is paused remain available in the release event feed.
Previews and gradual rollouts
Create a named preview from an uploaded release and open it while signed in. For compatible live and candidate releases, assign a percentage of incoming traffic to the candidate. Stopping the split restores traffic to the current live release. Promoting or restoring a release ends the split automatically.
Increase traffic in stages
In Delivery → Gradual rollout, choose a candidate and a staged rollout. Use the 5%, 25%, and 50% plan or enter two to five increasing percentages below 100%. Review the current stage’s request counts, errors, and latency before choosing Advance. Each advance starts a fresh comparison. After the last stage, review and confirm publication to make the candidate the live release. Stopping the split or reaching its deadline returns traffic to the live release.
To start a staged rollout with the owner API, include stageBasisPoints in the canary request with expectedRevision set to null and trafficBasisPoints set to the first stage. Send the current expectedRevision to POST /api/projects/{projectId}/release-routing/advance for each increase. To finish, send deploymentId, expectedGeneration, and expectedRolloutRevision to the activate-release endpoint. The current release checks and approvals apply to advances and publication.
Return traffic when a candidate returns too many errors
In Delivery → Gradual rollout, enable the health rule and choose a 5xx threshold from 1% to 100% and a minimum of 5 to 50 samples. Stackr evaluates recent candidate GET and HEAD samples in the current stage, up to the last 15 minutes. Once enough samples are available and their error rate meets the threshold, Stackr stops the split and returns traffic to the live release. Traffic split history and project MCP show the sample counts and threshold that triggered the stop.
The rule depends on sampled traffic and may take longer to evaluate on quiet projects. Each stage and health rule change starts a new health sample window. The owner API accepts healthGuard with errorRateBps and minSamples in the canary request with the current revision. Omit it to keep the current rule, or send healthGuard: null to clear it.
Set a deadline and review traffic changes
In Delivery → Gradual rollout, choose when to end the split. Timed rollouts return traffic to the live release at the deadline. When you edit a timed rollout, you can keep its current deadline, choose a new duration, or choose Manually to clear the deadline.
Traffic split history shows the latest 50 changes, including starts, updates, ends, and expiries. Expiries appear after Stackr records them and show the original deadline as the event time. Read the same history with stackr_list_rollout_history in project MCP. Call the tool with {} using a project agent token.
The owner API returns the current deadline and revision at GET /api/projects/{projectId}/release-routing. To set a deadline, send durationMinutes from 1 through 1440 or an expiresAt timestamp in Unix milliseconds up to 24 hours ahead to PUT /api/projects/{projectId}/release-routing/canary. Omit both fields to keep the current deadline, or send expiresAt: null to clear it. Use GET /api/projects/{projectId}/release-routing/history for the traffic history.
Compare a rollout before changing traffic
In Delivery → Rollout comparison, compare sampled GET and HEAD requests, 5xx responses, average and p95 latency for the live and candidate releases. The dashboard uses the last hour of samples since the current split began and links to the logs for each release. Observed share is the fraction of recorded samples. Check sample counts before using the metrics to make a release decision.
Changing the candidate or traffic percentage starts a fresh comparison. Editing only the deadline changes the rollout revision and preserves the comparison window. An outdated tab must reload the current configuration before changing or stopping the rollout. Agents can read the comparison with stackr_get_rollout_metrics using a project agent token. Supported API and MCP windows are 15, 60, 360, and 1440 minutes.
Open Preview links to share a staged static ZIP with a reviewer. Choose a lifetime of one hour, one day, or seven days. Anyone who has the URL can view that release until it expires or you revoke it. Stackr shows the URL once and ends the link when its release starts receiving public traffic. Use relative asset URLs so scripts and styles load in the preview.
Open Release checks to require specific files or cap the unpacked size of a static ZIP. Select a release to review the result before publishing. An enabled policy applies to promotions, rollbacks, and releases receiving a share of public traffic. The current release stays online when a candidate fails. Disable the policy before publishing a different runtime.
Use stackr_inspect_release_checks in project MCP with a deploymentId to read the current activation blocker, missing-file count, size limit, and owner approval. The tool reads the same checks as Release details and leaves publishing decisions to the operator.
Require owner approval before publishing
In Release checks → Owner approval, turn on approval for the project. Open a staged release’s Details to review the private preview and record approval. Publishing or starting a traffic split to a different release requires approval, including publication from CI and by release managers.
The current live release can keep serving or be resumed after a pause. To roll back to a different release, approve that release first. Changing the setting clears previous approvals. End an active traffic split before changing the setting or revoking its candidate’s approval.
Deployment history shows your retained releases and static file storage. Delete unused releases to free space. Move a named preview or stop a canary before deleting its release. Keep any version you may want to roll back to.
To work with someone on a project, open its Settings tab and choose Collaborators. Create a one-use invite and share the code privately. The recipient signs in to Stackr and redeems it under Shared projects within 48 hours.
Viewers can see the project’s status and release history. Release managers can also publish or restore eligible static ZIPs and Stackr starters. Existing release checks still apply, and the owner controls project settings, access, and billing. Revoke a member or an unused code from Collaborators.
When GitHub push automation is available, connect a repository and branch through the installed GitHub App. A push stages the managed starter from that exact commit’s launch.json. Review the resulting release before publishing.
When custom domains are available, add a subdomain in Delivery. Publish the ownership TXT record and verify it, then add the displayed CNAME and any certificate verification records. Keep the ownership TXT and direct CNAME visible in public DNS. When DNS and the certificate are active, open the HTTPS test and refresh Delivery to see the result.
Open Zo.gy links and load balancing in Delivery. Copy a published site's URL to make a short link or QR code in Zo.gy. For a load balancer, copy a verified custom origin domain and request managed setup. Zo.gy requires at least two eligible HTTPS origins.
Container releases
When container hosting is available, stage your project's registered image digest. Set its HTTP port, instance size, and up to three replicas. The app must answer GET /health. Run the paid readiness preview before making the release live.
stackr deploy-container --image "$STACKR_IMAGE_DIGEST" --port 8080 --size lite --replicas 1 --url "$STACKR_DEPLOY_URL"
Container requests draw from prepaid funds at the rate shown in Delivery. The runtime accepts bounded UTF-8 HTTP responses, disables outbound Internet access, and serves HTML in a browser sandbox.
Build a container in CI
In Delivery, select Node.js, Python, Go, Rust, or your own Dockerfile. Choose the protected branch, build context and Dockerfile path. Save the workflow and optional Dockerfile template in your repository. Merge the jobs into any existing GitLab or Bitbucket pipeline. Bind your server to 0.0.0.0 on the selected port and implement GET /health.
Your CI runner builds a Linux amd64 image archive with a checksum and source commit. Use those files for Stackr image registration. Once you have the approved sha256:… digest, run the workflow’s manual staging job with the digest and source commit. Store STACKR_DEPLOY_TOKEN in the deployment environment.
On GitHub, include the workflow in the default branch and run it on the selected protected branch. On GitLab, run a web pipeline on that branch with STACKR_CONTAINER_IMAGE and STACKR_CONTAINER_COMMIT. On Bitbucket, run the stage-stackr-container custom pipeline with those variables. Open the paid readiness preview in Stackr before publishing.
JavaScript releases
When JavaScript hosting is available to your project, stage a bundled ES module with a default fetch handler. It can return text or JSON for GET and HEAD. The module can be up to 32 KiB and has no outbound network access.
stackr deploy-js ./dist/worker.mjs --tag v1 --url "$STACKR_DEPLOY_URL"
Use the project's deploy token as STACKR_DEPLOY_TOKEN. Review the staged release and make it live from deployment history. Each admitted execution, including previews, draws from the project's workspace usage funds at the displayed rate. Open Settings → Usage funding to view the ledger and add funds when checkout is available.
Use Pause public traffic to stop serving the current release. Resume or choose an earlier release from deployment history.
Scheduled jobs
Open a project and choose Schedules. Set up recurring health checks, JSON record backups, or webhooks. Use five-field cron in UTC. For example, 30 2 * * * runs daily at 02:30 UTC. The minimum spacing between runs is 15 minutes. Set backups to one time per day and use Backup history to download a retained snapshot.
Pause or resume a schedule, run it manually, and inspect the last 20 runs. A project can have three jobs and 24 runs per UTC day, including manual runs. Stackr applies a platform-wide cap of 120 runs per day. A health check uses one app request. At capacity, an occurrence may be skipped. Stackr does not automatically retry deliveries.
Run your application code with a webhook
Use a dedicated HTTPS endpoint hosted on a Vercel or Netlify app subdomain, or a Supabase Edge Function. Generate a verification challenge. Configure your endpoint to return the exact challenge as plain text on a GET with x-stackr-challenge: 1, then verify it in Stackr. Save the signing key in your server's secret store and enable the schedule.
Each delivery is a JSON POST with jobId, runId, scheduledAt in epoch milliseconds, and source. Check the freshness of x-stackr-timestamp and compare the x-stackr-signature to sha256= followed by the hex HMAC-SHA256 of <timestamp>.<raw request body>, using the signing key as UTF-8. Deduplicate side effects with the Idempotency-Key header. Supabase needs a dedicated Edge Function configured for external webhooks. Supabase external webhooks
Manage jobs from CI and tools
Create a schedule token from the Schedules page. Store it as STACKR_SCHEDULE_TOKEN in your terminal or CI and copy the project endpoint. The token expires after 30 days and can be rotated or revoked. Use the owner dashboard to verify endpoints and rotate webhook signing keys.
stackr schedules list --url "$STACKR_SCHEDULE_URL"
stackr schedules create --name "Nightly backup" --cron "30 2 * * *" --kind backup --url "$STACKR_SCHEDULE_URL"
stackr schedules history --job JOB_ID --url "$STACKR_SCHEDULE_URL"
Tools can use the Stackr API specification with the same scoped token.
Project databases
Open a project and choose Databases. Create a JSON records database, check availability for managed SQLite and key-value storage, or connect an account you already have. JSON records storage includes 200 records, 4 KiB per value, and 2,000 data operations per project each UTC month.
Use the separate database bearer token from a backend or CI secret. With the URL from the database page, send PUT with {"value":{"name":"Example"}} to save a record, or GET to fetch it. Use If-None-Match: * to create only. To avoid overwriting a concurrent edit, put the response’s record.revision in double quotes in the If-Match header. Use the collection URL with GET to list records.
Records keys and stale requests
Project ownership, owner identity and account changes revoke Records and schedule keys. Store removal or replacement also invalidates requests and restore previews captured for the earlier store. Returning to an earlier visible state does not restore old access. Successful responses keep their existing fields and revision ETags; private authorization and store-generation values are not exposed.
The current Records access controls revoke legacy Records/schedule keys and pause automatic backups until the current owner enables them again. It preserves records, backups and quota counters. Current owners must issue replacement keys and authorize backup scheduling again, through the owner session or a newly issued scoped schedule key. Explicit manual backup runs remain available under current authorization; health and webhook jobs are unchanged.
Records requests retain the 200-record, 4-KiB-value and 2,000-attempt monthly limits. Each admitted runtime attempt counts even if its body, conditional write or later access check fails. Corrupt or future-dated counters return HTTP 503. Lost owner access returns 404, a replaced owner store 409, and invalid/revoked bearer access 401. Existing ETag conditions still use 412.
JSON bodies use strict UTF-8 and five seconds to read, with structural-token caps equal to their byte limits. Store creation/deletion allows 512 bytes and depth four; record PUT allows 4,196 bytes/depth 20 while its serialized value stays within 4,096 bytes. Uploaded restore preview allows 1,000,000 bytes and apply 1,000,256 bytes, both depth 24; scheduled restore selections allow 512 bytes/depth 24. Invalid input returns 400, an aborted/timed-out read 408 and oversized bodies/values 413.
Latest-backup downloads accept the exact current schedule key or owner session. Backup history and selecting a snapshot require the owner session. Backup creation and downloads recheck original authority and source identity before returning data or saving a snapshot. The shared Records workflow passed isolated hosted acceptance. Acceptance with real customer credentials remains separate.
Use Supabase on a published site
Connect a Supabase project you already manage using its URL and publishable key. Stackr checks the Auth service and updates the live project's /backend-health endpoint. Enable browser access if your published static site needs the external Supabase Data API. Enable row-level security and write policies for the tables your site will use. Supabase API security
Copy the public config URL from Databases and fetch it from your site. The response contains url and publishableKey. Use these with the Supabase Data API and its apikey header. This config is public while enabled and unavailable in previews. Keep any service-role keys on your own backend.
Connect Postgres or Redis
Verify a Neon Postgres connection string or Upstash Redis REST URL and token from Databases. Stackr keeps the endpoint and last verification time. Add the credential to your own backend or CI secret store to use it in your application. Each verification makes one provider request that may count toward your usage. Your provider bills you directly.
Apply database migrations
From Databases → Migrations, choose a target, enter a migration version, and review your SQL. A provisioned dedicated SQLite database can apply the reviewed migration from Stackr. The version and changes commit together. For PostgreSQL, Supabase, or Neon, download the migration and run the displayed psql command with your own connection settings. Use a direct or session-pooled PostgreSQL connection.
Migration SQL allows up to 64 KiB. The JSON request allows 128 KiB, depth eight and 4,096 structural tokens, with five seconds to read its body. Invalid input returns HTTP 400, an aborted or timed-out body returns 408, and an oversized body returns 413. Stackr rechecks your current access before returning a plan or download, and checks active billing enrollment before each provider request when applying dedicated SQLite changes.
If a migration acknowledgement is lost, its recovered version receipt can show that the changes committed while usage is still unknown. Stackr returns HTTP 502 without applied-success data and blocks further statements until operator reconciliation. Keep the same version and SQL for that review; an error does not mean the migration rolled back. PostgreSQL-family downloads still run only when you execute them in your own environment.
Moving existing data is a separate job. For PostgreSQL, use a compatible pg_dump and pg_restore workflow against a staging database. Review roles, extensions, Auth and Storage metadata, and data counts before switching traffic. Use SQLite SQL for dedicated SQLite and review PostgreSQL syntax and extensions before translating a migration between engines.
Manage Auth and Functions
Connect a hosted Supabase project you manage, then open Auth and Functions. Stackr uses the external Supabase Management API to load enabled providers, signup policy, and deployed function versions. Enter a Management API token scoped to the connected project and the action you want to perform. Stackr clears it from the form after use. A reviewed TypeScript function can be deployed with gateway JWT verification or its own handler authentication.
Inspecting Auth uses auth_config_read and listing functions uses edge_functions_read. Updating signup policy requires Auth read and write permissions plus project_admin_write. Deploying a function uses edge_functions_write. Supabase Management API permissions
Run your own PostgreSQL backend
Use the PostgreSQL migration download with an existing PostgreSQL server. The self-hosted backend kit prepares PostgreSQL, Auth, Storage, Realtime, and Edge Functions on your own Linux server. It generates local credentials and binds the API gateway to loopback by default. Use the included instructions to connect your app.
Use managed key-value storage
When managed key-value storage is available to your project, create a store and issue a backend-only token from Databases. Send GET to /api/kv/PROJECT_ID/keys to list keys. Send GET, PUT with {"value":"example"}, or DELETE to /api/kv/PROJECT_ID/keys/KEY with the bearer token. Check the catalog for size and operation limits.
Project storage and feature flags
Open Storage in a project to upload, download, and remove private files. Each file can be up to 1 MiB. A project can keep up to 40 files and 5 MiB. Shared capacity and daily operation limits apply. Create a project file token for backend automation, then use the file endpoint with a bearer header and the file key in the query string.
Owners can download all private files from Export all files in Project files. The JSON export includes binary contents encoded as base64, revisions and SHA-256 checksums. It counts as one daily file operation and requires the owner session; file tokens cannot request bulk exports. Keep the downloaded file private.
To recover an export, choose Restore a file export, review the checksums, conflicts and capacity, then select Restore reviewed files. Restore creates new keys and blocks if any key already exists. Each restored file gets a fresh revision. Preview costs one daily file operation; a successful restore costs one per file. The review expires when destination files change or at the next UTC date. Owner sessions and the Stackr origin are required; file tokens cannot restore files. Review and apply each consume a separate validation attempt, limited to 30 per workspace and 300 across Stackr per UTC day, including invalid or aborted submissions. One validation can run per workspace at a time, with three across Stackr. Requests must finish uploading within 60 seconds. These attempt limits are separate from successful file operations.
The GET /api/projects/PROJECT_ID/files/activity endpoint gives the project owner a resource-metadata object activity summary, including lifecycle counts, held capacity, backend summaries and active read pins. It requires the owner session; file bearer tokens cannot use it. The report contains private metadata, excludes file contents and object keys, and leaves file/object lifecycle and provider data unchanged. The HTTP wrapper reserves inspection work and stores observation metadata. D1 remains the primary file backend. Its provider-usage verification and billing authorization flags remain false; hosted acceptance is still pending.
Advanced storage operations and operator reference
Review held object metadata
The local operator workflow provides GET /api/operator/object-storage/ATTEMPT_ID/review and POST /api/operator/object-storage/ATTEMPT_ID/review-check. Both require the separate object-storage operator bearer credential at the canonical HTTPS origin, without cookies, an Origin header or query parameters. Inspection returns a private metadata snapshot, an advisory assessment and an unsigned proposal; checking compares the raw proposal JSON against fresh database metadata. Both routes leave provider data and object lifecycle unchanged; inspection admission and observation metadata are stored by their HTTP wrapper.
A snapshot used to create a proposal must be at most 60 seconds old. Proposals expire five minutes after their original observation, and metadata, lifecycle or reference changes invalidate older reviews. The check accepts at most 16 KiB of JSON with bounded structure and a two-second body deadline. A current matching packet returns 200 with valid: true; rejected packets return 409 with reason codes.
The SHA-256 digest binds content and does not authenticate the issuer, prove provider finality or grant approval. Unknown writes stay held; absence, matching bytes and lease expiry do not prove a delayed request has finished. A cleanup-retry recommendation requests manual review and does not reset retry limits or release capacity. All execution, approval and billing authority stays false. There is no apply endpoint, and hosted/provider acceptance remains pending.
npm run --silent storage:status -- --snapshot ATTEMPT_UUID > SNAPSHOT.json
npm run --silent storage:review -- propose SNAPSHOT.json > PROPOSAL.json
npm run --silent storage:status -- --snapshot ATTEMPT_UUID > FRESH_SNAPSHOT.json
npm run storage:review -- validate PROPOSAL.json FRESH_SNAPSHOT.json
The status command uses the private STACKR_OBJECT_STORAGE_ORIGIN and STACKR_OBJECT_STORAGE_OPERATOR_TOKEN environment settings to fetch only the validated snapshot JSON; --snapshot cannot be combined with state or cursor filters. Keep those files private and use --silent when redirecting JSON so npm's banner is excluded. The separate offline review CLI reads regular local JSON files up to 256 KiB each and has no network, credential or apply mode. Validation checks only the supplied current metadata and grants no approval or response-time freshness guarantee. D1 remains the primary file backend.
Record owner and operator reviews
Operators can create a durable server record with POST /api/operator/object-storage/ATTEMPT_ID/reviews and a JSON requestId, plus an optional available action. The server derives the packet from fresh metadata. Reusing the same request ID under the same operator credential returns the existing record when its target and requested action match, with its original expiry.
In Project files → Storage reviews, open a record to check its current evidence and identify the staged copy by file key and byte size. Read the proposal, select I reviewed this proposal, then choose Record my review. Opening, refreshing or paging records records no acknowledgement. Revoke my review and Withdraw review record remain available for authenticated historical records after evidence changes or expiry.
Owner APIs are GET /api/projects/PROJECT_ID/file-reviews, GET .../file-reviews/RECORD_ID, POST .../RECORD_ID/confirmation and POST .../RECORD_ID/withdraw. They require the owner workspace session; file tokens and operator bearers cannot establish that channel. Owner writes require the Stackr origin. Confirmation JSON contains expectedRevision, the exact proposalDigest, and confirmed: true or false; withdrawal uses the first two fields.
Operators use GET /api/operator/object-storage/reviews, GET .../reviews/RECORD_ID, and the same confirmation/withdrawal suffixes with the separate operator bearer credential. All operator routes require the canonical HTTPS origin and reject cookies and an Origin header. List pages contain at most 25 records; open detail before relying on current evidence. Operator records omit file keys and private owner/provider/claim details.
A confirmed record means both authenticated role channels recorded their review; the same person could hold both credentials. Every execution and approval flag stays false. This records a review; recovery actions require a separate process. The five-minute packet expiry stays fixed. Changed evidence, current owner-policy changes, expired leases, CAS conflicts or operator token rotation block new confirmation. Rotation requires a new record for further confirmation; owner history remains readable and revocable when the operator credential is removed.
Strict record JSON is limited to 4 KiB, depth six, 200 structural tokens and a two-second read deadline. Issuance has SQL UTC daily and active-record limits: 50 per owner and 500 across Stackr per day; three active per attempt, 20 per project and 100 across the platform. Each record allows at most eight confirmation transitions and 18 audit events. Expired or withdrawn receipts are eligible for removal after 30 days and daily counters after 35 days, with bounded pruning. These review controls are deployed. Native files still use D1; acceptance with a real object provider remains pending.
Storage inspection usage
Storage activity, usage, review lists/details and advisory checks use a separate daily inspection allowance. Issuing a durable review or recording confirmed: true also reserves inspection work. Activity and usage reserve one unit, review lists two units, and detail/advisory/positive review workflows 16 units. These are work weights, not database rows or monetary prices. Admission and observation metadata is written while file/object lifecycle and provider data remain unchanged.
Each owner shares 200 requests and 2,000 units per SQL UTC day across projects; the platform owner lane shares 2,000 requests and 20,000 units. Each operator principal has 500 requests and 5,000 units; the platform operator lane shares 1,000 requests and 10,000 units. One handler can run per principal and three per lane. Leases last 30 seconds, with a 20-second workflow deadline. Reservations are nonrefundable, and uncertain work keeps its slot until lease expiry.
HTTP 429 includes Retry-After: 30 as a retry hint, not an availability guarantee. Daily exhaustion can last until the SQL UTC date resets. Owner inspections are queued in the console; refresh usage explicitly when needed. Revocation and withdrawal bypass inspection admission and the queue, retain authentication/CAS checks, and return an unchecked receipt with ineffective confirmations until detail is opened again. Closed historical detail avoids private-evidence reconstruction but still uses the fixed detail weight.
Owners read GET /api/projects/PROJECT_ID/files/usage using the owner session; file tokens cannot use it. Operators read GET /api/operator/object-storage/usage using the separate canonical-origin bearer credential. Both reject query parameters. Owner reports show shared owner allowance and current-owner project history; operator reports show both platform lanes and their own principal allowance. Aggregate reports contain no private identifiers or SQL text.
Submitted-statement counts and valid D1 row-count metadata are observations, not verified provider executions or charges. first() and raw() have no trusted row-count metadata; missing counts are unknown rather than verified zero. Authentication/admission baseline, metering/finalization and late work are excluded. observedOverflow marks saturated counters. The current usage request's reservation may appear immediately, while currentInspectionFinalized: false explains why its query observations are not yet finalized. Detail retention is seven days; daily aggregates are eligible for pruning after 35 days.
Native service usage and capacity
Open Service usage for a project to inspect native Records, dedicated SQLite, KV, queues and files, then refresh or download its private metadata export. Requests run in sequence without polling. A stored ready state and declared limits describe metadata and configuration; provider health, credentials and actual charges have not been verified.
Owner routes are GET /api/projects/PROJECT_ID/service-usage and GET .../service-usage/export. They require the current workspace owner session and reject bearer-token substitution and query parameters. Both reserve one shared inspection usage unit. Resource/provider data remain unchanged; inspection admission and observation metadata are stored.
Operators use GET /api/operator/service-usage/PROJECT_ID and its /export suffix with a separate STACKR_SERVICE_USAGE_OPERATOR_TOKEN at the canonical HTTPS origin, without Cookie or Origin headers. The object-storage operator credential does not grant this access. The operator audit channel can inspect existing project metadata while an owner is suspended, without establishing owner consent.
Records operation counters are monthly. SQL, queue and file counters are daily; inventory is a point-in-time view. SQL uncertainty makes remaining query/write capacity unknown even when the latest retained sample is from an earlier day. The report, export and browser keep blockedByUncertainty true and remaining capacity null until reconciliation. KV account counters are shared and excluded from project usage; manifest acknowledgements are not provider key counts. Queue effective states are separate from raw capacity reservations, so expiry never implies freed reservation capacity. Reports retain only the latest source counter period and cannot reconstruct history. Project-keyed counters can include a previous owner's use, so owner/workspace attribution remains unverified.
The export contains aggregate counts and the target project ID, with no contents, resource keys, query text, owner/provider identity or credentials. Its canonical SHA-256 digest binds content and does not authenticate an issuer, provider measurement or invoice. Provider usage, charges and billing/provider authority remain false or unverified.
npm run --silent service:status -- PROJECT_UUID --export > SERVICE_USAGE_EXPORT.json
npm run --silent service:review -- SERVICE_USAGE_EXPORT.json > SERVICE_USAGE_FACTS.json
The status command uses only the process environment's STACKR_SERVICE_USAGE_ORIGIN and separate STACKR_SERVICE_USAGE_OPERATOR_TOKEN, rejecting redirects and bounding the response. The review command reads one regular local UTF-8 JSON export up to 256 KiB without network, credentials, stdin or an apply mode. Facts retain separate windows, partial coverage and project-only attribution. Missing current samples and shared KV quantities stay unknown for attribution; no combined billing-period or cost total is produced. These facts support manual review rather than establishing actual charges or competitive prices. The usage reporting controls are deployed; real-provider cost acceptance remains pending and native files still use D1.
Review native SQL and key-value recovery metadata
In Service usage, choose Download recovery metadata (advisory only) to save a private SQL/KV snapshot with your current owner session. Owners can also use GET /api/projects/PROJECT_ID/native-recovery and .../native-recovery/export. This manual inspection does not call a provider or change a hold, token, usage counter or reservation. Each read, download or operator check uses one shared inspection unit; inspection admission and observations are stored.
The snapshot distinguishes temporary leases and durable holds, shows the latest retained SQL usage day and KV manifest counts, and excludes private provider bindings, keys, credentials and owner identity. This V1 snapshot and its review do not read the separate operation journal: their operation kind, dispatch and acknowledgement remain unrecorded and finality unverified. Legacy holds do not gain receipts retroactively. Provider identity/usage, complete history and shared KV attribution remain unverified.
Operators use the separate STACKR_NATIVE_RECOVERY_OPERATOR_TOKEN, a random 43–128 character base64url secret, for GET /api/operator/native-recovery/PROJECT_ID, its /export suffix and POST .../check. Requests must use the exact canonical HTTPS origin without Cookie or Origin headers. The service-usage and object-storage operator tokens do not grant this access. Operators can audit a suspended owner's existing metadata without establishing owner consent. Snapshot, export and check routes reject query parameters; owners have read/download access only.
npm run --silent service:recovery:review -- EXPORT.json --service sql --intent investigate_hold > REVIEW.json
npm run --silent service:recovery:review -- EXPORT.json --service sql --intent reconcile_usage > USAGE_REVIEW.json
The offline command reads one regular UTF-8 JSON export up to 256 KiB with no network, URLs, stdin, credentials or apply mode. Use --service kv --intent investigate_hold for a durable KV hold; usage review is SQL-only and requires uncertain usage. Run it within 60 seconds of the original snapshot. The packet retains that original expiry and its SHA-256 content binding does not authenticate an issuer or supplied evidence.
An operator sends the packet itself to POST .../check, with up to 16 KiB of JSON, depth eight, 2,048 structural tokens and a five-second body deadline. HTTP 200 reports either a current or stale metadata match; HTTP 409 asks for a fresh inspection if evidence changes or a current review expires before return. Access, evidence and expiry are checked again after inspection accounting finishes. Final checks fall outside the incomplete inspection observations, which never establish provider charges. Invalid, aborted/timed-out and oversized bodies use 400, 408 and 413. A current check grants no recovery approval, hold release, usage correction, quota refund, provider action or billing authority. It does not verify uninterrupted provider history, and existing owner confirmations still apply.
The recovery metadata controls are deployed. These routes and packets cannot execute recovery or settle an unknown provider operation. Actual credentials, provider finality, hosted recovery, costs and commercial acceptance remain pending.
Inspect native SQL and key-value operation records
In Service usage, choose View operation records for a manual read. The owner endpoint is GET /api/projects/PROJECT_ID/native-recovery/operations; the operator endpoint is GET /api/operator/native-recovery/PROJECT_ID/operations with the same separate native-recovery operator credential and origin restrictions. Owners see records created under their original owner identity and current authorization epoch. Operators can audit retained target records across original authorities. Operation records load only when you follow the link; it adds no recovery action.
Each request uses one inspection unit and returns up to 20 records, newest first. Pass the returned cursor unchanged as the only query parameter to read older records. Responses omit private owner/provider/account/lease/token identities, raw SQL, keys, values and request/response digests. An operation ID identifies its journal record. Reading records calls no provider and changes no native service state or usage.
New operations record their original intent before provider work. A possible-dispatch count means that a request might have been sent; it is retained before fetch and cannot prove actual dispatch. Validated mutation acknowledgements, observed reads, rejections and unknown responses are counted separately. Readback, discovery, absence or an HTTP status alone cannot acknowledge an earlier mutation or prove finality. A late acknowledgement belongs to its original record and does not release a hold or restore access.
incarnationCurrent compares the stored source incarnation and binding; leaseCurrent compares the original lease ID even when expired; authorityCurrent compares stored owner/identity/epoch/account eligibility and does not establish live session, invite or configuration policy. An old-source acknowledgement can remain visible to an operator while these flags are false. Complete/unknown RPC measurements stay separate, and observed SQL row totals can be a partial subset. Per-RPC measurements alone do not prove quota admissions; new covered operations have the separate receipts below. Legacy records and KV reads/listings still lack that proof. Complete reservations/history/invoices and usage-correction authority remain unavailable. Unknown quantities do not become verified zero.
The journal keeps at most 10,000 operations per project and 50,000 globally, with 32 RPCs per operation. Unfinished, incomplete-coverage, unobserved and unacknowledged-mutation records are retained when capacity fills. Only eligible history older than seven SQL-clock days can be pruned, at most 25 records per call; matching leases block pruning even when expired, and source/sequence tombstones remain. Unknown usage measurements alone do not prevent otherwise eligible history cleanup. Records establish no complete history, verified provider finality/usage, billing, execution, hold release or usage correction. Operation records are deployed; actual-provider and hosted-cost acceptance remain pending. Existing reviews and confirmations still apply.
Understand operation quota receipts
Operation-list responses now use version: 2. New SQL queries/migrations and KV key writes/deletions can have an atomic quota receipt accepted only after its guarded counter charge is confirmed before provider work. A stored candidate alone is not proof of admission. A recorded, confirmed receipt shows its original UTC day and admission time, project or account-shared scope, and this operation's quota debit. These units are not provider RPC counts, SQL rows or money; account-shared debits do not reveal shared totals. Private counter snapshots, limits, source and credential identifiers are excluded.
Each row's reservation.status is recorded, unrecorded or not_applicable. Legacy, denied-admission and unconfirmed-candidate records have null charged fields. An unconfirmed candidate blocks provider work and parent-history pruning; null does not prove zero/no charge or authorize a refund. Unsafe metadata instead fails as unavailable. Operation kinds outside the covered path are not applicable, and legacy history is never backfilled. KV reads/listings retain their existing read counters without new journal rows or receipts; namespace/resource controls gain no new quota charges. reservationHistoryComplete remains false. The V1 recovery snapshot and review still do not read journal or receipt details.
A confirmed receipt can exist even when no provider RPC followed, and its quota debit is not refunded. Exact internal confirmed-receipt replay prevents a second charge for the same operation; a customer retry remains a new request. Confirmation is checked after the database insert completes without an exception; an exception is never converted into readback success or automatic admission retry. SQL uncertainty survives midnight, future-dated counter periods are rejected, and completion uses the original receipt day. Receipts grant no provider-finality, correction, refund, hold-release, execution or billing authority and cannot reconstruct complete history or invoices. Quota receipt controls are deployed. Native provider activation and billing remain gated, with actual-provider and hosted-cost acceptance pending.
Offline inspection cost scenarios
npm run storage:costs -- examples/storage-control-costs.synthetic.json
npm run --silent storage:costs -- INPUT.json > COST_SCENARIO.json
Supply a saved usage aggregate, a project, platform-owner or platform-operator selection, and explicit USD micro-dollar row rates, allocated included allowances, fixed/request overhead, unmeasured reserve and budget. The command reads one regular local JSON file up to 256 KiB, with no network, credential or apply mode. The example rates and usage are synthetic. A valid scenario exits 0 even when it exceeds the declared budget; malformed input exits 1. The estimate grants no billing, pricing, refund or provider authority and proves no actual spend, profit or competitive price. Native file serving stays on D1 and hosted/provider cost acceptance remains pending.
PUT /api/projects/PROJECT_ID/files/object?key=reports%2Fdaily.json
GET /api/projects/PROJECT_ID/files/object?key=reports%2Fdaily.json
Open Feature flags to change named boolean switches without redeploying. Flags start private. Enable public access for a switch only when its name and value can be shared. Browser clients can read /_stackr/flags.json under a published Stackr static app's base path. Other sites can read https://stackr.grasany.com/api/flags/PROJECT_ID. Both return the flags you marked public.
Observability and log export
Open Observability for recorded requests, response bytes, latency, and status breakdowns. Request logs include time, method, status, runtime, latency, and response size. Stackr caps collection per project and platform per UTC day. Logs are retained for 24 hours and hourly analytics for up to seven days.
Web analytics
Enable Web analytics under a project's Monitoring tab to count eligible browser navigations to a published static site. Choose the paths you want to see separately. Other paths go into one bucket, and referrals are grouped by source type when available. The dashboard shows page views for seven UTC days. Collection stops at 200 page views per project or 2,000 across Stackr each UTC day and resumes the next day.
In Request logs, filter by status group, runtime, HTTP method, and minimum latency. Select Load older requests to continue within the same window. Bookmark the URL to reopen those filters.
Copy the X-Stackr-Request-ID response header into Find by request ID to locate its sampled log entry. You can also filter the project logs API with requestId. An ID can have no match when the request falls outside the sampling limits or retention window.
Open Request logs from Release details to filter sampled requests to that release. This includes traffic served by an eligible canary or a retained static release. In the project logs API, use releaseId with the status, runtime, method, and latency filters, or use requestId on its own. Older samples and project-level routes can have no release ID.
Open Performance to enable browser measurements for a published static app. Add the script shown there to your site and deploy the update. Stackr records sampled LCP, INP, and CLS measurements in daily aggregates. INP requires visitor interaction and some browsers report fewer metrics.
Create a read-only log token to export events into your own monitoring tools. The token expires after 30 days. For Splunk Cloud, run the forwarder from your own scheduled job with your project log token and a Splunk HEC token. Use a private cursor file to resume after the last accepted batch.
Download the Splunk Cloud forwarder and run node stackr-splunk-forwarder.mjs with Node 22 or newer. Set STACKR_LOG_PROJECT_ID, STACKR_LOG_EXPORT_TOKEN, SPLUNK_HEC_ORIGIN, SPLUNK_HEC_TOKEN, and STACKR_LOG_CURSOR_FILE in the job environment. The job handles up to 100 events per run.
Traffic rules
Open Traffic rules in your project to block a path on its public app URLs. For example, /internal blocks that path and its descendants. The changes take effect on the next request. Clear the entry to restore access.
Use Redirects to move an exact path to another path in the same app. Choose 302 or 307 for a temporary move or 301 or 308 for a permanent move. Redirects apply to published GET and HEAD requests and discard the incoming query string.
Use Rewrites to serve a file in a published static release at another URL. For example, /help/* to /guides/* serves /guides/setup.html at /help/setup.html. A pattern can also point to a single file such as /guides/index.html. Redirects run first. Exact rewrites take precedence over patterns, and the first matching pattern wins. Both the requested and resolved paths must pass traffic rules, and the file must exist in the selected release.
Use Security headers to ask search engines to skip indexing your published app, omit the referrer, or block browser access to the camera, microphone, and location. Use Site access or a private preview when you need to restrict who can view a release.
Site access and asset cache
In your project, open Site access to require a password on a published Stackr starter without inquiry capture. Visitors unlock the app in their browser. Changing or removing the password ends previous unlock sessions. Turn off site access before publishing a ZIP or another runtime. Use application sign-in when visitors need separate accounts or permissions.
Use Cache policy to allow browsers to reuse eligible public CSS, JavaScript, images, and fonts for 60 seconds to one hour. The policy leaves pages, previews, and password protected responses uncached. Static files provide a deployment-specific ETag. When the selected file still matches, a conditional request receives HTTP 304 with no body. The request still counts toward hosted usage. Use versioned asset filenames when you publish.
Public static files return X-Stackr-Release. To require the same release for a follow-up asset request, pass that ID as ?__stackr_release=RELEASE_ID or as X-Stackr-Expected-Release from a tool or same-origin client. A mismatch returns HTTP 409. Reload the document and retry against the new release. For header-based validation from a browser, use cache: 'no-store' to bypass a previously cached response.
Load assets from the release that served your page
On a published static site, append ?__stackr_asset_release=RELEASE_ID to an exact JavaScript, CSS, image, or font URL to request the version that served your page. Stackr keeps the immediate previous public static release eligible for up to 20 minutes after a new static release takes over. Deleting the release, pausing the project, or publishing again can end access sooner. HTTP 409 means the requested release is no longer eligible. Reload to start with the current release.
For HTML links you control, add data-stackr-release and select Keep marked assets on this release when uploading the ZIP. You can also pass --asset-affinity to stackr launch or stackr deploy-static. On the public site, Stackr adds the release ID to eligible marked scripts, stylesheets, preloads, and image sources. It can also fill a marked <meta name="stackr-release"> tag for client code. Marked images and picture sources also support srcset with up to 32 local candidates and positive width or density descriptors. Every candidate must be eligible; unsupported or mixed external sets stay unchanged. Imports and CSS url() need their own handling.
<meta name="stackr-release" data-stackr-release>
<link rel="stylesheet" href="./styles.css" data-stackr-release>
<script type="module" src="./main.js" data-stackr-release></script>
The Stackr app address exposes the ID of the original page through its navigation timing entry. This example sets the ID on one module URL. Apply it to each request that needs release-specific routing, including imports. HTML navigation, API routes, service workers, and paths with rewrites use their own routing rules.
const navigation = performance.getEntriesByType('navigation')[0];
const release = navigation?.serverTiming?.find(entry => entry.name === 'stackr-release')?.description;
const url = new URL('./main.js', location.href);
if (release) url.searchParams.set('__stackr_asset_release', release);
await import(url.href);
Project activity
Open Activity to review up to 100 recent events, including release changes and changes to site access, asset cache, redirects, and traffic rules. The owner view shows when a change happened without exposing passwords or configuration values. History starts when recording is enabled.
Background jobs and alerts
Open Job queues to submit JSON jobs and see how many jobs are ready, delayed, leased, or failed in each queue. The backlog shows the oldest ready job and the next delayed job. Counts cover retained jobs.
Issue an enqueue-only producer token for services that submit jobs and set STACKR_QUEUE_PRODUCER_TOKEN in their environment. Set the separate STACKR_QUEUE_TOKEN in your worker's environment. Existing worker tokens can also submit jobs. Use a stable idempotency key when retrying a submission.
Project ownership, owner identity and account changes revoke queue worker and producer tokens. Issue new credentials after access is restored; returning to an earlier account state does not reactivate an old token. Access is checked again after a request body is read and before a private result is returned. An admitted operation still consumes its queue allowance if access changes before the response.
Queue JSON requests allow up to 9,000 bytes, depth 16 and 4,096 structural tokens, with five seconds to read the body. Invalid JSON returns HTTP 400, an aborted or timed-out body returns 408, and an oversized body returns 413. An admitted request keeps its operation charge even when body validation fails.
stackr jobs enqueue --project PROJECT_ID --queue reports --file report.json --key report-2026-11-12
stackr jobs claim --project PROJECT_ID --queue reports
stackr jobs heartbeat --project PROJECT_ID --id JOB_ID --expected-lease-until LEASE_UNTIL_MS --lease 120
stackr jobs ack --project PROJECT_ID --id JOB_ID
Set STACKR_QUEUE_LEASE_TOKEN from the claim response before acknowledging, retrying, or extending a lease. For longer work, send a heartbeat before expiry and pass the last leaseUntil as the expected deadline. Use the deadline returned by each heartbeat in your next renewal. Each claim can hold a job for up to 15 minutes, as indicated by leaseLimitAt. Heartbeats count toward the queue operation allowance. Jobs can be delivered again after an expired lease, so make handlers safe to rerun. When a claim is empty, wait five minutes before polling again.
In Job queues → Failed jobs, requeue a retained failure once after resolving its cause. Stackr links the original to a replacement job with a fresh attempt limit. Use redrivenFrom from the worker’s claim or an application key to deduplicate business effects. Failed job history and recoverable payloads are retained for up to 24 hours.
In Job queues → Recent jobs, cancel a job before its first claim. A cancelled job stays in history for up to 24 hours. To submit new work during that window, use a new idempotency key.
Turn incoming webhooks into jobs
Open Job queues → Incoming webhooks. Name the endpoint, choose a queue such as orders, then copy the URL and signing secret into a service that supports Standard Webhooks v1. Your worker claims jobs from that queue as usual. This can move order updates, form events, and other small JSON notifications into your processing queue.
Send a POST with Content-Type: application/json, webhook-id, webhook-timestamp, and webhook-signature. Sign id.timestamp.rawBody with HMAC-SHA256 using the base64-decoded bytes after the secret’s whsec_ prefix. Use Unix seconds and v1,BASE64_SIGNATURE. Stackr checks a five-minute timestamp window and accepts up to 8 KiB per delivery. Keep the same delivery ID and JSON payload when retrying. A successful response means the job was queued. Make your worker safe to retry.
Each project can create up to three endpoints. Deliveries share the project’s queue quota. Delivery IDs can use up to 128 letters, digits, underscores, hyphens, and colons. Rotate the signing secret to replace the old one immediately, or delete the endpoint to stop receiving new deliveries. Standard Webhooks specification
Event topics and consumer groups
Open Data & services → Event topics when multiple services need the same events. Publish an event once, then give each service its own consumer group. Use a job queue when one worker should process each item.
Create a topic and group in Stackr. Issue a producer token for publishers and a consumer token for readers. Set STACKR_EVENT_PRODUCER_TOKEN or STACKR_EVENT_CONSUMER_TOKEN in the corresponding service’s environment.
stackr events publish --project PROJECT_ID --topic orders --file order.json --key order-123
stackr events read --project PROJECT_ID --topic orders --group billing
stackr events commit --project PROJECT_ID --topic orders --group billing --expected-offset 0 --offset 1
Read events in offset order and commit only after processing them successfully. If a commit conflicts, read the group’s current offset and retry from there. For replay, pass --after to read from an earlier retained offset without changing the group. Events can expire after 24 hours and are subject to the storage and operation limits shown in the dashboard. For business transactions, keep your source of record in a database and make consumers safe to retry.
Removing a consumer group discards its saved position. A topic can be removed after its groups are removed and its retained events expire. Use a new name for its replacement so old service requests cannot reach it. Each project can use 64 topic names, and each topic can use 32 group names over its lifetime.
Open Alerts to track request error rates, latency, and repeated failures from a project health schedule. Stackr evaluates sampled requests from a completed UTC hour and shows incident history in the project dashboard.
Collect alert events
In Alerts → Alert feed, create a read-only feed token. Save the token in your monitoring tool and poll the displayed URL with a bearer header. The first request returns retained alert openings and resolutions in feed order. An event’s at field is a Unix timestamp in milliseconds.
curl -H "Authorization: Bearer $STACKR_ALERT_FEED_TOKEN" \
"https://stackr.grasany.com/api/projects/PROJECT_ID/alerts/feed?limit=100"
Save nextCursor after processing each page and send it as after on the next request. If hasMore is true, fetch another page. Otherwise, wait for your next polling interval. Use the event ID to deduplicate retries. Stackr prunes feed events with their incidents. Rotate the token before it expires in 30 days.
Project infrastructure
Open Infrastructure to see the project’s Records, files, queues, event topics, schedules, and flags in one place, with links to manage each service.
Restore a Records backup
Open Schedules → Backup history and choose Preview restore on a retained snapshot. In Records, preview that snapshot and confirm. You can also upload a Stackr JSON export under Records → Restore JSON. Restore inserts the entire backup together and preserves existing records. An existing key blocks the restore. If the snapshot expires from history, Records is replaced, or ownership/account access changes after preview, take a fresh preview and confirm again. An empty database can be exported, while restore requires 1–200 records.
Open your project and choose Infrastructure to see whether dedicated SQL, containers, or usage billing are available for your workspace.
When dedicated SQL is available, you can create a project database, run one parameterized SQLite statement at a time, configure read replication, and issue a database-only token. Keep this token in your server or CI secret store. Send a POST request to /api/sql/PROJECT_ID/query with {"sql":"SELECT ? AS message","params":["hello"]}.
Native service credentials and interrupted requests
Project ownership, owner identity and account changes revoke native SQL, key-value, queue worker, queue producer and file tokens. Access is checked again while work proceeds and before returning private data. Returning the account to its earlier state does not restore an old token; issue a new one when the service is available.
If access changes or a provider response is lost after a write starts, the remote change may still complete. An error does not establish that the write was rolled back. Preserve the operation details for review before repeating a create or delete. Existing database migration reviews and resource-deletion confirmations still apply.
A SQL database marked reconciliationRequired needs operator review. Unknown resource changes keep their exclusive hold, and incomplete query usage blocks new statements even after the UTC day changes. There is no automatic hold release. SQL query JSON allows up to 32,768 bytes; deletion and replication bodies allow 256 bytes. Both use depth eight, 4,096 structural tokens and a five-second body-read deadline, with HTTP 400, 408 or 413 for invalid, aborted/timed-out or oversized bodies.
Managed key-value storage also reports reconciliationRequired after an uncertain namespace creation/deletion or key write/deletion. It keeps the namespace and key capacity reserved and blocks further provider work pending review; there is no hold-release endpoint. Key-value PUT JSON allows 16,512 bytes, depth 12 and 2,048 structural tokens; each value still has the project's configured limit of at most 16 KiB. Namespace-deletion JSON allows 128 bytes, depth two and eight structural tokens. Both use the same five-second body deadline and HTTP 400, 408 or 413 failures.
The container controls manage a digest-pinned image, instance size, and replica limit. The capacity settings require enrollment and approval. Use the billing panel to view reconciled periods and open an issued invoice.
Free workspace limits
A free workspace includes three projects and 30 releases per project. The workspace shares 10,000 hosted requests across projects each UTC calendar month. All workspaces share a platform limit of 15,000 hosted requests per UTC day. If either limit is reached, further metered requests return HTTP 429 until the corresponding UTC period resets. The dashboard shows your workspace usage.
Set a monthly hosted request cap
Open Usage funding → Monthly request cap to set a ceiling for the workspace. It covers the monthly hosted request counter across your projects, including live requests, static previews, and any paid traffic overages. Once you reach the cap, further metered requests return HTTP 429 until the next UTC month or until you raise or clear the cap. Changing the cap keeps the current request count. Plan limits and any separate spending limits still apply.
Paid traffic overages and wallet top-ups are currently unavailable. Usage funding still lets you set a monthly hosted request cap for the workspace.
Use the migration calculator to compare your current bill, traffic, response sizes, storage, and measured latency with Stackr.
Use the infrastructure cost calculator to model hypothetical monthly database, request, and container costs with a commission assumption.
Browse Grasany integrations for sign-in, links, routing, monitoring, and transactional email setup.