Skip to Content
Platform
Core ConceptsFiles & Shares

Files & shares

Files are the versioned artifacts a runtime reads and writes; a share is a read-only link that lets others see, and fork from, your work.

Runtimes don’t just emit telemetry; they produce output you can keep. Files are those durable artifacts, and shares are how you hand a file or a conversation to someone else, read-only.

Files

A file is a durable artifact stored against a project. Runtimes read and write files during a task; anything a run writes to its outputs persists as a file you can download later or feed into subsequent work. Each file records who created it and the task it came from.

Versioning

Files are versioned. Writing new content to an existing file produces a new version rather than overwriting in place, so an artifact’s history is preserved and you can always trace a file back through the versions that came before it.

An artifact written by one run can be read by a later one. Treat a run’s outputs as the durable surface: anything you want to reuse should be written there, where it persists as a file.

Shares

A share is a read-only link to a single resource. It widens who can read that resource without ever granting write access or changing ownership: a share only ever adds read access. Two resource families can be shared:

  • Files: hand someone a downloadable artifact.
  • Conversations: give someone the replayable record of a task.

A share can target the whole project (everyone in it) or a single member, and only the grantor can revoke it. Each share resolves to a canonical URL for the underlying resource, so following the link fetches the file or conversation directly.

Tasks are not shareable. A task is an owned lifecycle object, not a shareable resource. To let someone reproduce a task, share its conversation instead.

Sharing enables forking

Sharing a conversation is what makes a task reproducible by someone else. When you share the conversation from a task, the recipient can fork a new task from it: spinning up a fresh execution seeded from that shared record to reproduce, debug, or build on what happened. The share is the capability that unlocks the fork; without it, the conversation (and the task behind it) stays private to its owner.

  • Tasks: the executions that read and write files. A fork starts a new task from a shared conversation.
  • Conversations: the replayable records you share to enable forking.
Last updated on