File (PaiFile)

A PaiFile is a versioned, namespace-scoped file resource stored on the Pai platform. Files can be uploaded from a local machine, mounted into agent sessions at a declared path, updated by agents at runtime, and downloaded by users.

CLI usage

# Upload a file
pai upload report.pdf

# Upload with a custom resource name and description
pai upload report.pdf --name q1-report --description "Q1 earnings analysis"

# List all files
pai get files

# Describe a file (version history, metadata)
pai get files q1-report

# Download the latest version
pai download q1-report

# Download to a specific path
pai download q1-report ./downloads/report.pdf

# Download a specific version
pai download q1-report --version 1

# Delete a file (all versions)
pai delete file q1-report

Mounting a file into a session

Add spec.files to your Agent or Session:

apiVersion: pai.io/v1
kind: Agent
metadata:
  name: report-analyst
spec:
  models:
    - anthropic/claude-sonnet-4-6
  system: |
    You are a report analyst. The report to analyse is at /data/report.pdf.
    When you are done, save your findings back to /data/report.pdf and call
    register_file to publish the updated version.
  files:
    - name: q1-report          # PaiFile resource name
      mountPath: /data/report.pdf

The file is placed at mountPath before the agent starts. Mounts are writable by default — the agent can edit the file in-place.

Version pinning

By default Pai pins the file to status.currentVersion at the time the session is created. Later uploads do not affect already-running sessions.

To pin to a specific version explicitly:

files:
  - name: q1-report
    mountPath: /data/report.pdf
    version: 1          # always use version 1, even if newer versions exist

Read-only mounts

If the agent should not modify the file, set readOnly: true:

files:
  - name: reference-doc
    mountPath: /docs/reference.pdf
    readOnly: true

Session overrides

A Session can add or override files on top of the Agent. Session entries win on name conflicts:

apiVersion: pai.io/v1
kind: Session
metadata:
  name: q2-analysis
spec:
  agentDefinition: report-analyst
  title: "Analyse the Q2 report"
  files:
    - name: q2-report           # replaces q1-report for this session only
      mountPath: /data/report.pdf

Updating a file from inside a session

Mounted files land in a writable directory. The agent can edit the file at mountPath like any ordinary local file. To publish the changes back to the platform as a new version, the agent calls the register_file tool.

register_file takes two inputs:

Input	Required	Description
path	Yes	Absolute local path to the file (the mountPath the file was mounted at, or any other path the agent wrote to)
name	No	PaiFile resource name. Defaults to a sanitised version of the filename. Use the same name as the mounted file to create a new version of it.
description	No	Optional description

Example — annotate a report and publish the result:

The agent receives the report at /data/report.pdf, adds its annotations, then registers the updated file:

I have finished annotating the report. I'll now save it and publish it.

register_file(
  path="/data/report.pdf",
  name="q1-report"
)

This creates q1-report v2 on the platform. The previous version is preserved. Any user can download it with pai download q1-report, and any future session that mounts q1-report will get v2 by default.

Example — produce a new output file:

The agent writes a summary to a new path, then registers it as a separate resource:

register_file(
  path="/workspace/summary.md",
  name="q1-summary",
  description="Executive summary of Q1 results"
)

This creates a brand-new PaiFile named q1-summary that users can download and other sessions can mount.

spec.files field reference

Field	Type	Required	Description
name	string	Yes	PaiFile resource name in the same namespace
mountPath	string	Yes	Absolute path inside the container where the file will appear
version	integer	No	Version to mount. Omit to use status.currentVersion at session creation time
readOnly	boolean	No	Default false. Set to true to prevent the agent from modifying the file

Versioning

Each upload (or register_file call) creates a new version. Versions are integer-numbered starting at 1. status.currentVersion always points to the latest.

pai get files q1-report

  q1-report  file

  Filename             report.pdf
  MIME Type            application/pdf
  Current Version      v2
  Size                 2.3 MB
  Ready                yes
  Created              2026-04-12 10:00:00
  Updated              2026-04-12 11:30:00

  V     SIZE         CREATED                CREATED BY
  ────────────────────────────────────────────────────────────
  v1    2.1 MB       2026-04-12 10:00:00    (upload)
  v2    2.3 MB       2026-04-12 11:30:00    session-q2-analysis

All versions are retained until the file is deleted. Version-specific deletion (--version N) is not yet supported — deleting a file removes all versions.