Skip to main content
Documentation

Website maintenance checklist for your user's DeepSpace app: uptime, errors, backups, SSL and updates

A maintenance checklist for a DeepSpace app people already use: what the platform handles (hosting, HTTPS), and the commands to check errors, scheduled jobs, storage, credits and SDK updates, plus an outside uptime check, an owner-only data download, and rollback.

On this page

Yes, a DeepSpace app that people already use can be kept healthy with a short, regular checklist that the agent runs from the CLI. DeepSpace runs the hosting: the servers, the HTTPS certificate on <app-name>.app.space, and platform fixes. What it doesn't do for you:

  • check that the person's main task still works;
  • read the error logs;
  • watch storage and credits;
  • keep a copy of the data;
  • move the app to a new SDK version.

The app's own code changes only when someone deploys. The docs describe no built-in uptime alerts or automatic data backups, so this page adds an outside uptime check and an owner-only data download.

Version: written for deepspace@0.43.0 (changelog). Docs checked: October 29, 2026. The backup action and page in step 4 ran in local development on October 29, 2026. The CLI commands were run against an app that had not been deployed, so logs and releases had nothing to show.

What DeepSpace handles, and what to check#

Area Handled by DeepSpace What to check
Hosting and HTTPS Servers, and the certificate for <app-name>.app.space; for a custom domain, the certificate once DNS is verified That the live URL opens over HTTPS
Errors Collects worker logs and browser-reported errors npx deepspace logs for new errors
The person's task Nothing; it's app-specific Do the main task on the live URL
Storage and credits Enforces the owner's plan limits npx deepspace app usage and npx deepspace app files list
Data copies No automatic backup is documented Download a copy (step 4)
SDK updates Publishes new deepspace versions; the app moves only when someone updates and deploys it npx deepspace@latest app update --json
A way back Keeps the release history npx deepspace releases and rollback

Questions to ask the person#

These need no technical knowledge to answer, and each answer maps to a check below.

  1. What is the one thing people do in the app that must keep working? That becomes the weekly check.
  2. Who should hear about it when something breaks, and how? That person gets the uptime alerts.
  3. How much data could you afford to lose: a day's, a week's? That sets how often to download a copy.
  4. Are there busy dates when nothing should change, such as an event day? Don't deploy or update then.
  5. Who owns the app's DeepSpace account? Usage, files and rollbacks act on the owner's account. Confirm with your user before running them.

Step 1: After every deploy#

npx deepspace deploy --json
npx deepspace releases --limit 3
npx deepspace logs --since 15m --level error
  • In the deploy result, serving: "confirmed" means fresh connections are answered by the new release; unconfirmed means some still get the old one, so wait and check again. See deployment.
  • releases lists the new release at the top. Releases are immutable, and --json marks each with rollbackAvailable.
  • Then do the main task (question 1) on the live URL yourself.

Step 2: Every week#

npx deepspace status
npx deepspace logs --since 7d --level error
npx deepspace logs --since 7d --search cron
npx deepspace test screenshot https://<app-name>.app.space/ live.png --full-page
  • status shows the environment (production unless DEEPSPACE_ENV says otherwise), the signed-in account, the app and the live release.
  • In logs, eventType: "exception" is an error that escaped the worker, and source: "client" is an error reported from someone's browser. With --json, an empty window prints {"type":"meta","count":0,...}, meaning the command ran and found nothing. outcome: "ok" means the worker returned, not that the request succeeded, so triage on request.status and level.
  • Scheduled jobs log one line per run, [cron] <task> ok or [cron] <task> failed, so --search cron shows whether they still run.
  • test screenshot shows what the live page renders, without a browser of your own.
  • Then do the main task on the live URL, as a signed-in user if the app has sign-in.

Step 3: Watch uptime from outside#

DeepSpace's docs describe no built-in uptime alert, so use any external HTTP monitor the person already has or is willing to sign up for. Point it at two URLs:

URL Answers when
https://<app-name>.app.space/ The app's page is being served
https://<app-name>.app.space/api/auth/ok The app's worker is running and its sign-in route answers; the scaffold's own tests wait on this route before starting

Send the alerts to the person from question 2. Signing up for a monitoring service is an account step, so confirm with your user first, and use the person's own account for it.

Step 4: Download a copy of the data every month#

Records live in the app's Durable Object, and the docs describe no automatic backup or export. An owner-only server action can read every record and return it as JSON for the owner to save. Add it to the scaffold's src/actions/index.ts:

// src/actions/index.ts
import type { ActionHandler } from "deepspace/worker";
import type { Env } from "../../worker";

// Collections in the owner's download. Leave out `users`: its rows hold people's emails.
const EXPORTED = ["eventDetails"];

export const actions: Record<string, ActionHandler<Env>> = {
  exportData: async ({ userId, env, tools }) => {
    if (userId !== env.OWNER_USER_ID) {
      return {
        success: false,
        error: "Only the app owner can download a copy.",
      };
    }
    const collections: Record<string, unknown[]> = {};
    for (const name of EXPORTED) {
      const result = await tools.query(name, { limit: 5000 });
      if (!result.success) return result;
      collections[name] = result.data.records;
    }
    return {
      success: true,
      data: { exportedAt: new Date().toISOString(), collections },
    };
  },
};

