Files and Git-backed source

Checkfu does not use FileTree as the universal container for everything an Agent can read or change. Use the resource that owns the lifecycle you need:

Resource	Use it for	Authority boundary
File	One user-provided upload or artifact	File identity, content digest, retention, and Session attachment
Git-backed source	A repository tree resolved to an immutable commit	Repository identity plus a governed Connection for provider effects
Skill / SkillVersion	Reusable authored capability	Human-reviewed versioning and AgentVersion selection
MemoryStore / MemoryVersion	Retained knowledge across Sessions	Permissioned writes, proposals, curation, retention, and erasure

The currently served API still exposes /v1/file-trees for multi-file uploads and Git repository workflows. Treat that as the exact compatibility contract for those workflows, not as the final meaning of File, Skill, Memory, or every other resource.

Plain HTTP against the Checkfu API needs no private package. The Checkfu CLI and TypeScript SDK are optional private-alpha artifacts; the HTTP requests work without them. The documented path is usable as written for an admitted Workspace. Confirm capability status before making availability part of your application’s contract.

Files

A File is a first-class Workspace resource. Upload it once, attach its ID to a Session, and let Session admission freeze the exact object the run may read. The Files API is intentionally small:

POST /v1/files uploads exactly one multipart file with an Idempotency-Key;
GET /v1/files/{id} reads its credential-free metadata; and
DELETE /v1/files/{id} removes it under the File lifecycle contract.

The upload limit is 64 MiB. A File is not a Credential store, a mutable folder, a MemoryStore, or a Skill. The upload part’s Content-Type becomes the File’s mime_type, and image and document message content accept only a matching type. Browsers type the part from the file name, and so does the CLI (checkfu operation invoke files.createFile --input <path>); with the SDK or a raw request, set the type on the part you send. MCP doesn’t project uploads, so upload through another client and pass the File ID. A Session that references a File records the selected File identity and content digest. Replacing a local file later does not change an admitted Session.

Captured outputs and reuse

Files published through a supported Session output-capture path are scoped to that Session and marked downloadable: true. Use GET /v1/files/{id}/content under current authority to download their exact bytes. A user upload is marked downloadable: false; attaching it as input does not turn it into a captured output. A captured File ID remains scoped to its producing Session. A native Session cannot read another Session’s scoped File ID. To reuse the bytes where downloads are supported and you are authorized to copy them, download the File and upload those exact bytes through POST /v1/files. This creates a new File ID; compare its content digest with the downloaded source before attaching it to the new Session. The new upload and Session selection need their own current authority. An earlier mount or download grants no continued access. Native Workspace execution currently has no path that publishes its generated artifacts as downloadable Session Files. Its retained Tool results and private working files do not prove capture, downloads, or later reuse. Check the selected Harness’s capability status for the supported output path. Private Workspace state and native private memory are not automatically promoted into shared resources.

A customer-provided File can contain a secret if the customer uploads one. Do not put API keys, passwords, OAuth grants, session cookies, or provider tokens into Files merely because Checkfu never injects a custodied Connection Credential into a File.

Uploaded folders

An uploaded FileTree is a nested folder published directly to Checkfu. A developer with an API key can attach one to a native Session and the Agent can list and read it. No acting Principal is involved: the Session keeps its real API key, Workspace, and scopes.

Upload the folder with POST /v1/file-trees and source.kind: "upload". Paths can be nested.
Create the Session without acted_as.
Attach the tree with POST /v1/sessions/{id}/resource-bindings using kind: "file_tree" and access: "read_only".
Send a message. The Agent’s list_directory and read tools see the mount.

Upload the folder:

curl --request POST https://api.checkfu.com/v1/file-trees \
  --header "Authorization: Bearer $CHECKFU_API_KEY" \
  --header "Checkfu-Version: 2026-08-31" \
  --header "Idempotency-Key: docs-folder" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "docs-folder",
    "source": { "kind": "upload" },
    "files": [
      { "path": "guides/setup/notes.txt", "content_base64": "aGVsbG8=" },
      { "path": "readme.txt", "content_base64": "aGk=" }
    ]
  }'

const fileTree = await checkfu.fileTrees.create(
  {
    name: "docs-folder",
    source: { kind: "upload" },
    files: [
      { path: "guides/setup/notes.txt", content_base64: "aGVsbG8=" },
      { path: "readme.txt", content_base64: "aGk=" },
    ],
  },
  { idempotencyKey: "docs-folder" },
)

Attach it to a Session, pinned to version 1:

curl --request POST https://api.checkfu.com/v1/sessions/sess_0123456789abcdef0123456789abcdef/resource-bindings \
  --header "Authorization: Bearer $CHECKFU_API_KEY" \
  --header "Checkfu-Version: 2026-08-31" \
  --header "Idempotency-Key: docs-folder-attach" \
  --header "Content-Type: application/json" \
  --data '{
    "kind": "file_tree",
    "file_tree_id": "ftree_0123456789abcdef0123456789abcdef",
    "mount_path": "/mnt/session/folder",
    "access": "read_only",
    "version_policy": { "kind": "pinned", "version": 1 }
  }'

await checkfu.sessions.resourceBindings.attach(
  session.id,
  {
    kind: "file_tree",
    file_tree_id: fileTree.id,
    mount_path: "/mnt/session/folder",
    access: "read_only",
    version_policy: { kind: "pinned", version: 1 },
  },
  { idempotencyKey: "docs-folder-attach" },
)

What the Agent receives is fixed when the message is admitted:

