Jettson Files

Read, write, list, and delete files inside the agent's /workspace.

Every agent owns a /workspace on its computer — files it reads and writes during the run. Anything outside /workspace is rejected. The workspace is destroyed when the agent terminates; cross-run persistence lives in Memory.

jettson_files_read

| Field | Type | Description | | --- | --- | --- | | path (required) | string | Path relative to /workspace. Traversal (../) is refused. |

Returns:

json
{
  "path": "data.csv",
  "content": "id,name,email\n1,Tay,tay@acme.io\n...",
  "size_bytes": 482,
  "truncated": false
}

truncated: true means the file was over 1 MB. The first 1 MB is returned; further bytes need shell-side processing (head, tail, etc.).

jettson_files_write

| Field | Type | Description | | --- | --- | --- | | path (required) | string | Path relative to /workspace. Parent directories are created. | | content (required) | string | UTF-8 content to write. Up to 5 MB. |

json
{ "path": "scratch/notes.md", "bytes_written": 421 }

Writes are atomic at the filesystem level. Overwrites existing files.

jettson_files_list

| Field | Type | Description | | --- | --- | --- | | path | string | Directory relative to /workspace (default .). |

json
{
  "path": ".",
  "entries": [
    { "name": "data.csv", "size_bytes": 482, "is_dir": false },
    { "name": "scratch", "size_bytes": 0, "is_dir": true }
  ]
}

jettson_files_delete

| Field | Type | Description | | --- | --- | --- | | path (required) | string | File path relative to /workspace. Directories refused — use jettson_shell_run with rmdir for those. |

json
{ "path": "old.csv", "deleted": true }

Path safety

Every path is resolved against /workspace and checked to stay inside. Inputs that would escape — ../etc/passwd, /, /tmp/foo — are refused with:

json
{ "error": "Jettson Files rejected the operation: path escapes /workspace or is empty." }

This is enforced server-side; there's no way for the agent to bypass it from inside the container.

When to use Files vs Shell

  • Files: structured read/write of plain-text data. Returns the content directly to the Mind so it can reason over it.
  • Shell: when you need a Linux command's behavior — grep, head, wc, etc. — or when you're piping multi-step processing.

Common pattern: shell to fetch + process, files to read the final artifact back into the Mind's context.

text
jettson_shell_run({ command: "curl ... > big.json && jq '.items[:10]' big.json > top.json" })
jettson_files_read({ path: "top.json" })

Failure modes

| Situation | Returns | | --- | --- | | Path escapes /workspace | error: "Jettson Files rejected the operation: …" | | File doesn't exist (_read, _delete) | error: "Jettson Files rejected the operation: no such file: …" | | Tried to delete a directory | error: "Jettson Files rejected the operation: <path> is a directory — use Jettson Shell with rmdir for that." | | Read of a >1 MB file | Returns first 1 MB with truncated: true |

Related