Mount a volume

By default a component has no filesystem. It starts with no preopened directories, so wasi:filesystem cannot open anything until you grant it one. Filesystem access is a capability you mount, the same deny-by-default posture as network egress. This guide grants a directory.

You mount filesystem access in two parts: declare a volume on the workload's spec.volumes, then mount it into a component at a path with a volumeMount. There are two kinds of volume:

• Ephemeral (ephemeral: {}): a scratch directory that starts empty and lasts as long as the workload. Use it for working files a component needs while it runs.
• hostPath: a real directory on your machine that you name explicitly. Use it to hand a component your files. Scope it narrowly, and prefer read-only.

Mount a volume

Add the volume and the mount to the workload spec. Desktop keeps each workload as YAML at workloads/<namespace>/<name>.yaml in its state directory (run cosmonicd paths to find it):

spec:
  volumes:
    - name: scratch
      ephemeral: {} # starts empty, lives as long as the workload
    - name: notes
      hostPath:
        path: /Users/you/notes # a real directory on your machine
  components:
    - name: my-component
      image: ghcr.io/you/my-component@sha256:…
      localResources:
        volumeMounts:
          - name: scratch
            mountPath: /scratch
          - name: notes
            mountPath: /notes
            readOnly: true

With that, the component sees exactly two directories through wasi:filesystem: /scratch (read-write) and /notes (read-only). Everything else on your machine stays invisible to it.

• mountPath is where the directory appears inside the component. Your code opens /scratch, not the host path.
• readOnly defaults to false. Set it to true for a directory the component should read but never write. Prefer read-only for a hostPath mount unless the component genuinely needs to write.
• Mount the same volume into more than one component, each with its own volumeMount, to share a directory between them.

The same grant on the cluster

volumes and volumeMounts are the same schema Cosmonic Control uses on Kubernetes, so a filesystem grant you declare on your laptop carries to a cluster unchanged (see From Laptop to Cluster). For the cluster-side details, including sharing a volume between a component and a service sidecar, see Component Configuration.

Takeaway

A component gets no filesystem until you mount one. Declare a volume on spec.volumes, mount it into a component with a volumeMount at a mountPath, and that path, and only that path, becomes visible to wasi:filesystem.