Function Compute:Custom Metadata

Write metadata

If your Python SDK version supports the metadata parameter, you can write metadata as follows:

info = sandbox.files.write(
    "/tmp/report.txt",
    "hello\n",
    metadata={
        "author": "alice",
        "purpose": "demo",
    },
)

print(info.metadata)

TypeScript example:

const info = await sandbox.files.write("/tmp/report.txt", "hello\n", {
  metadata: {
    author: "alice",
    purpose: "demo",
  },
});

console.log(info.metadata);

When you write multiple files in one call, the same metadata set is applied to all files in that write operation.

Python example:

sandbox.files.write(
    "/tmp/input/a.txt",
    "A\n",
    metadata={
        "source": "import",
    },
)
sandbox.files.write(
    "/tmp/input/b.txt",
    "B\n",
    metadata={
        "source": "import",
    },
)

TypeScript example:

await sandbox.files.write(
  [
    { path: "/tmp/input/a.txt", data: "A\n" },
    { path: "/tmp/input/b.txt", data: "B\n" },
  ],
  {
    metadata: {
      source: "import",
    },
  },
);

Read metadata

Python example:

info = sandbox.files.get_info("/tmp/report.txt")
print(info.metadata)

entries = sandbox.files.list("/tmp")
for entry in entries:
    print(entry.name, entry.metadata)

TypeScript example:

const info = await sandbox.files.getInfo("/tmp/report.txt");
console.log(info.metadata);

const entries = await sandbox.files.list("/tmp");
for (const entry of entries) {
  console.log(entry.name, entry.metadata);
}

Limits

• Metadata keys and values should use printable ASCII characters.

• Keys are converted to lowercase by the sandbox, so the casing you read may differ from the casing you wrote.

• Overwriting a file replaces the previous metadata instead of preserving it.

• This capability depends on file extended attribute support in the runtime. E2B requires envd version v0.6.2 or later in the template. If you use an older custom template, verify that the runtime version supports this capability first.

• The Python SDK metadata parameter requires a recent version. If your current SDK does not support it, upgrade the SDK or write metadata through the TypeScript SDK.

Recommendations

Metadata is suitable for lightweight business labels. It is not suitable for access control, audit logs, or persistent databases. Business state that must be retained, queried, or shared across sandboxes should be written to external storage.