File metadata

Attach string key-value metadata while writing a file. AgentBox stores it with the file and returns it from file information, directory listing, and rename operations. In Go, these methods are Stat, List, and Rename.

mjs

import { Sandbox } from "@abox-dev/sdk";

const sandbox = await Sandbox.create();

try {
  await sandbox.files.write("/tmp/report.txt", "Quarterly report", {
    metadata: { author: "alice", status: "draft" },
  });

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

from agentbox import Sandbox


sandbox = Sandbox.create()

try:
    sandbox.files.write(
        "/tmp/report.txt",
        "Quarterly report",
        metadata={"author": "alice", "status": "draft"},
    )

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

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/abox-dev/sdk/packages/go-sdk"
)

func kill(sandbox *agentbox.Sandbox) {
	if _, err := sandbox.Kill(context.Background()); err != nil {
		log.Printf("cleanup sandbox: %v", err)
	}
}

func run() (err error) {
	ctx := context.Background()
	client, err := agentbox.NewClient()
	if err != nil {
		return err
	}
	sandbox, err := client.Sandboxes.Create(ctx, nil)
	if err != nil {
		return err
	}
	defer kill(sandbox)

	if _, err := sandbox.Files.WriteText(ctx, "/tmp/report.txt", "Quarterly report", &agentbox.WriteFileOptions{
		Metadata: map[string]string{"author": "alice", "status": "draft"},
	}); err != nil {
		return err
	}
	info, err := sandbox.Files.Stat(ctx, "/tmp/report.txt", nil)
	if err != nil {
		return err
	}
	fmt.Println(info.Metadata)
	return nil
}

func main() {
	if err := run(); err != nil {
		log.Fatal(err)
	}
}

Metadata has a few constraints:

keys and values must contain printable US-ASCII characters;
keys are converted to lowercase;
writing a file again replaces its previous metadata;
a shared metadata object applies to every file in a multi-file write.

Go also accepts metadata in each WriteFile passed to WriteBatch. Per-file values override matching keys in WriteFileOptions.Metadata.

Inside the sandbox, the values are available as user.agentbox.* extended attributes.

File metadata ​

File metadata