Custom metadata

Compatibility status

FC Agent Sandbox does not currently support custom file metadata. Regular file reads and writes and standard file information returned by getInfo(), list(), and rename() are unaffected.

Custom file metadata and sandbox control-plane metadata are separate capabilities:

• Custom file metadata is passed to sandbox.files.write(..., metadata=...) and stored with a file. FC Agent Sandbox does not currently support this capability.

• Sandbox control-plane metadata is passed to Sandbox.create(..., metadata=...) to label, query, and correlate sandboxes. This limitation does not affect sandbox metadata.

Failure behavior

The files.write() signature in Python SDK e2b==2.31.0 accepts metadata. This does not mean that the current backend supports the capability.

Sandboxes currently report envd 0.5.2, while the SDK requires envd 0.6.2 or later for custom file metadata. The call fails before the SDK sends the write request:

e2b.exceptions.TemplateException:
File metadata requires envd 0.6.2 or later.

This exception does not mean that the Python parameter is missing, and it does not affect regular file operations that omit metadata. Upgrading the SDK or changing only the runtime version declaration does not bypass the limitation. The runtime must fully support metadata validation, lowercase keys, and extended-attribute persistence.

Alternatives

Until custom file metadata becomes available, use one of these approaches:

• Store file labels in your application database or object storage, keyed by sandbox ID and file path.

• Write a JSON manifest next to the files to map paths to business labels. If the data must persist across sandboxes, store both the files and manifest in external storage such as NAS or OSS.

• If you only need to label or query a sandbox, use sandbox control-plane metadata; do not treat it as file metadata.