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 isartifact_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:
--enabled
is a boolean flag, so turning the default back off needs --enabled=false:
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):
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 exactlytrue; 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 accepttrue 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 undercraft_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 with422 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.
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 with413 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.
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 beforepnpm 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):GET /api/v1/pages/artifacts/availability). The answer includes the
environment bypass:
--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:
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, exceptartifact_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.