TransferKit

TransferKit is the cross-device file transfer service in AgentOS.
It allows third-party apps to securely transfer files between AgentOS devices on the local network.

What it solves

TransferKit handles:

• Sending files to a target device
• Real-time transfer progress tracking
• Receiving files from other devices
• Managing receive policies (auto-accept / require confirmation)
• Transfer history management

Best fit

• You want to implement cross-device file sharing
• You want to let users transfer files between their devices
• You are building multi-device collaboration workflows
• Your app needs to sync file data between devices

Core capabilities

Send files

• SDK (TypeScript): sdk.transferkit.send(bearerToken, { targetDeviceId, files, targetBundleId })
• SDK (Python): await sdk.transferkit.send(bearer_token, {"targetDeviceId": "...", "files": [...]})
• HTTP: POST /transferkit/send

Request body:

Field	Type	Description
targetDeviceId	string	Target device ID (from DiscoveryKit)
targetBundleId	string?	Target app bundleId on the device
files	array	File list
files[].fileName	string	File name
files[].filePath	string	File path
files[].size	int	File size in bytes
files[].mimeType	string?	MIME type

Returns a TransferSession with transferId and initial state.

Track transfer progress

Real-time SSE stream:

• SDK: sdk.transferkit.streamProgress(bearerToken, transferId)
• HTTP: GET /transferkit/transfers/<transferId>/stream

Or poll the status:

• SDK: sdk.transferkit.getStatus(bearerToken, transferId)
• HTTP: GET /transferkit/transfers/<transferId>/status

Transfer states:

State	Description
preparing	Preparing the transfer
transferring	Transfer in progress
completed	Transfer completed
failed	Transfer failed
cancelled	Transfer cancelled

Cancel a transfer

• SDK: sdk.transferkit.cancel(bearerToken, transferId)
• HTTP: POST /transferkit/transfers/<transferId>/cancel

Receive files

Monitor incoming file events via SSE:

• SDK: sdk.transferkit.receiveStream(bearerToken)
• HTTP: GET /transferkit/receive/stream

When the receive policy is requireConfirm, respond manually:

• SDK: sdk.transferkit.respond(bearerToken, transferId, { accept: true })
• HTTP: POST /transferkit/transfers/<transferId>/respond

Receive policy management

Set receive policy:

• SDK: sdk.transferkit.setPolicy(bearerToken, { policy: 'autoAccept' })
• HTTP: PUT /transferkit/receive/policy

Get current policy:

• SDK: sdk.transferkit.getPolicy(bearerToken)
• HTTP: GET /transferkit/receive/policy

Policy	Description
autoAccept	Automatically accept all files
requireConfirm	Require manual confirmation before each receive

Transfer history

• Query records: GET /transferkit/history?deviceId=...&userId=...
• Delete one: DELETE /transferkit/history/<recordId>
• Clear all: DELETE /transferkit/history

Security

• Path validation: ensures files stay within the app sandbox, preventing path traversal
• Permission isolation: each app can only view and manage its own transfers
• Bearer token auth: all operations require a valid AppKit token

Relationship with DiscoveryKit

TransferKit depends on DiscoveryKit for target device info:

• targetDeviceId comes from DiscoveryKit's getPeers result
• Before sending, ensure the target device is online and registered

Relationship with AuthKit

TransferKit uses AuthKit's userId to identify the sender:

• Transfer history is scoped by deviceId:userId
• The receiver can see the sender's identity info

When you may not need TransferKit

• You do not need device-to-device file transfer
• Your files are relayed through cloud servers
• Your app does not run in a local network environment

Next steps

• To discover devices before sending: see DiscoveryKit
• To obtain user identity first: see AuthKit
• To register your app: see AppKit