Using Filesystems & Agents

Overview

Once your agent is deployed, you can interact with it from any client application using the Terminal Use SDKs or CLI. This guide covers:

Creating and managing filesystems
Creating tasks with mounted filesystems
Sending messages to tasks
Receiving responses
Working with files

Client Setup

import TerminalUse from '@anthropics/terminaluse';

const client = new TerminalUse({
  apiKey: process.env.TERMINALUSE_API_KEY
});

Filesystems

Filesystems provide persistent file storage that exists independently of tasks. They allow you to share files between tasks, pre-load data for agents, and download results.

Projects

Projects are permission boundaries over filesystems. When you create a filesystem, you associate it with a project. All filesystems in a project share the same access permissions.

Creating Filesystems

// Create a project first (if required)
const project = await client.projects.create({
  namespace_id: 'ns_123',
  name: 'my-project'
});

// Create filesystem in the project
const filesystem = await client.workspaces.create({
  namespace_id: 'ns_123',
  project_id: project.id,
  name: 'my-workspace'
});

console.log(filesystem.id); // Use this ID when creating tasks

Adding Files to Filesystems

Files are uploaded as tar.zst archives (tar compressed with Zstandard). The CLI handles this automatically, but for SDK usage you’ll need to create the archive first.

import { execSync } from 'child_process';
import { readFileSync, unlinkSync } from 'fs';

// Create tar.zst archive from directory
execSync('tar -cf - -C ./my-project . | zstd -o archive.tar.zst');
const archiveBuffer = readFileSync('archive.tar.zst');
unlinkSync('archive.tar.zst'); // Clean up

// Get upload URL
const { url } = await client.workspaces.getUploadURL(filesystemId);

// Upload archive to presigned URL
await fetch(url, {
  method: 'PUT',
  body: archiveBuffer,
  headers: { 'Content-Type': 'application/zstd' }
});

Viewing and Downloading Files

// List files in filesystem
const { files } = await client.workspaces.listFiles(filesystemId, {
  recursive: true,
  include_content: false
});

// Get a specific file
const file = await client.workspaces.getFile('path/to/file.txt', {
  workspace_id: filesystemId,
  include_content: true
});

// Get download URL for the archive
const { url } = await client.workspaces.getDownloadURL(filesystemId);

Tasks

Tasks are execution contexts for agents. Each task represents a conversation or unit of work.

Creating Tasks

Mount a filesystem when creating a task to give the agent access to files.

const response = await client.agents.rpcByName('my-namespace/my-agent', {
  namespace_id: 'ns_123',
  method: 'task/create',
  params: {
    name: 'my-task',
    workspace_id: filesystemId,  // Mount filesystem
    params: {
      // Custom parameters for your agent
      model: 'claude-sonnet-4-20250514'
    }
  }
});

const task = response.result;
console.log(task.id);

Listing Tasks

const tasks = await client.tasks.list({
  agent_name: 'my-namespace/my-agent',
  limit: 10
});

Sending Events

Send messages or events to running tasks.

const response = await client.agents.rpcByName('my-namespace/my-agent', {
  namespace_id: 'ns_123',
  method: 'event/send',
  params: {
    task_id: taskId,
    content: {
      type: 'text',
      text: 'Analyze the uploaded files',
      author: 'user'
    }
  }
});

Receiving Messages

Stream or retrieve messages from tasks.

// Stream events from a task
const stream = await client.tasks.streamEvents(taskId);

// Or list messages
const messages = await client.messages.list({
  task_id: taskId
});

Complete Example

Here’s a complete workflow: create a filesystem, upload files, create a task, send a message, and download results.

import TerminalUse from '@anthropics/terminaluse';

const client = new TerminalUse();

async function runAgent() {
  // 1. Create filesystem
  const filesystem = await client.workspaces.create({
    namespace_id: 'ns_123',
    project_id: 'proj_456',
    name: 'analysis-workspace'
  });

  // 2. Upload files (using CLI or presigned URL)
  // tu filesystems push <filesystem.id> ./data

  // 3. Create task with mounted filesystem
  const taskResponse = await client.agents.rpcByName('my-namespace/my-agent', {
    namespace_id: 'ns_123',
    method: 'task/create',
    params: {
      workspace_id: filesystem.id,
      params: { task_type: 'analysis' }
    }
  });
  const task = taskResponse.result;

  // 4. Send message to start work
  await client.agents.rpcByName('my-namespace/my-agent', {
    namespace_id: 'ns_123',
    method: 'event/send',
    params: {
      task_id: task.id,
      content: {
        type: 'text',
        text: 'Analyze all CSV files and create a summary report',
        author: 'user'
      }
    }
  });

  // 5. Stream responses
  const stream = await client.tasks.streamEvents(task.id);
  // Handle streamed messages...

  // 6. Download results
  const { url } = await client.workspaces.getDownloadURL(filesystem.id);
  // Download from presigned URL...
}

CLI Commands

`tu tasks create`

tu tasks create [OPTIONS]

Option	Short	Description
`--filesystem-id`	`-f`	Filesystem ID to attach
`--project-id`	`-p`	Project ID for auto-creating filesystem
`--message`	`-m`	Text message to send
`--params`		JSON string with task params
`--name`	`-n`	Optional task name

`tu tasks send`

tu tasks send <TASK_ID> [OPTIONS]

Option	Short	Description
`--message`	`-m`	Text message to send
`--event`	`-e`	Raw JSON event to send

`tu tasks ls`

tu tasks ls [TASK_ID] [OPTIONS]

Option	Short	Description
`--agent`	`-a`	Filter by agent name
`--status`	`-s`	Filter by status (RUNNING, COMPLETED, FAILED)
`--json`	`-j`	Output as JSON

Without a task ID, lists all tasks. With a task ID, shows task details.

`tu filesystems create`

tu filesystems create [OPTIONS]

Option	Short	Description
`--project-id`	`-p`	Project ID (required)
`--name`	`-n`	Optional filesystem name
`--dir`	`-d`	Local directory to push after creation

`tu filesystems push`

tu filesystems push <FILESYSTEM_ID> <LOCAL_PATH>

Upload a local directory to the filesystem as a tar.zst archive.

`tu filesystems pull`

tu filesystems pull <FILESYSTEM_ID> <LOCAL_PATH> [OPTIONS]

Option	Short	Description
`--force`	`-f`	Clear existing directory before extracting

Download filesystem contents to a local directory.

`tu projects create`

tu projects create [OPTIONS]

Option	Short	Description
`--namespace`		Namespace slug (required)
`--name`	`-n`	Project name (required)
`--description`	`-d`	Project description

Build with Terminal Use

​Overview

​Client Setup

​Filesystems

​Projects

​Creating Filesystems

​Adding Files to Filesystems

​Viewing and Downloading Files

​Tasks

​Creating Tasks

​Listing Tasks

​Sending Events

​Receiving Messages

​Complete Example

​CLI Commands

​tu tasks create

​tu tasks send

​tu tasks ls

​tu filesystems create

​tu filesystems push

​tu filesystems pull

​tu projects create