Skip to main content

Artifacts configuration

Every Artifacts surface beyond the classic Page list is off by default. A surface appears only when each layer it depends on is switched on: The server layers decide whether an endpoint answers. The build-time layer decides whether the web UI shows the screen at all. A screen whose UI variable is off stays hidden even when the workspace flag is on, and a screen whose UI variable is on shows nothing until the server reports the feature available.

Which switches each screen needs

Dashboard and Slides project-backed previews need NEXT_PUBLIC_CHAT_ARTIFACT_PROJECTS as well as their own UI variable. The Artifacts library additionally needs NEXT_PUBLIC_ARTIFACTS_LIBRARY; enabling the library alone does not enable project-backed previews. NEXT_PUBLIC_ARTIFACTS_DESIGN alone also opens /artifacts, so a Design-only build can reach the canvas. Without either library variable, a saved /artifacts link falls back to /pages. Artifacts is the main place for this work: with the library on, old /pages addresses lead there too (see Pages addresses).

Workspace feature flags

These flags are stored in the database. Each one is created by a migration with its instance default off, so upgrading an existing instance never turns a surface on. A migration that runs again leaves a changed default alone. The one exception is artifact_projects: Projects are a supported default, and a later migration turns its instance default on unless an administrator had already changed it (see Turning Projects off). The server resolves a flag in this order: the server environment bypass forces it on, then a workspace override wins, then the instance default applies. A key that does not exist reads as off. The flag check reads only the on/off value: the percentage column shown by crewship feature-flag list does not change the result for these keys. Turn a flag on for the current workspace (OWNER or ADMIN). Select the workspace with --workspace <workspace-id> or CREWSHIP_WORKSPACE:
Return the workspace to the instance default, or turn it off explicitly:
Change the instance default for every workspace without an override. --enabled is a boolean flag, so turning the default back off needs --enabled=false:
Only an instance administrator may change a default: the account named by CREWSHIP_OWNER_EMAIL on the server, or anyone named with crewship admin instance add-admin. Being OWNER or ADMIN of a workspace is not enough; that role can only set the workspace override. The same operations are available as PUT and DELETE /api/v1/feature-flags/{key}/override and PATCH /api/v1/feature-flags/{key}. See crewship feature-flag and the Feature flags API.

Turning Projects off

artifact_projects is on by default. Turning it off hides Projects; it does not delete them. While it is off, the project routes answer 404 (artifact projects are not enabled) and crewship page artifact availability reports {"enabled": false}. Turning it back on shows the existing projects and versions again. For one workspace (OWNER or ADMIN of that workspace):
For every workspace without an override (instance administrator):
A workspace override wins over the instance default in both directions, so a workspace that ran enable stays on after the instance default goes off. CREWSHIP_ARTIFACT_PROJECTS_ENABLED=true forces Projects on for every workspace and overrides both; leave it unset to let the flags decide. Upgrading from an earlier release. Migration 20261105094324_artifact_projects_default_on turns the instance default on only where the flag is still the untouched seed from 20261027175100_artifact_project_comments. If an administrator ever changed the instance flag (crewship feature-flag update, PATCH /api/v1/feature-flags/artifact_projects or a manifest apply), or deleted or recreated it, the upgrade keeps that choice. Workspace overrides are not touched: a workspace that was turned off stays off.

Server environment bypasses

Four flags have a server environment variable that turns the feature on for every workspace on the instance, whatever the database says. Use them for a single-tenant or demo instance. The value must be exactly true; 1 is not accepted. The Dashboard data and Slides bypasses do not imply artifact_projects: that flag, or its bypass, must still be on for the workspace. gridcraft_editor has no bypass. A bypass cannot be turned off per workspace; remove the variable and restart the server instead.

Instance startup switches

These switches are read once when the server starts. Set them in the YAML configuration file or as environment variables; an environment variable overrides the YAML value. Boolean switches accept true or 1. Change them only with a restart. A switch that is off removes or refuses its routes for every workspace. The startup settings below have YAML keys. Workspace flags and their server environment bypasses are separate mechanisms, and NEXT_PUBLIC_* variables are build inputs, not YAML settings. This template needs real qualified engine and bundle pins, installed bundles and running private services; it is not a self-contained deployment:

Native Craft profiles

Native Craft runs only operator-qualified releases. Each application profile is pinned at startup; requests cannot override it. In YAML a profile sits under craft_native.profiles.wordcraft (Word) or craft_native.profiles.gridcraft (Sheet), and its application must repeat that key. As environment variables, <APP> is WORD (Word) or GRID (Sheet): The full names are CREWSHIP_CRAFT_NATIVE_WORD_ENGINE_REVISION, CREWSHIP_CRAFT_NATIVE_WORD_CLI_PATH, CREWSHIP_CRAFT_NATIVE_WORD_CLI_SHA256, CREWSHIP_CRAFT_NATIVE_WORD_EDITOR_BUNDLE, CREWSHIP_CRAFT_NATIVE_WORD_EDITOR_URL, and the same five with GRID for Sheet. The server does not start when a native pin is invalid. When legacy GridCraft editing or Mooring is also enabled, gridcraft.editor_bundle_dir must explicitly equal craft_native.editor_bundle_dir, as in the template. GridCraft also requires its distinct clean absolute service socket and token-file paths (at most 100 bytes each); enabling its two booleans alone fails validation. The native and legacy editor bundles together may name at most four pins. The qualification rules are in the Craft native spec.

