Skip to main content

​
Create Filesystem

Create a new filesystem. 
fs = client.filesystems.create(
    name="my-workspace",
    namespace_id="ns-123",
)
Parameters:
  • name (str): Filesystem name
  • namespace_id (str): Namespace UUID
Returns: Filesystem

​
Retrieve Filesystem

Get a filesystem by ID. 
fs = client.filesystems.retrieve("fs-uuid")
Parameters:
  • filesystem_id (str): Filesystem UUID
Returns: Filesystem

​
List Filesystems

List filesystems in a namespace. 
filesystems = client.filesystems.list(
    namespace_id="ns-123",
    limit=20,
)
Parameters:
  • namespace_id (str, optional): Filter by namespace
  • limit (int, optional): Max results
  • page_number (int, optional): Page number
Returns: FilesystemListResponse

​
Delete Filesystem

Delete a filesystem. 
client.filesystems.delete("fs-uuid")
Parameters:
  • filesystem_id (str): Filesystem UUID
Returns: DeleteResponse

​
File Operations

​
Get Upload URL

url_info = client.filesystems.get_upload_url(
    filesystem_id="fs-uuid",
    file_path="data/file.json",
)
# PUT to url_info.url

​
Get Download URL

url_info = client.filesystems.get_download_url(
    filesystem_id="fs-uuid",
    file_path="data/file.json",
)
# GET from url_info.url

​
Sync Operations

For agent code, use the SDK for filesystem sync:

​
Sync Down

from terminaluse import filesystem

await filesystem.sync_down(
    filesystem_id="fs-uuid"
)
# Files now in /workspace

​
Sync Up

await filesystem.sync_up(
    filesystem_id="fs-uuid"
)
# Changes uploaded

​
Filesystem Model

fs.id           # Filesystem UUID
fs.name         # Filesystem name
fs.namespace_id # Parent namespace
fs.status       # Sync status
fs.created_at   # Creation timestamp

​
Status Values

StatusDescription
READYAvailable for use
SYNCINGSync in progress
ERRORSync failed

​
Usage Example

from terminaluse import Client, filesystem

client = Client()

# Create filesystem
fs = client.filesystems.create(
    name="project-workspace",
    namespace_id="ns-123",
)

# In agent handler
@server.on_event
async def handle_event(ctx: TaskContext, event: Event):
    # Download workspace
    await filesystem.sync_down(filesystem_id=fs.id)

    # Work with files
    with open("/workspace/data.txt", "w") as f:
        f.write("Hello!")

    # Upload changes
    await filesystem.sync_up(filesystem_id=fs.id)