latest resolves once for that message and the exact version is recorded. A version published later does not change what that message reads, including after recovery. Use pinned to select a version yourself.
Uploaded trees are read-only here. A writable mount, a Git tree, or a mount that combines an uploaded tree with Memory or Skills in an API-key Session without acted_as is not supported by this path and gains no authority from it.
You can mix individual Files and uploaded trees in one Session.

Every listing and read rechecks live authority before anything is released: the API key must still be valid for this Workspace, and the tree version must still exist and be within retention. If the key is revoked, the tree is erased, or its content expires while a read is in flight, the Agent gets a normal error and no file names or bytes. Uploaded input is never downloadable, and attaching a tree does not grant the Agent any Tool, credential, or network access.

Git-backed source

Use Git-backed source when the Agent needs a repository tree rather than one uploaded object. The source resolves a branch or ref to an exact commit and immutable tree before execution. Provider access goes through a governed Connection. The acting Principal must hold the required PermissionAssignment, and Checkfu rechecks live Connection authority before provider reads or writes. Checkfu does not inject or return the Git Connection’s custodied Credential value through the Session, sandbox, commit message, pull-request body, or event log. Repository bytes remain customer content. A committed secret can still reach the Agent because it is part of the selected tree; review and scan repositories independently of Connection credential custody.

Current FileTree compatibility operations

The current /v1/file-trees contract serves two narrow source kinds:

`source.kind`	Meaning
`upload`	A bounded multi-file tree published directly to Checkfu
`git`	A repository resolved through a Connection to an immutable commit

Each publication or refresh creates an immutable FileTree version. latest, a pinned version, or an already-published Git ref can select which version a Run receives. The resolved version is recorded with the Run. Create a Git-backed FileTree with the Principal that owns and may use the Connection:

curl --request POST https://api.checkfu.com/v1/file-trees \
  --header "Authorization: Bearer $CHECKFU_API_KEY" \
  --header "Checkfu-Version: 2026-08-31" \
  --header "Idempotency-Key: project-support-site" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "support-site",
    "acted_as": "prin_0123456789abcdef0123456789abcdef",
    "source": {
      "kind": "git",
      "provider": "github",
      "repository": "acme/support-site",
      "connection_id": "conn_0123456789abcdef0123456789abcdef",
      "ref": "main"
    }
  }'

const fileTree = await checkfu.fileTrees.create(
  {
    name: "support-site",
    acted_as: principalId,
    source: {
      kind: "git",
      provider: "github",
      repository: "acme/support-site",
      connection_id: connectionId,
      ref: "main",
    },
  },
  { idempotencyKey: "project-support-site" },
)

A provider name in this example does not claim universal hosted support. The exact Connection, package, placement, scopes, and provider operation must be qualified and available.

Runtime overlays

A repository or multi-file tree can be mounted read_only or read_write. A writable mount gives the sandbox a disposable overlay. It does not mutate the source resource in place. These overlay and writeback behaviors belong to the FileTree compatibility path. The native Session reader currently supports uploaded trees, not Git checkout mounts. Preparing recorded Git metadata does not enable native repository reads, writable overlays, or Git writeback. A native Session started with an API key and no acted_as can read an uploaded tree. See Uploaded folders. Git checkout mounts still need the acting Principal that holds the Connection; an API key alone never supplies one. Supplying acted_as still requires current delegation and resource permissions; it is not a substitute for them. Publishing work back to Git is a separate external effect. The current FileTree compatibility contract can push a new non-force branch and open a pull request through the same live Connection. Those mutations need stable idempotency keys, exact base versions, policy evaluation, and provider-side reconciliation. The human merge remains outside the Session. A Session-owned pull-request writeback policy may capture a bounded overlay at settlement under standard retention. Omission keeps the overlay disposable. Uploaded trees and zero-data-retention placements can reject writeback where retained content is required. A lost response after push or pull-request creation is not proof that the provider rejected the request. Reconcile the retained provider receipt or provider state before retrying; never turn uncertainty into a blind second Git effect.

Repository Skills

A frozen Git tree may contain repository-local Skill instructions at an admitted path. Those files remain repository content. They do not create a Skill resource or SkillVersion automatically. The native recorded-Git preparation does not discover or load repository-local Skills automatically. Select reusable Skills through their own versioned resource contract. Mounting a repository is therefore also an instruction-trust decision. Review contributions before letting an Agent read repository-local instructions. Use a real Skill when you need an independently versioned, reusable capability.

Choosing the resource

Use a File for a document the user supplied. Use Git-backed source for a repository and explicit Git effects. Use a Skill for reusable authored capability. Use Memory for retained knowledge. Keeping these separate lets Session admission freeze the right selection policy and each Run record the exact version it receives. It also lets revocation target the correct authority and lets retention or erasure operate without inventing one mutable aggregate that owns everything.

Capabilities, Tools, and Skills

See how SkillVersion differs from repository content.

Memory

Retain knowledge under a different version and erasure boundary.

Get started

Agents

Sessions

Environments

Tools

Context

Automations

Permissions

Security

Billing

Deployment

Files and Git-backed source

Files

Captured outputs and reuse

Uploaded folders

Git-backed source

Current FileTree compatibility operations

Runtime overlays

Repository Skills

Choosing the resource

Capabilities, Tools, and Skills

Memory

​Files

​Captured outputs and reuse

​Uploaded folders

​Git-backed source

​Current FileTree compatibility operations

​Runtime overlays

​Repository Skills

​Choosing the resource

Capabilities, Tools, and Skills

Memory

Files

Captured outputs and reuse

Uploaded folders

Git-backed source

Current FileTree compatibility operations

Runtime overlays

Repository Skills

Choosing the resource