Skip to main content

AzureBlobFilesystem

Stores files in Azure Blob Storage containers.

info

For interface details, see WorkspaceFilesystem Interface.

Installation
Direct link to Installation

npm install @mastra/azure

Usage
Direct link to Usage

Add an AzureBlobFilesystem to a workspace and assign it to an agent:

import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { AzureBlobFilesystem } from '@mastra/azure/blob'

const workspace = new Workspace({
  filesystem: new AzureBlobFilesystem({
    container: 'my-container',
    connectionString: process.env.AZURE_STORAGE_CONNECTION_STRING,
  }),
})

const agent = new Agent({
  name: 'file-agent',
  model: 'anthropic/claude-opus-4-6',
  workspace,
})

Account key
Direct link to Account key

Use an account name and account key when you do not want to pass a full connection string:

import { AzureBlobFilesystem } from '@mastra/azure/blob'

const filesystem = new AzureBlobFilesystem({
  container: 'my-container',
  accountName: process.env.AZURE_STORAGE_ACCOUNT_NAME,
  accountKey: process.env.AZURE_STORAGE_ACCOUNT_KEY,
})

Shared access signature token
Direct link to Shared access signature token

Use a shared access signature (SAS) token with either accountName or endpoint:

import { AzureBlobFilesystem } from '@mastra/azure/blob'

const filesystem = new AzureBlobFilesystem({
  container: 'my-container',
  accountName: process.env.AZURE_STORAGE_ACCOUNT_NAME,
  sasToken: process.env.AZURE_STORAGE_SAS_TOKEN,
})

DefaultAzureCredential
Direct link to DefaultAzureCredential

Use DefaultAzureCredential when your environment provides Azure identity credentials:

import { AzureBlobFilesystem } from '@mastra/azure/blob'

const filesystem = new AzureBlobFilesystem({
  container: 'my-container',
  accountName: process.env.AZURE_STORAGE_ACCOUNT_NAME,
  useDefaultCredential: true,
})

Install @azure/identity when you use DefaultAzureCredential:

npm install @azure/identity

Constructor parameters
Direct link to Constructor parameters

container:

string
Azure Blob Storage container name

connectionString?:

string
Full Azure Storage connection string. Takes priority over other authentication options.

accountName?:

string
Azure Storage account name. Required unless you use connectionString or endpoint.

accountKey?:

string
Azure Storage account key.

sasToken?:

string
Shared access signature token. Requires accountName or endpoint.

useDefaultCredential?:

boolean
= false
Use DefaultAzureCredential from @azure/identity.

endpoint?:

string
Custom Blob service endpoint URL. Used for local development with Azurite.

prefix?:

string
Optional prefix for all keys (acts like a subdirectory).

id?:

string
= Auto-generated
Unique identifier for this filesystem instance.

displayName?:

string
Human-friendly display name for the UI.

icon?:

FilesystemIcon
Icon identifier for the UI.

description?:

string
Short description of this filesystem for the UI.

readOnly?:

boolean
= false
When true, all write operations are blocked.

Properties
Direct link to Properties

id:

string
Filesystem instance identifier.

name:

string
Provider name ('AzureBlobFilesystem').

provider:

string
Provider identifier ('azure-blob').

readOnly:

boolean | undefined
Whether the filesystem is in read-only mode.

Methods
Direct link to Methods

AzureBlobFilesystem implements the WorkspaceFilesystem interface, providing all standard filesystem methods:

  • readFile(path, options?) - Read file contents
  • writeFile(path, content, options?) - Write content to a file
  • appendFile(path, content) - Append content to a file
  • deleteFile(path, options?) - Delete a file
  • copyFile(src, dest, options?) - Copy a file
  • moveFile(src, dest, options?) - Move or rename a file
  • mkdir(path, options?) - Create a directory
  • rmdir(path, options?) - Remove a directory
  • readdir(path, options?) - List directory contents
  • exists(path) - Check if a path exists
  • stat(path) - Get file or directory metadata

init()
Direct link to init

Initialize the filesystem. Verifies container access and credentials.

await filesystem.init()

getInfo()
Direct link to getinfo

Returns metadata about this filesystem instance.

const info = filesystem.getInfo()
// { id: '...', name: 'AzureBlobFilesystem', provider: 'azure-blob', status: 'ready' }

getContainer()
Direct link to getcontainer

Returns the underlying Azure Blob Storage ContainerClient.

const container = await filesystem.getContainer()

getMountConfig()
Direct link to getmountconfig

Returns the mount configuration for sandbox providers that support Azure Blob filesystem mounts.

const config = filesystem.getMountConfig()
// { type: 'azure-blob', container: 'my-container', ... }
note

Azure Blob sandbox mounting depends on sandbox support for azure-blob mount configs. Use filesystem for direct workspace file operations when your sandbox provider does not support Azure Blob mounts.

On this page