Artifact Server product and architecture proposal

The server stores seven kinds of records:

• Project: a stable project ID, name, installation ID, creation time, and archive state.
• Artifact: the same item over time, including its project, name, access setting, optional tags, and current version.
• Version: the saved copy created when someone publishes. It never changes and points to one manifest.
• Manifest: the canonical, ordered list of file paths, fingerprints, sizes, media types, and the entry file.
• File: one file in a version, including its name, folder path, file type, size, and SHA-256 fingerprint.
• Source: an optional note about an upload, approved local import, or agent.
• Action: who published, restored, changed access, changed tags, or deleted the artifact and when.

A SHA-256 fingerprint is calculated from a file's exact contents. If one byte changes, the fingerprint changes.

Project identity is enforced by every repository query, upload, browser session, HTTP request, MCP tool, action record, backup, and restore. Archiving a project stops new artifacts and versions but preserves existing links and history. The first release does not destructively delete a nonempty project.

Paths are portable relative paths. The server rejects absolute paths, dot segments, .git path components, backslashes, null bytes, percent-encoded separators, symlinks, special files, duplicate normalized names, and names that collide only by case or Unicode normalization. The entry file must exist in the manifest.

The manifest is serialized in one fixed order and hashed. That manifest digest, not an operating-system directory walk or Git commit, is the portable identity of the saved file set and the basis for comparison and idempotency checks.

The two access settings control reading. They do not grant permission to publish or administer.

One Plannotator organization connects to one Artifact Server installation. Each Plannotator project pairs with one Artifact Server project.

Artifacts belong to projects, not workspaces. A workspace stores references to artifacts and exact versions in its project. Moving, unfiling, or deleting a workspace does not move or delete the project artifact.

Plannotator checks whether a person or agent may use the project or workspace. It then sends Artifact Server a short-lived signed request limited to the paired project and one operation. A workspace viewer may open one referenced artifact or exact version but cannot list or change the project artifact library. WorkOS tokens and browser cookies are not forwarded.

Connecting a server does not silently move existing artifacts. Pairing an existing Artifact Server project with a Plannotator project requires an explicit administrator action and preserves all artifact and version IDs.

The complete connection and review behavior is described in the Plannotator integration handoff.

1. The client creates an upload and receives a unique staging location.
2. It sends regular files directly to disk or cloud file storage.
3. The server verifies every size and SHA-256 fingerprint and rejects unsafe or colliding paths.
4. The client names the entry file, states the version it started from, and sends one idempotency key for the request.
5. The server writes missing content-addressed blobs without overwriting an existing blob, saves the immutable manifest and version, and updates the current-version pointer in one database transaction.
6. A retry with the same key returns the stored result. Scheduled work deletes only expired staging uploads in the first release.

Object storage and the database cannot commit atomically. The safe order is stage, verify, write each blob once, then commit the database records. The first release intentionally keeps committed or orphaned blobs. Reference garbage collection is added only after a lease-based or mark-and-sweep design survives crash, retry, and concurrent-publish tests.

Artifact Server always saves the version record, file list, fingerprints, and published files first. A configured provider is only available infrastructure; it creates no repository and copies no version. When an enabled project's version is durable, the server copies it in the background into one private repository for that artifact. Each saved version maps to one commit, and the database records the Git commit identifier.

Git never supplies the files used to open the artifact. If the Git provider is unavailable, the saved version remains available and the server retries the Git copy.

ARTIFACT_SERVER_GIT_HISTORY_PROVIDER=off
# Explicit opt-in when the installation has access:
ARTIFACT_SERVER_GIT_HISTORY_PROVIDER=cloudflare-artifacts

The variable is absent or off by default, and there is no auto value. Off means no Git implementation, binding, credential, or provider request. The Cloudflare runtime uses a configured Workers binding; other runtimes use Cloudflare's REST control plane with operator-supplied credentials.

Every project has one durable Git-history switch, and it starts off. An administrator first sees a current-inventory estimate for repositories, versions, operations, copied bytes, and pointer bytes. Enabling that project schedules a bounded, resumable backfill. There is no installation-wide mode, inheritance rule, or automatic enablement for future projects. Browser, HTTP, and MCP use the same authorized, naturally idempotent project operation.

Disabling a project or provider stops applicable mirror work but does not delete remote repositories, jobs, or mappings; re-enabling the same project and provider resumes. Changing the persisted provider account or namespace after repositories exist requires a separate migration instead of silently moving or deleting history.

