Files

Use druks.files for an agent file that must outlive its sandbox. Druks pulls the file from the sandbox. It stores immutable bytes under a stable ID and returns a File handle. Apps declare files and decide when to delete them. Apps do not implement transport or file routes.

Receive a file from an agent

Annotate the file in the agent output contract. Every nested object must also inherit AgentOutput. The harness needs a strict schema at every object node.

from druks.agents import AgentOutput
from druks.files import File


class SurveyShot(AgentOutput):
    screen: str
    viewport: str
    image: File


class SurveyOutput(AgentOutput):
    findings: list[str]
    shots: list[SurveyShot]

The harness sees each File field as a string path. The agent writes the file inside its workspace and reports that path. Druks accepts only a regular file whose resolved path stays inside the workspace. One file can contain at most 10 GiB. A missing path, a symlink escape, or an oversized transfer fails the agent call. The returned value has a stable identity and metadata:

shot = result.shots[0]
shot.image.id
shot.image.name
shot.image.size
shot.image.content_type
shot.image.url
content = await shot.image.open()

url is /api/files/{id}. The route uses the normal Druks identity gate. It shows images, PDF, and plain text inline. It downloads all other content. The route sends X-Content-Type-Options: nosniff and validates the file with its SHA-256 ETag.

Pass a file to another agent

Pass the File as ordinary agent context:

analysis = await NightWatch.analyze(image=shot.image)

Before the agent starts, Druks copies each stored file into the call directory in the sandbox. The prompt context receives the sandbox path. A deleted file or missing stored content stops the agent call before it starts.

Keep a file on an app row

Use FileField for one file reference. It stores a real foreign key to the platform files table and does not copy the bytes.

from sqlalchemy.orm import Mapped, mapped_column

from druks.db import Base
from druks.files import File, FileField


class Shot(Base):
    __tablename__ = "night_watch_shots"

    id: Mapped[int] = mapped_column(primary_key=True)
    image: Mapped[File] = FileField()

A read of the app row loads the handle metadata in the same query. Access to image.id or image.url does not start another query. Use one app row for each file in a collection.

Delete a file

If app policy says that the file is no longer usable, delete it:

await shot.image.delete()

Deletion is immediate for reads and file routes. Druks keeps the row as a tombstone so an app foreign key remains valid. An hourly task removes only the stored bytes after a 24-hour grace period. An interrupted durable operation can leave a file without a reference after an agent retry. A worker failure can also leave canonical bytes without a row. This can occur between the rename and the step commit. This is the same retry boundary as other side effects. Druks does not remove this rare crash data in version 1. Files do not cover app-generated bytes, browser uploads, remote storage, or list-valued fields.

Get started

Understand Druks

Build an app

Operate

Contribute

Receive a file from an agent

Pass a file to another agent

Keep a file on an app row

Delete a file

​Receive a file from an agent

​Pass a file to another agent

​Keep a file on an app row

​Delete a file

Receive a file from an agent

Pass a file to another agent

Keep a file on an app row

Delete a file