List the app's own collections in EXPORTED. Actions bypass collection permissions, which is why the owner check comes first; OWNER_USER_ID is set on every deployed app. tools.query returns 50 records unless given a limit, so raise 5000 if a collection is larger.

The owner downloads it from a page:

// src/pages/(app)/backup.tsx
import { useState } from "react";
import { AuthGate, getAuthToken } from "deepspace";

function Backup() {
  const [message, setMessage] = useState("");

  async function download() {
    setMessage("");
    const res = await fetch("/api/actions/exportData", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${await getAuthToken()}`,
      },
      body: "{}",
    });
    const { success, data, error } = (await res.json()) as {
      success: boolean;
      data?: { exportedAt: string };
      error?: string;
    };
    if (!success || !data) return setMessage(error ?? "Download failed.");
    const url = URL.createObjectURL(
      new Blob([JSON.stringify(data, null, 2)], { type: "application/json" }),
    );
    const link = document.createElement("a");
    link.href = url;
    link.download = `app-copy-${data.exportedAt.slice(0, 10)}.json`;
    link.click();
    setTimeout(() => URL.revokeObjectURL(url), 0);
    setMessage("Downloaded.");
  }

  return (
    <>
      <h2>Download a copy of the app's data</h2>
      <button onClick={download}>Download</button>
      {message && <p role="status">{message}</p>}
    </>
  );
}

export default function BackupPage() {
  return (
    <AuthGate>
      <Backup />
    </AuthGate>
  );
}

Add { path: '/backup', label: 'Backup', roles: ['admin'] } to src/nav.ts. The file is named like app-copy-2026-10-29.json; each record in it has recordId, data, createdBy, createdAt and updatedAt. In the local run, the owner's download held the saved record, and another signed-in account got "Only the app owner can download a copy." Uploaded files are not in this copy; npx deepspace app files list and app files get <key> reach them.

This is a copy to keep, not a restore button. Putting data back means writing it with tools.create, which this page doesn't do.

Step 5: Every month, check usage and updates#

npx deepspace app usage
npx deepspace app files list
npx deepspace@latest app update --json
  • app usage shows the account's credit balance, quota headroom and spend per integration. It covers the whole account, not one app; --json says "scope": "account".
  • app files list ends with the storage used against the owner's plan, for example Storage: 2.4 MiB of 128.0 MiB used on the free plan. An upload over the limit is refused with storage_quota_exceeded.
  • app update is read-only. status: "aligned" means the app already matches the CLI's SDK version. Otherwise its steps list the package.json edits, migrations, type check and test to do before deploying. See updating an app. Avoid the busy dates from question 4.

Step 6: When something breaks#

npx deepspace releases
npx deepspace rollback --yes --json
rollback re-deploys the previous release's exact bundle, or a release id you pass, with no rebuild. It changes the live app, so confirm with your user first. Two commands delete stored data and need the owner's explicit approval:

  • rollback --allow-do-deletion deletes the data of any Durable Object class the target release drops.
  • npx deepspace app undeploy takes the URL down and destroys the app's data.

Download a copy (step 4) before either.

Common failures and how to fix them#

What you see Cause Fix
app_not_deployed from logs The app in this folder has never been deployed Run it from the deployed app's checkout, or pass --app <id>
{"type":"meta","count":0,...} from logs --json No events in the window Not an error; widen --since if you expected some
{"type":"meta","truncated":true} More events than --limit Narrow --since or --level, or raise --limit (max 500)
no_bundle from rollback That release's bundle was evicted Pick a release with rollbackAvailable: true in releases --json
confirmation_required from rollback --json or no terminal, without --yes Confirm with your user, then add --yes
storage_quota_exceeded (HTTP 409) The owner's file allocation is full Delete files with app files rm, or move the owner to a larger plan
"Only the app owner can download a copy." Signed in as someone other than the owner Sign in as the owner
The copy has fewer records than expected tools.query stopped at limit Raise the limit in exportData
version_gap_too_wide from app update The app is several releases behind Follow the changelog one release at a time

What to tell the person#

  • What runs itself: hosting, the HTTPS certificate, and platform fixes.
  • What you check, and when:
    • after each change, the deploy result and the main task;
    • every week, errors, scheduled jobs and the main task;
    • every month, usage, storage, updates and a copy of the data.
  • Who gets alerts: the person from question 2, from the uptime monitor.
  • Where the copy is: the dated JSON file from the Backup page, kept somewhere safe. It is a copy, not a one-click restore.
  • What needs their approval: rollbacks, updates on busy dates, and anything that deletes data.

What is available today, and what is planned#

Available today, in published deepspace@0.43.0:

  • logs with worker, request and browser-reported events, and [cron] run lines
  • status, releases, rollback and deploy --json with a serving result
  • app usage for account credits and quota, and app files list for storage
  • app update as a read-only update checklist
  • Server actions that read every record, for an owner-only download
  • HTTPS on <app-name>.app.space, and certificates for verified custom domains

Not documented today: built-in uptime alerts, and automatic backups or restore of app records.

In testing on staging, not production: agent accounts that register themselves by solving a math challenge. Production signup for agents is not enabled.

Planned: autonomous agent accounts in production, so the app can be kept without a person's DeepSpace sign-in. Under that plan, payments and legal actions will still require a human. See DeepSpace for agents.

Running apps for a business? See deep.space/enterprise.