Permanent removal uses an operator-only artifactserver history purge plan/apply command with exact installation-ID confirmation. It is resumable and cannot delete primary artifact data or the Cloudflare namespace. No purge surface exists in HTTP, MCP, or the member application.

Authenticated HTTP and MCP capability discovery separately reports provider state and each project's disabled, waiting, backfilling, ready, degraded, or budget-limited state. It never exposes credentials or repository coordinates. Git provider health never controls the application's readiness check.

Deterministic per-file and per-version limits leave excluded bytes in the normal file store while path, media type, size, and fingerprint stay in the Git pointer manifest. An optional logical copied-byte budget pauses new provider writes before overshoot without affecting saved versions. Cloudflare Artifacts currently limits each repository to 10 GB and its published pricing requires Workers Paid and bills aggregate operations and storage, not a per-repository fee. Estimates are guidance rather than invoice guarantees.

Each installation environment persists one exclusive Cloudflare account and namespace identity. The adapter has no account-wide or namespace-delete operation. Live tests use a separate artifact-server-test- namespace, unique run-prefixed repositories, a separate revocable token, hard bounds, and cleanup restricted to a durable run manifest. Existing namespaces such as workspaces remain outside that route and cleanup boundary, although the Cloudflare control credential and billing remain account-wide. Access is not universal, so the product remains complete when the provider is unavailable or disabled.

Git repositories remain private. A public artifact link never grants Git access or exposes earlier versions through a Git remote.

Hosted deployments use an application address plus a unique content host for each saved version:

app.example.com
v12-7f3a.content.example.net

The content domain is separate from the application's registrable domain. Each saved version receives its own origin, so root-relative paths and service workers stay inside that version. Application cookies are host-only. The content service accepts only GET and HEAD, sends no credentialed CORS responses, and cannot change application data. The application also enforces CSRF tokens, trusted origins, and Fetch Metadata on browser mutations.

For account-required content, the application checks the viewer and creates a short-lived, single-use bootstrap token for one version host. That host exchanges the token for a Secure, HttpOnly, host-only content cookie. Direct loopback HTTP uses the host-only, HttpOnly browser exception because browsers reject a Secure cookie on *.localhost. Relative CSS, JavaScript, image, and font requests then work without exposing an application credential. Private content is not placed in a shared CDN cache in the first release.

The current public version uses immutable cache keys and may be cached by a CDN. Publishing a new current version or changing the artifact to account required purges the previous public version from supported caches and stops new public origin requests. It cannot revoke copies already downloaded or retained outside the server. The interface must state that limitation before it is first made public and again before access is changed.

The stable application link checks access and selects the current version. The version link stays fixed. A static-site artifact returns 404 for a missing path. A single-page application may return its entry HTML only for browser navigation requests; a missing JavaScript, stylesheet, image, or other asset still returns 404. Responses use an explicit media type, nosniff, ETag, and safe download disposition. Media supports byte ranges.

Local file import is available only through the local helper, when the helper and server can read the same disk. An administrator configures allowed root folders. The helper resolves the real path, rejects symlinks and special files, verifies that every file remains inside an allowed root, and copies the current bytes into staging. Changing the original file never changes a saved version.

A remote server never accepts a client filesystem path. The agent uploads the bytes. The first release does not fetch arbitrary source URLs, which avoids a server-side request path into private networks and cloud metadata services.

A committed version cannot be edited or deleted by itself. Deleting an artifact creates a tombstone and stops every application and content link. The first release does not immediately remove blobs, because reference reclamation must not race a publish, retry, backup, or restore.

A team deployment is not ready until backup and restore preserve installation, artifact, version, manifest, and action IDs and an integrity check confirms that every referenced blob exists. Retention duration, tombstone duration, physical deletion, recovery-point target, and recovery-time target remain deployment policy and release-gate decisions.

Every artifact reference includes the Artifact Server address, artifact ID, and, when needed, the exact version ID. An artifact ID by itself is not enough because the same person may use a local server and one or more team servers.

The artifact route resolves the target in this order:

1. An Artifact Server address, artifact link, or named server stated in the current request.
2. The server contained in an artifact reference already present in the conversation.
3. The server used by the artifact most recently published or opened in the current conversation.
4. The current project's configured default server.
5. The user's default server.

If those rules do not produce one server, the agent asks whether to use the local or team server. It never publishes to, reads from, or opens an artifact from a guessed server.

The Artifact Server command-line program keeps named connection profiles such as local and team. A project may contain an optional, non-secret .artifactserver.json file that names its default server address, connection profile, and stable project ID. It never contains a credential. A project display name is resolved through the selected server and is never passed where an ID is required. User defaults, recent artifact references, and the local server's current address remain in user-local state. Access credentials stay in the MCP client or operating-system credential store; they are never written into the project file.

