Skip to main content

Operate Artifacts

This page is for the administrator of a Crewship instance. It covers how much an artifact may store, how long its history is kept, what a backup carries and what an upgrade changes. Everything an artifact holds lives in the instance database: there is no separate file store to size, mount or back up.
Projects are on by default on the server; every other artifact kind is off, and the web screens need build-time variables. An upgrade adds the tables and the workspace feature flags and turns on only the artifact_projects default, unless an administrator had already changed it. See Turning Artifacts on and Turning Projects off.

Turning Artifacts on

Three switches decide whether a kind of artifact is available. The server side is a workspace feature flag (or an instance-wide environment variable that overrides it for every workspace). The Artifacts screens in the web UI also depend on build-time NEXT_PUBLIC_* variables, which are compiled into the web UI when it is built. The library variable is needed for the library across kinds. Dashboard and Slides additionally need their own preview variable, and the chat viewer needs NEXT_PUBLIC_CHAT_ARTIFACT_PROJECTS. artifact_projects is on by default. Every other workspace flag in the table is seeded with its instance default off. Enable or disable one for the current workspace, or check what a workspace resolves to:
crewship feature-flag update <key> --enabled changes the instance default for every workspace that has no override. Native Word and Sheet editing is an instance setting, CREWSHIP_CRAFT_NATIVE_ENABLED, not a workspace flag. That switch alone does not enable editing: it needs a qualified engine revision, CLI executable and digest, editor bundle and URL, plus the native bundle directory. The operator must install and qualify these before restarting. Live workbooks also need their private service socket, service token file and qualified editor bundles. See Environment variables and crewship feature-flag.
Release builds (binaries, packages and Docker images) ship with the build-time variables off, so a release web UI does not show the Artifacts screens. Turning the workspace flags or instance switches on still makes Artifacts available through the server, the CLI (crewship page artifact, crewship page design) and the API. You cannot change a build-time variable on an installed release: the Docker image accepts no build argument for it. To show the screens, build Crewship from source (see the From source tab in the Quickstart) with the variables set to true in the environment of the build, for example:
Such a custom build is not a published release.

Storage limits

The limits below are compiled into the server. There is no setting or environment variable that raises them.

Versions of a Project, Dashboard, Slides or Design

Each saved version is an immutable, complete set of files. Limits apply per artifact: History usage counts every file stored once per artifact (identical content is deduplicated by hash across versions), plus each version’s manifest, message and a small fixed overhead. At 80 % of the limit the quota.warning field turns true. The live, unsaved canvas of a Design is stored separately and does not count until you save it as a version. The CLI reads a manifest file of at most 9 MiB, so crewship page artifact create and publish cannot send a version as large as the server would accept.

Dashboard data

Dashboard collections are mutable data next to the immutable code versions: What happens when a limit is exceeded depends on the limit:
  • 413 with code artifact_data_quota: a document over 256 KiB, a batch request over 1 MiB, a collection that would hold more than 4096 documents or 8 MiB, and a write that would create a 33rd collection.
  • 400 (invalid request): a batch with more than 50 writes.
  • 400 on data reads and writes: a dashboard.json that declares more than 32 collections is not a valid declaration. Publishing such a version is not refused, but the version is not treated as a Dashboard and its data requests fail.
A rejected batch is rejected as a whole and existing data is kept. A stale ifVersion returns 409 with code artifact_data_conflict instead.

Word and Sheet documents

A native Word or Sheet document keeps up to 16 GiB of version history. When it is full, saving returns 413 “native history quota reached; existing versions retained”. The older document service has its own per-workspace document and operation limits, set with CREWSHIP_DOCUMENTS_MAX_DOCUMENTS_PER_WORKSPACE, CREWSHIP_DOCUMENTS_MAX_OPERATIONS_PER_WINDOW and CREWSHIP_DOCUMENTS_OPERATION_WINDOW_SECONDS (see Environment variables).

Artifacts per workspace

An artifact is stored as a page record, so it counts toward the limit of 100 pages per workspace by default (an instance administrator changes it with crewship admin instance page-limit set). Creating a Project or Design in a full workspace returns 422 with code pages_limit, not the 413 of a full history (artifact_history_quota, or “Design capacity is full”).

Checking usage

List the artifacts you can see with crewship page list. Its JSON output names each one’s kind in artifact_kind (project, dashboard, slides, design, word or sheet):
Archived and test items still consume history and count toward the workspace Page limit. This list includes only items you may read: other people’s private items can count toward the limit without appearing here. It is not an instance-wide inventory. Archiving is reversible and does not free storage. For a Project, Dashboard or Slides artifact, the owner sees its usage in the quota object of the artifact read:
Other readers receive zero usage/limit values rather than the owner’s usage. A non-owner who can edit gets "retention": "latest-version-only", and a reader of the shared version gets "retention": "shared-version-only". A Design does not report its usage: crewship page artifact get does not read Design artifacts, and crewship page design get has no quota field. You learn that a Design is full only when saving a version returns 413 “Design capacity is full”. There is no instance-wide report of artifact storage; to see which artifacts are large, read each one as its owner.

Retention

Artifact history is keep-all. Nothing ages versions out:
  • Saving appends a version. Restoring an older version appends a new version with the old content; it does not rewrite history.
  • Sharing pins which version readers see. It never moves or removes the latest version.
  • There is no command that prunes old versions of one artifact. The only way to free its history is to delete the artifact, which removes its versions, data and comments with it. Save any content you need first; deletion is permanent. The owner can delete it with crewship page delete <slug> --yes. page archive only hides it and does not free history.
The instance retention windows (crewship admin instance retention, Admin › Data retention) do not cover Artifacts. Their page_project_history housekeeping applies to the older Pages application builds, not to artifact versions. See Admin API.

Backup and restore

Workspace backups carry Artifacts in the pages content category: versions and their file blobs, Design documents, Dashboard data, comments, Word and Sheet documents and their history. A backup plan that leaves out pages leaves out every artifact. The workspace’s artifact creation policy travels with the agents category. Live sessions do not travel. Editing leases, pending creation consents and chat-run permissions are excluded, so after a restore an editor must open the document again and an agent needs a fresh permission. See Backup & Restore.

Upgrades

The Artifacts tables arrive through ordinary migrations that run on the next start after an upgrade, after the automatic pre-migration snapshot. They add empty tables and off-by-default flags; existing Pages are not converted. A rollback across them follows the usual snapshot procedure in Upgrading & Downgrading. The individual migrations are listed in the Migrations Catalog.