> ## Documentation Index > Fetch the complete documentation index at: https://docs.crewship.ai/llms.txt > Use this file to discover all available pages before exploring further. # Operate Artifacts > Storage limits, history retention, backups and upgrade notes for administrators who run Artifacts. # 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. > [!WARNING] > > 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](#turning-artifacts-on) and > [Turning Projects off](https://docs.crewship.ai/configuration/artifacts.md#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. | Artifact kind | Workspace flag | Instance switch | Build-time UI variables | | - | - | - | - | | Project (multi-screen HTML) | `artifact_projects` | `CREWSHIP_ARTIFACT_PROJECTS_ENABLED=true` | `NEXT_PUBLIC_ARTIFACTS_LIBRARY`, `NEXT_PUBLIC_CHAT_ARTIFACT_PROJECTS` | | Dashboard data | `artifact_dashboard_data` (needs Project) | `CREWSHIP_ARTIFACT_DASHBOARD_DATA_ENABLED=true` | `NEXT_PUBLIC_ARTIFACT_DASHBOARDS` | | Slides | `artifact_slides` (needs Project) | `CREWSHIP_ARTIFACT_SLIDES_ENABLED=true` | `NEXT_PUBLIC_ARTIFACT_SLIDES` | | Design | `artifacts_design` | `CREWSHIP_ARTIFACTS_DESIGN_ENABLED=true` | `NEXT_PUBLIC_ARTIFACTS_DESIGN`; prototype playback also `NEXT_PUBLIC_ARTIFACTS_DESIGN_PROTOTYPE`; the Export HTML button also `NEXT_PUBLIC_ARTIFACTS_DESIGN_EXPORT`; text style controls also `NEXT_PUBLIC_ARTIFACTS_DESIGN_TEXT_STYLE`; hide and lock buttons also `NEXT_PUBLIC_ARTIFACTS_DESIGN_HIDE_LOCK`; shape style controls also `NEXT_PUBLIC_ARTIFACTS_DESIGN_SHAPE_STYLE` | | Live workbook editing | `gridcraft_editor` | `CREWSHIP_GRIDCRAFT_ENABLED` and `CREWSHIP_GRIDCRAFT_EDITOR_ENABLED` are both **required**, not an override | — | 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: ```bash theme={null} crewship feature-flag list # DEFAULT, WORKSPACE override, EFFECTIVE crewship feature-flag enable artifact_slides # this workspace only crewship feature-flag disable artifact_projects # turn Projects off here crewship feature-flag inherit artifact_projects # drop the override again ``` `crewship feature-flag update --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](https://docs.crewship.ai/configuration/environment.md) and [`crewship feature-flag`](https://docs.crewship.ai/cli/feature-flag). > [!NOTE] > > 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](https://docs.crewship.ai/quickstart.md#installation)) with the variables set to `true` in the > environment of the build, for example: > > ```bash theme={null} > NEXT_PUBLIC_ARTIFACTS_LIBRARY=true NEXT_PUBLIC_CHAT_ARTIFACT_PROJECTS=true make build > ``` > > 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: | Limit | Value | When it is exceeded | | - | - | - | | Retained history | 256 MiB | `413` with code `artifact_history_quota` (Design: `413` "Design capacity is full") | | One version | 32 MiB of file content | `413`, same code as above | | Files in one version | 256 | `400` (invalid manifest) | | File path | 512 bytes, relative, no `..` | `400` | | Version message | 4096 bytes | `400` | 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: | Limit | Value | | - | - | | Collections per artifact | 32 | | Documents per collection | 4096 | | Data per collection | 8 MiB | | One document | 256 KiB | | Writes in one batch | 50 | | One batch request | 1 MiB | 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](https://docs.crewship.ai/configuration/environment.md)). ### 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`): ```bash theme={null} crewship page list --archived include --test-items include --limit 500 -f json \ | jq -r '.[] | select(.artifact_kind == "project" or .artifact_kind == "dashboard" or .artifact_kind == "slides") | .slug' ``` 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: ```bash theme={null} crewship page artifact get -f json | jq '.quota' # { "used_bytes": 388, "limit_bytes": 268435456, "warning": false, "retention": "keep-all" } ``` 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 --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](https://docs.crewship.ai/api-reference/admin.md#get-/api/v1/admin/instance/retention). ## 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](https://docs.crewship.ai/guides/backup.md#artifacts-in-a-backup). ## 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](https://docs.crewship.ai/guides/upgrades.md#rollback-/-downgrade). The individual migrations are listed in the [Migrations Catalog](https://docs.crewship.ai/guides/migrations.md). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.