The two credential stores are intentionally separate. artifactserver connect registers MCP in an AI client. artifactserver auth login <server> signs the command-line program into an exact server origin, opens browser approval when supported, and stores the renewable credential in the operating-system credential store. Local mode uses private user-only state without browser login or a visible key. CI uses a scoped service credential from its secret manager.

The MCP artifact_get tool returns the exact full-screen Review address for the current version. artifact_open returns that Review address and the raw immutable content address for the chosen artifact and version. Agents use the Review address for human handoff and never label the raw content address as Review. A local helper may ask the operating system to open an address directly. A remote server only returns addresses; the agent or client opens them on the user's computer. The remote server never attempts to start a browser on the server machine.

A successful publish instead returns a durable links.review address for the exact version. MCP instructions and the publish tool's text result tell the agent to give that full-screen commenting link to the user first, then mention the immutable raw links.version address when it is useful. The credential-free review address uses normal team authentication.

The skill uses the open Agent Skills folder format and ships in the official Artifact Server repository under skills/artifact-server. Its artifact and server-operation references stay separate inside that folder. After the private plannotator/artifact-server repository is published, compatible clients can install the skill with npx skills add plannotator/artifact-server. A skills.sh listing follows the same controlled release.

The skill name is the portable contract. A client may display it as a slash command, but Artifact Server does not depend on slash-command spelling because that behavior differs between clients. The skill contains a short main instruction file. Detailed upload errors and deployment-specific procedures live in separate reference files that the agent reads only when required.

The artifact route does not contain a cloud-specific configuration. It resolves the target, uses artifactserver publish when it must read a file on the user's computer, and calls artifact_capabilities before choosing a server-supported upload path. Operations that only need information already on the server may use MCP or the command-line program. The same installed skill therefore works with a laptop, private server, Kubernetes, or hosted service.

The command-line program owns its authenticated server profile and hides the create, upload, retry, and commit requests behind one publish action. Any temporary upload address is short-lived, limited to one declared file, and redacted. It is not copied from MCP or shown to the model. An exact retry after a lost response is safe. The server still verifies the declared size and SHA-256 fingerprint before it saves a version.

The skill is versioned with Artifact Server releases and tested for correct activation, routing, and output. It tells the user when the connected server is too old for a requested operation. The release process tests realistic requests that select each route and similar requests that must not activate it.

Format and distribution follow the current Agent Skills specification and the skills.sh directory and installer.

Ordinary OpenID Connect sign-in proves who a person is in a browser. It is not, by itself, enough for an MCP client. Remote MCP also needs discovery, approval, a credential issued for the exact /mcp address, renewal, and revocation.

The primary endpoint uses MCP revision 2026-07-28 and the official TypeScript SDK version 2. Every request is independent. There is no initialization handshake, MCP session identifier, sticky load-balancer route, or permanent event stream. The client calls server/discover to learn supported protocol versions and server instructions, then uses tools/list and resources/templates/list for the current catalog. It calls artifact_capabilities for deployment-specific limits and publishing behavior.

• Remote external-storage installations use HTTP POST /mcp.
• Normal results use JSON. Request-scoped server-sent events are reserved for useful progress.
• The first release rejects subscriptions/listen. It is enabled only after the deployment has a real shared event service.
• Modern GET /mcp and DELETE /mcp return 405. Older MCP behavior is an isolated, optional compatibility path.
• Every durable change has an application idempotency key. A change to an existing artifact also includes the version the caller started from. A broken connection cannot silently publish twice or overwrite newer work.

In the hosted service, WorkOS owns the authorization page, approval screen, authorization codes, client registration, access credentials, renewal, and revoke behavior. Artifact Server remains the protected service. It publishes the standard metadata that tells clients where to sign in and verifies every credential before an MCP request reaches product code.

The credential must name the exact Artifact Server MCP address as its audience. WorkOS identity scopes do not grant artifact permissions. Artifact Server also verifies the issuer, signature, expiry, and user, then maps that user to an account admitted to this installation. Artifact Server does not copy WorkOS organizations into a second organization system. The same membership and service-capability checks used by the browser still apply.

The hosted authorization service enables Client ID Metadata Documents first and keeps Dynamic Client Registration temporarily for clients that still require it. Authorization uses the browser authorization-code flow with S256 PKCE. WorkOS credentials never pass to file storage, background workers, or published websites.

The exact wire behavior, metadata, token checks, self-hosted modes, and release test matrix are recorded in the Artifact Server MCP engineering baseline.