Docs engine settings

documents.enabled needs three clean absolute paths of at most 100 bytes each, all different from one another. The service token must be a regular file with mode 0600. The Docs engine needs Unix sockets, so it does not start on Windows. A limit set to 0 uses the default. With documents.enabled, a negative or non-numeric limit stops the server from starting. The workbook engine and editor use CREWSHIP_GRIDCRAFT_SERVICE_SOCKET, CREWSHIP_GRIDCRAFT_SERVICE_TOKEN_FILE, CREWSHIP_GRIDCRAFT_EDITOR_BUNDLE_DIR, CREWSHIP_GRIDCRAFT_EDITOR_BUNDLES and CREWSHIP_EDITOR_RUNTIME_ORIGIN (YAML gridcraft.service_socket, service_token_file, editor_bundle_dir, editor_bundles and editor_origin); see Environment variables.

Page limit

A workspace may hold at most 100 pages by default (archived pages count). Pages, Designs, artifact projects, Documents and Workbooks all check the same limit and, when it is reached, refuse with 422 pages_limit and a message that states the limit. It is not an environment variable or YAML key: an instance administrator sets it at runtime (10 to 10000) and the value is kept in the database. Lowering it never deletes pages; it only blocks new ones.
Pages marked as test items (created_by_test) still count toward the limit; excluding them is a possible follow-up. See Admin API and Admin CLI.

Artifact storage limits

Every artifact family (versions, proposals, Design, Data, documents, Slides, GridCraft and Mooring) counts against one aggregate budget: 32 GiB per workspace and 64 GiB per instance by default. When a limit is reached, writes are refused with 413 artifact_storage_quota and nothing is deleted to make room. These are not environment variables or YAML keys: an instance administrator sets them at runtime and the values are kept in the database.
Limits must be between 1 MiB and 1 PiB. Lowering a limit below current usage only refuses further growth. The counters are maintained by database triggers; after a restore, or if get disagrees with what is stored, rebuild them with crewship admin instance artifact-storage recompute (add --dry-run to preview the drift). It never deletes data. See Admin API and Admin CLI.

Build-time UI variables

The web UI is a static export, so these variables are inlined when it is built. Export them before pnpm build (or make build, which runs it) and deploy the new binary with its embedded UI; changing them on a running server has no effect. Each one is on only when its value is exactly true. The repository’s .env.production sets NEXT_PUBLIC_CHAT_ARTIFACT_PROJECTS and NEXT_PUBLIC_CHAT_CRAFT_LEASE to false explicitly, and none of the other variables. A default production build therefore hides every screen in the matrix above that needs a build-time variable. The build-profile line of that file names the profile, and the tests in lib/__tests__/build-profile.test.ts and lib/__tests__/feature-flags.test.ts hold it to one of three shapes: A declared preview is reviewed like any other change. A branch built for the slot carries it as .env.production unchanged, in a commit of its own. e2e/preview-profiles/dev2.env is the dev2 preview. Code bound for main must carry the main profile; an unknown ref counts as bound for main. CI on main checks only the main profile; a release or preview profile is checked by the same tests on its own branch. These checks cover the checked-in file only. Values exported in the build environment take precedence over that file, so a build that exports flags is outside them:

Check what is on

List the workspace flags with their instance default, override and effective value (columns abridged):
Ask the server whether artifact projects are available to the current workspace (GET /api/v1/pages/artifacts/availability). The answer includes the environment bypass:
Add --agent <id> (query agent_id) to ask whether that agent’s crew may create artifact projects under the workspace artifact-creation policy. The answer then also carries can_create; a crew outside the policy returns can_create: false with code: "artifact_crew_not_allowed", and the chat composer hides Project creation for that agent:
Ask which document engines the instance serves (GET /api/v1/documents/status):
enabled is true when the Docs engine is running. wordcraft_native and gridcraft_native are true when native Craft is on with a qualified Word or Sheet profile. A successful answer is not enough: the web UI offers New Doc only when at least one of enabled, wordcraft_native or gridcraft_native is true (or a separately qualified Mooring Word integration is available). The response above, with every value false, offers nothing. gridcraft_native reports the native Sheet profile, not the legacy live workbook editor. Check that editor by opening an existing workbook with its workspace flag enabled; doc status does not certify the legacy worker service.

Upgrades

The flags on this page arrive through ordinary migrations and start off, except artifact_projects, whose instance default an upgrade turns on unless an administrator had changed it (see Turning Projects off). For the other surfaces, nothing changes for users until you enable the flags, set the startup switches and deploy a UI build with the matching variables. To roll a surface back, undo it in the layer that turned it on. Stored artifacts stay in the database in every case.