Session Files

The Files API lets you attach files — code repositories, configuration, reference docs — to a Session for the Agent to read during task execution. The console exposes the same workspace in the Files tab. Files are available at their workspace paths as soon as they are uploaded; there is no separate File resource or mount step.

Workflow

1. Open a Session Start a Session with the Agent that will use the files.
2. Upload file Open Files, select a directory, then upload or drag in one or more files.
3. Agent uses it The Agent reads the file's contents during the Session and completes the task.

Upload a File

POST /api/v1/sessions/{session_id}/files/upload
Content-Type: multipart/form-data

Parameters

Field	Type	Required	Description
files	binary[]	Yes	One or more files
path	string	No	Destination directory; the Session root by default

File Operations

Action	Meaning
Upload	Add one or more files to the selected folder
New folder	Create a directory in the workspace
Rename	Rename or move a file or directory
Delete	Delete a file or directory
Download	Download a regular file

A regular file up to 64 MiB can be downloaded. Directories are managed in place rather than downloaded as archives.

curl Upload Example

curl -X POST \
  "$SERVICE_URL/api/v1/sessions/$SESSION_ID/files/upload" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F "files=@./src/main.py"

Response:

{
  "code": "OK",
  "message": "success",
  "data": {
    "root_path": "/workspace",
    "current_path": "/workspace",
    "parent_path": null,
    "entries": [
      {
        "path": "/workspace/main.py",
        "name": "main.py",
        "kind": "file"
      }
    ],
    "uploaded_count": 1
  }
}

Uploading multiple files:

curl -X POST \
  "$SERVICE_URL/api/v1/sessions/$SESSION_ID/files/upload" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F "files=@./config.yaml" \
  -F "files=@./requirements.txt"

Use Files in a Session

The upload endpoint is scoped to a Session, so each uploaded file is already in that Session's workspace. The standard AstraBox Agent images expose the workspace as /workspace, and the Files tab always shows the effective root and current directory.

Prompt Example

After uploading app.py, send the task in the same Session:

Review /workspace/app.py and fix the bugs. Save the corrected file in place
and write a summary to /workspace/review.md.

The Agent can open app.py immediately and any files it creates appear in the same workspace.

Download a File

Open the file's action menu in Files and select Download, or call:

curl --get \
  "$SERVICE_URL/api/v1/sessions/$SESSION_ID/files/download" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode "path=/workspace/review.md" \
  -o review.md

Any regular file in the workspace can be downloaded when it is no larger than 64 MiB.

Inspect File Metadata

The Files tab shows the current path, directory tree, file names, file types, and sizes. These values come from the live Session workspace, so Agent changes appear at the same paths.

List Files

Expand folders in Files to browse the workspace. The open directories refresh after a turn completes; select Refresh to reload them at any time.

The corresponding API operation lists one directory at a time:

POST /api/v1/sessions/{session_id}/files/list
Content-Type: application/json

curl -X POST \
  "$SERVICE_URL/api/v1/sessions/$SESSION_ID/files/list" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path": "/workspace"}'

End-to-End Example

1. Open an Agent and start a Session.
2. Open Files, select the workspace root, and upload app.py.
3. Ask the Agent to review app.py, fix the bugs, and save a report as review.md.
4. When the task completes, open review.md in Files and select Download.

FAQ

Q: How long are uploaded files retained?

A: Files belong to the Session workspace. Because AstraBox is self-hosted, the deployment controls its workspace and sandbox retention. Download important results or commit and push repository changes when they need an independent copy.

Q: Can I attach files when creating a Session?

A: Start the Session, wait for its runtime to be ready, then upload the files. They are written directly into the workspace, with no later mount operation.

Q: Which files can I download?

A: Any regular file in the Session workspace can be downloaded when it is no larger than 64 MiB, whether it was uploaded by a user or produced by the Agent.

Q: Which file formats are supported?

A: Any binary file is accepted. Text-based files (code, configuration, documents) yield the best results.