Files and agent state

AgentRun stores definitions, run history, workspaces, and learning separately. Use the API for the files an application needs; preserve the whole data directory when backing up the server.

Know which state you are reading

State	Scope	Access
Agent definition and revisions	One agent	Console or /v2/agents/{id} and /revisions.
Run workspace and outputs	One run	/v2/runs/{id}/files and /files/{path}.
Uploaded inputs	Server, then copied into selected runs	/v2/files; attach IDs when starting a run.
Accepted learning	One agent, pinned at each run's start	/v2/agents/{id}/learning.
Agent home files	Persistent files addressed by agent	/v2/agents/{id}/home/files.

The current home-files API does not automatically mount arbitrary home files into every run. Use explicit uploaded inputs or the learning API for the corresponding purpose. learning/ and sign-ins/ are server-owned namespaces, not general file storage.

Give a run an input file

With the API environment from Use the API, upload a local file:

curl --fail-with-body --silent --show-error \
  "$AGENTRUN_BASE_URL/files?path=notes.md" \
  -H "Authorization: Bearer $AGENTRUN_API_KEY" \
  --data-binary @notes.md

Take file.file_id from the response and include it in the run request:

{
  "input": { "content": "Summarize inputs/notes.md." },
  "file_ids": ["FILE_ID"]
}

Grant the agent a suitable file-reading tool. AgentRun copies the upload into the run's workspace under inputs/ and tells the harness where to find it. Deleting the original upload does not remove copies already attached to runs.

Read the results

List GET /v2/runs/{id}/files, then request GET /v2/runs/{id}/files/{path} for a file's content. The console exposes the same files on the run page.

File access is scoped to the workspace. Paths outside it and unsupported links are refused. Inspect the running server's capability limits before submitting large files.

Preserve the underlying data

The launcher defaults to ~/.agentrun; --data DIR changes it. Current repository source puts the control-plane database at DIR/store.sqlite and run workspaces and stores under DIR/disk/agents/. Earlier published servers use a different layout.

Do not manipulate database files to transfer an agent. Use Back up and move your server, and keep version-specific layouts with the server version that wrote them.

See the source reference for Uploads and Agent home, including limits and platform-specific write support.