# 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.

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](https://deep.space/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](https://docs.deep.space/guides/custom-domains), 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

```bash
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](https://docs.deep.space/concepts/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

```bash
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](https://docs.deep.space/guides/server-actions) can read every record and return it as JSON for the owner to save. Add it to the scaffold's `src/actions/index.ts`:

```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:

```tsx
// 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

```bash
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](https://docs.deep.space/guides/updating). Avoid the busy dates from question 4.

## Step 6: When something breaks

```bash
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](https://deep.space/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](https://docs.deep.space/agents).

Running apps for a business? See [deep.space/enterprise](https://deep.space/enterprise).
