Skip to main content
An artifact project is a private Page that holds a complete set of files (an entrypoint such as index.html plus its other files) as numbered, immutable versions. Every save is a whole new version; nothing is edited in place, and restoring an old version creates a new one. People read one version that the owner chose to share, while the owner keeps working on the latest one.
Artifact projects are on by default through the artifact_projects feature flag. A workspace manager can turn them off for one workspace (crewship feature-flag disable artifact_projects), and an instance admin for every workspace without an override (see Turning Projects off). While they are off, the create, version and comment routes answer 404. crewship page artifact availability reports {"enabled": true} or {"enabled": false} for the current workspace.

The Artifacts library

The /artifacts library is a browser view over the Pages the caller can read. NEXT_PUBLIC_ARTIFACTS_LIBRARY=true at build time opens this library and makes the Artifacts sidebar entry lead there. The Design build flag NEXT_PUBLIC_ARTIFACTS_DESIGN=true also opens /artifacts, but without the library flag the sidebar still leads to /pages; open /artifacts directly. When both flags are off, /artifacts sends the browser to /pages. With the library flag on, old Pages addresses lead to the library as well; see One address per artifact. The library lists each Page with its kind: Project, Dashboard, Page, Word, Sheet, Slides or Design. The kind comes from the server’s artifact_kind and artifact_profile or from the Page’s stored content, never from its name. For a versioned item it shows the shared version, or marks the item as not shared yet. The list, counts, filters, preview, header and New artifact all show the same library label for it: a design system is Design · Library, and an interactive project is an App, never a Dashboard. Archived, test and empty items appear only in their own views; nothing is deleted by hiding it. The search box accepts free text plus kind:, is: and owner: operators, for example kind:word is:private owner:you budget. is: takes private, shared, unshared (or draft) and empty.

One address per artifact

Every artifact opens at /artifacts/<id>?workspace_id=<workspace-id>, where <id> is its immutable page ID, never its slug. A pinned version adds &version=N. Links the server generates use this address: the url from crewship doc create and the project commands, and the page_path the agent project tool reports. With NEXT_PUBLIC_ARTIFACTS_LIBRARY in the build, older addresses keep working and replace themselves with that address, so Back does not return to them: An address stays on Pages when Pages is the only place that shows it: the panel editor (?mode=edit), the project source editor (?artifact=1&edit=1), and a page the Artifacts detail cannot open, such as an older Craft workbook. A refused or failed read also stays on Pages, which answers it the way it always did. The public share address /p/<token> is unchanged. None of these moves reveals whether an artifact exists. /artifacts/@<id> and /pages/<slug>/editor move by address alone, before any read. /artifacts/<slug> matches only the artifacts the person’s own catalog lists; anything else gets the server’s single answer for a page that is missing or not theirs, so the screen reads “This artifact doesn’t exist” in both cases. A restricted member is never redirected, and sees exactly what they saw before: every /pages address shows their catalog of declared Page actions, and /artifacts stays outside their access. The library reads (GET /api/v1/pages and GET /api/v1/pages/{slug}) are not on the restricted allowlist. Without the library flag, /artifacts/<id> opens on Pages: a project in the Pages project viewer, every other kind in its Pages detail.

Versions

Save this complete example as manifest.json:
Create version 1, publish version 2 against the exact latest version you read, then restore version 1 as a new version 3:
Every file is listed every time: a file left out of the manifest is absent from the new version. If someone else saved first, the server answers 409 with code artifact_version_conflict and stores nothing; the CLI does not retry. Read the latest version, compare, and publish again.

Sharing

A new project is private to its owner. share pins one retained version as the version everyone else reads:
Only the human owner can share. Sharing also ends the Page’s private audience, so from then on the ordinary Page permission model decides who opens it: the owner, a workspace ADMIN or OWNER, grantees and folder access. Grant levels decide what each of them may do with the project: The project response tells a client which of these apply through can_write, can_comment, can_share, can_restore and can_send_to_agent. Issue grants with crewship page grant (also available as crewship page share), for example crewship page grant demo --user ada@example.com --level comment; see Page commands.

Comments

A comment is bound to one version, one file and one element:
Replace COMMENT_ID below with the comment response’s id. Change the heading text in manifest.json while keeping its artifact-heading ID, then publish that complete manifest as version 4 before replying:
The selector is a single #id that matches exactly one element in that file, and --quote must still match the element’s text. Give elements stable artifact- prefixed IDs so they stay selectable across versions. A comment on an outdated version returns 409 (artifact_version_conflict); a selection that no longer matches returns 409 (artifact_anchor_mismatch). Neither stores anything. For an agent-created project with a source chat, add --send-to-agent to queue a task bound to that version. The CLI-created project above has no source chat; this flag does not connect one. A queued task is not proof that an agent received it. A comment from a Comment grantee is stored with a task, but it never starts the owner’s agent. A reply normally names a newer version that made the change; --needs-clarification replies on the original version and asks for a new selection.

Storage limits

Identical file contents are stored once per project. The owner’s project response carries quota with used_bytes, limit_bytes and warning, which turns true at 80 % of the limit. A save that would exceed the history limit returns 413 with code artifact_history_quota and keeps every existing version; keep your local draft. A creation at the workspace page limit (100 by default) returns 422 with code pages_limit instead; it says nothing about an existing project’s history. Other readers see a quota that names only their retention (latest-version-only or shared-version-only). Unsaved project source and comment drafts are kept encrypted in this browser under the Page ID. A draft that an older Crewship version kept under the Page address (slug) carries no Page identity, and that address may have belonged to another Page. Opening the project shows it as an older draft: it is never applied or deleted automatically. Use old source draft here (or Use old comment here) stores it encrypted under this Page and only then removes the old copy; Discard removes it. Only the account that typed it sees it. A draft follows the read right. If the Page read right goes, the server stops unwrapping the draft key and the browser deletes the draft, and the page says so. It does not come back with a later grant. If you lose only the write right the draft stays sealed in this browser and is offered to nobody, also in the tab where you typed it; it comes back if the write right does.

Give the agent its playbook

The server installs Crewship’s artifact playbooks into the skill catalog when it starts. It does not attach them to agents. Assign the one that matches the work to each agent that should do it; the skill is written into the agent’s workspace when its next run starts.
The tools still need their workspace flags. For Project, Dashboard, Slides and Design the agent’s crew must also be on the workspace artifact policy allowlist; native Word and Sheet tasks do not check that policy yet (#4681). Design needs the owner’s connected chat and Craft the owner’s task. The playbook only tells the agent how to use them. See crewship skill assign.

Choose a workflow