File Metadata

Get metadata

Python example:

sandbox.files.write("/tmp/demo/input.txt", "hello\n")

info = sandbox.files.get_info("/tmp/demo/input.txt")
print(info.name)
print(info.type)
print(info.path)
print(info.size)
print(info.permissions)

TypeScript example:

await sandbox.files.write("/tmp/demo/input.txt", "hello\n");

const info = await sandbox.files.getInfo("/tmp/demo/input.txt");
console.log(info.name);
console.log(info.type);
console.log(info.path);
console.log(info.size);
console.log(info.permissions);

Other fields

In addition to the fields above, EntryInfo also includes owner, group, and modification time.

Python example:

info = sandbox.files.get_info("/tmp/demo/input.txt")
print(info.owner)
print(info.group)
print(info.modified_time)

TypeScript example:

const info = await sandbox.files.getInfo("/tmp/demo/input.txt");
console.log(info.owner);
console.log(info.group);
console.log(info.modifiedTime);

Directory management

Python example:

workdir = "/tmp/demo"

sandbox.files.make_dir(workdir)
sandbox.files.write(f"{workdir}/input.txt", "hello\n")

items = sandbox.files.list(workdir)
print(items)

sandbox.files.rename(f"{workdir}/input.txt", f"{workdir}/renamed.txt")
print(sandbox.files.exists(f"{workdir}/renamed.txt"))

sandbox.files.remove(workdir)

TypeScript example:

const workdir = "/tmp/demo";

await sandbox.files.makeDir(workdir);
await sandbox.files.write(`${workdir}/input.txt`, "hello\n");

const items = await sandbox.files.list(workdir);
console.log(items);

await sandbox.files.rename(`${workdir}/input.txt`, `${workdir}/renamed.txt`);
console.log(await sandbox.files.exists(`${workdir}/renamed.txt`));

await sandbox.files.remove(workdir);

File status

Use sandbox.files.exists(path) to check whether a file or directory exists before running a command.

Python example:

if not sandbox.files.exists("/tmp/demo/config.json"):
    sandbox.files.write("/tmp/demo/config.json", "{}\n")

TypeScript example:

if (!(await sandbox.files.exists("/tmp/demo/config.json"))) {
  await sandbox.files.write("/tmp/demo/config.json", "{}\n");
}

Wait for file generation

When you need to wait for changes inside a directory, use Watch for Changes. If you only need to wait for a single file to appear, bounded polling with sandbox.files.exists() also works.

When polling, always set a timeout and a maximum retry count so the task does not keep resources for too long.

Custom metadata

FC Agent Sandbox does not currently support attaching custom metadata through metadata when writing a file. Regular file information returned by getInfo(), list(), and rename() is unaffected. For details, see Custom Metadata.

Recommendations

• Application code should not build paths from unvalidated user input, to avoid unauthorized access outside the intended working directory.

• Before deleting a directory, confirm the path prefix so you do not accidentally remove a system directory or a shared workspace.

• Files that need long-term retention should be written to external storage. Local sandbox files are suitable only for the lifetime of the current task.