artifact_capabilities
artifact_list
artifact_get
artifact_open
artifact_create_upload
artifact_commit_upload
artifact_set_visibility
artifact_set_tags
artifact_version_list
artifact_diff
artifact_restore_version
artifact_delete

Each tool has a strict input and output schema. Publishing returns the artifact, immutable version, canonical manifest digest, and browser links. Management tools return the exact artifact or deletion state they changed. Git is not part of the MCP result contract.

One read-only MCP resource returns the canonical manifest for a selected version. Full websites and file bytes return ordinary HTTPS links instead of being copied into the AI conversation.

Remote agents use HTTP POST /mcp. On the same computer, a small command-line helper or loopback listener uses a local token and calls the same product service. The helper never writes directly to the database.

Every change includes the version the agent believes is current. If newer work exists, the server returns the actual current version and tells the agent what to read before trying again. Retrying the same idempotency key returns the same result. Starting a new publish with a new key creates a new version even when the bytes match an earlier version. Creating a brand-new artifact has no earlier version. Creating an uncommitted upload is temporary preparation and does not alter an artifact.

The released July 2026 protocol is the product target. Compatibility with older MCP clients is not mixed into the modern path. If a required client still uses the older initialization handshake, an administrator can enable a separately tested compatibility handler.

Release testing covers current Codex, Claude Code, Claude.ai, and at least one DCR-only client. Each is tested with a fresh connection, an old cached connection, an expired credential, a revoked grant, a wrong audience, an invalid origin, and a user who has not been admitted to that installation. Claude.ai can reach only Artifact Servers exposed to Anthropic's cloud; a server reachable only inside a private network is not supported there.

The product ships as a downloadable local package that does not require Docker, one optional container image, Compact Compose and External-storage Compose for one server, a Helm chart for Kubernetes, a pinned Alchemy project for Cloudflare, and pinned Pulumi projects for AWS and GCP. Operators use Compose, Helm, Alchemy, or Pulumi directly. Artifact Server does not hide their plans behind another deployment command. Each package emits the same required URLs, resource IDs, and secret-free support information.

Teams that already run Kubernetes use the Helm chart on EKS, GKE, AKS, or their own cluster. The chart installs only Artifact Server and connects to the team's existing Postgres, file storage, secrets, DNS, TLS, and Ingress or Gateway. The AWS and GCP Pulumi projects are turnkey alternatives for teams that do not want to operate Kubernetes. Azure teams use the same Helm chart on AKS. The AWS default uses ECS Fargate; it does not create or replace an existing EKS cluster.

Browser login and MCP authorization are separate protocols even when they use the same identity provider. Team browser login uses WorkOS AuthKit or any OpenID Connect provider, configured directly on the installation; one installation configures one browser-login provider. Hosted MCP connections use WorkOS AuthKit. Private installations can use server API keys or a compatible authorization service. A single-user installation may rely on the operating-system account or a local token.

The product rules do not know which database or file storage is in use. Each deployment supplies small pieces of code for saving records, saving files, signing users in, and running cleanup work. The product rules do not call Node.js file functions or a specific database library directly. Optional Git handoff follows the same rule through one small provider interface.

• Laptop: one process runs directly on the host by default, with SQLite for records, files stored on disk by their SHA-256 fingerprints, and optional local file links. Cloudflare Artifacts may be configured through REST. Docker is optional.
• One server, compact: one process, SQLite in write-ahead logging mode, and one persistent data directory. Cloudflare Artifacts may be configured through REST. This profile does not support multiple application writers or claim failover.
• One server, external storage: the same image connected to existing Postgres and object storage through a supported adapter. The Compose package does not bundle those providers.
• Kubernetes: Postgres plus S3, Google Cloud Storage, R2, a tested compatible object store, or the preview Azure Blob adapter. Cloudflare Artifacts may be configured through REST. This is the official Azure path on AKS.
• Cloudflare: Workers for the application, D1 for records, R2 for files, and off-by-default Cloudflare Artifacts handoff through a configured Workers binding. External Postgres is supported through a separate adapter but is not the default.
• AWS: ECS Fargate, RDS PostgreSQL, and S3 through the AWS Pulumi project.
• GCP: Cloud Run, Cloud SQL PostgreSQL, and native Google Cloud Storage through the GCP Pulumi project.

The storage boundary uses product operations such as “publish this version only if the current version has not changed,” not a generic function that sends raw SQL to any database. SQLite/D1 and Postgres keep their own migrations, indexes, transactions, and optimized queries. External-storage tests prove that publishing, access, versions, and cleanup behave the same.

The first external-storage package supports AWS S3 and Cloudflare R2 through its S3 adapter. Another S3-compatible service is supported only after it passes the same storage contract tests. Native Google Cloud Storage ships with the GCP package. The Azure Blob adapter is preview-only until a live Azure qualification passes. Adding an adapter does not change artifact or version rules.

Every package receives the installation name, environment, region, pinned application image, application domain, separate content domain, initial administrator email, public or private ingress choice, replica limits, CPU, memory, database size, backup retention, deletion protection, network choice, and optional WorkOS and telemetry references. Secret inputs are references to the provider secret manager, not secret values in ordinary configuration.

Every successful deployment returns the installation ID, application, MCP, health, and readiness addresses, content domain, deployed image digest, runtime, database, file-store, workload-identity, network, and secret resource IDs, log destination, infrastructure-state location, and support-manifest location. It never returns a password, API key, access token, signed file address, or cloud credential.

Pulumi projects require an existing state backend or Pulumi Cloud and a selected secrets provider. The Cloudflare project uses Alchemy's Cloudflare state store for team and automated deployments. The main application stack does not create the bucket that contains its own infrastructure state.

Local use on the same computer needs none of them. Artifact Server binds to loopback and uses *.localhost. The same rule applies to an optional local container reached only from that computer.

A one-server installation opened from other devices needs HTTPS routing for the application address and the wildcard content address. Caddy is the documented example only when the team has no existing reverse proxy. Nginx, Traefik, HAProxy, or a company gateway can be used when it passes the same routing, upload, and TLS tests. Kubernetes uses its Ingress or Gateway. Cloudflare and managed-cloud packages use their provider edge. Those deployments do not run Caddy.

D1 stores small relational records: installations, accounts, artifacts, saved versions, file paths, fingerprints, access settings, credentials, and cleanup state. R2 stores the artifact files. An artifact file never goes into D1.

The hosted service starts with one production D1 database. The authenticated installation identity is bound before product code reaches storage. Composite database keys, R2 prefixes, cache keys, signed links, jobs, backups, and restore paths all include that trusted identity through a tenant-scoped storage API. Remembering to add an installation_id filter is not an adequate boundary.

The proposal does not claim that adding D1 databases is automatic. Before a second database, the team must choose and load-test either a D1 directory plus safe binding rollout or an external Postgres control plane. That decision must cover provisioning, tenant moves, retries, backups, restore, and rollback.

D1 has a hard 10 GB limit per paid database and processes writes through one primary database. Global read replicas can reduce read latency when the Sessions API is used, but they do not scale writes. Artifact metadata remains much smaller than the files in R2. Measurements decide whether D1 sharding or external Postgres is the safer growth path.

D1 scales to zero and includes substantial monthly reads and writes on Workers Paid. R2 stores Standard files for $0.015 per GB-month beyond the included allowance and does not charge for internet data transfer. External Postgres would add another provider, region, connection pool, credentials, backups, and another network failure path.

Publishing across D1 and R2 follows this order:

1. Upload each file to a unique staging key.
2. Verify size and fingerprint, then create the final blob without overwriting an existing object.
3. Commit the manifest and version in D1 only if the current version is still the expected version.
4. Return the recorded result when the same idempotency key is retried.
5. Delete only expired staging uploads in the first release. Keep committed and orphaned blobs until a concurrency-safe garbage collector exists.

Current platform references: D1 limits, D1 pricing, D1 global read replication, and R2 pricing.

• Local: artifactserver connect works in every advertised local client without browser sign-in, Docker, a visible key, copied secret, or log inspection; one service then publishes one file and a complete static site, opens the unique version host, compares versions without Git, retries safely, and survives a restart.
• Private team: account-required subresources load, forbidden mutations fail, backup and restore preserve IDs, and cross-tenant and hostile-path tests pass on one server and Kubernetes.
• Optional Cloudflare package: WorkOS MCP sign-in, R2 staged uploads, D1 transactions, public cache purge, private no-cache delivery, tenant isolation, and a restore drill pass. Service-operator policy is separate from core OSS conformance.
• Plannotator connection: one-click approval, cross-organization rejection, signed-request scope, one-use browser links, disconnect, key rotation, exact-version comments, hostile review-page tests, and private-route failure and recovery all pass.
• Major clouds: every provider package passes install, upgrade, rollback, backup, restore, private-network, and removal tests before support is advertised.
• All releases: browsers open native file types without a conversion service; arbitrary URL fetch is absent; optional Git failure never blocks or loses the primary saved version.