Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.blaxel.ai/llms.txt

Use this file to discover all available pages before exploring further.

Mastra is an open source TypeScript framework for building agentic applications. It includes built-in support for Blaxel sandboxes, making it possible to create agents that are backed by remote execution environments (sandboxes) in the cloud. This tutorial explores how you can use Mastra with Blaxel.

​
Prerequisites

The Mastra framework is provider-agnostic and can be used with multiple LLM providers. This tutorial uses Anthropic models, but you can also read about using other models.

​
1. Install required dependencies

In your Mastra project directory, initialize a new project and add the Mastra and Blaxel packages, tsx to run the TypeScript examples, and Node.js types: 
npm init -y
npm install -D typescript @types/node mastra@latest
npm install @mastra/core@latest zod @mastra/blaxel tsx
npm pkg set type=module
npx tsc --init \
  --target ES2022 \
  --module ES2022 \
  --moduleResolution bundler \
  --esModuleInterop \
  --strict \
  --skipLibCheck
More information on Mastra installation is available in the Mastra documentation.

​
2. Configure the environment

Add your LLM API key, Blaxel API key, Blaxel workspace name and Blaxel deployment region as environment variables: 
export ANTHROPIC_API_KEY=your_key_here
export BL_API_KEY=your_key_here
export BL_WORKSPACE=your_workspace_name_here
export BL_REGION=us-pdx-1

​
3. Build a simple agent

In your project directory, create a file named index.ts with the following code.
TypeScript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { BlaxelSandbox } from '@mastra/blaxel'

async function main() {
  const sandboxId = `mastra-blaxel-simple-${Date.now()}`

  // create sandbox
  const workspace = new Workspace({
    sandbox: new BlaxelSandbox({
      id: sandboxId,
      image: 'blaxel/base-image',
      memory: 4096,
    }),
  })

  try {
    // create agent
    const agent = new Agent({
      id: 'agent',
      name: 'Agent',
      instructions: 'You have access to a sandbox environment. You can execute commands, manage files, and inspect processes inside the sandbox.',
      model: 'anthropic/claude-sonnet-4-6',
      workspace,
    })

    // give the agent a task
    const result = await agent.generate(
      'Install a complete Go development environment. Once done, return the installed Go version number and Go environment variables.',
      { maxSteps: 50 }
    )

    console.log(result.text)
  } finally {
    // delete the sandbox once complete
    await workspace.sandbox?.destroy()
  }
}

main().catch((error) => {
  console.error(error)
  process.exit(1)
})
This creates a simple sandbox-backed agent on Blaxel with the Mastra framework. Instructions that you send the agent will be executed in a uniquely named sandbox that is dynamically created and managed in your workspace on Blaxel’s infrastructure. Run the agent: 
npx tsx index.ts
It will create and deploy a Blaxel sandbox using the blaxel/base-image image, then investigate the sandbox and install all the tools required for Go development. Once done, it will return a report of its work and automatically delete the sandbox. Here’s a partial example of the output: 
Go is installed and ready.

- Installed version: `go1.25.9`
- Command check: `go version` → `go version go1.25.9 linux/amd64`

**Go Env**
- `AR='ar'`
- `CC='cc'`
- `CGO_CFLAGS='-O2 -g'`
- `CGO_CPPFLAGS=''`
- `CGO_CXXFLAGS='-O2 -g'`
- `CGO_ENABLED='1'`
- `CGO_FFLAGS='-O2 -g'`
...

​
4. Build a streaming coding agent

One of the most popular uses for agents is to generate code. Sandboxes provide isolated execution environments, allowing agents to securely run generated code with no risk of escaping. Update index.ts to build a simple coding agent that accepts tasks from the command line and streams its responses as it works:
TypeScript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { BlaxelSandbox } from '@mastra/blaxel'

// read task from command line
const task = process.argv[2]

if (!task) {
  console.error('Usage: npx tsx index.ts "<task>"')
  process.exit(1)
}

async function main() {
  const sandboxId = `mastra-blaxel-coding-${Date.now()}`

  // create sandbox
  const workspace = new Workspace({
    sandbox: new BlaxelSandbox({
      id: sandboxId,
      image: 'blaxel/py-app',
      memory: 4096,
    }),
  })

  try {
    // create agent
    const agent = new Agent({
      id: 'coding-agent',
      name: 'Coding agent',
      instructions: `You are an expert software engineer with access to a sandbox environment. You can write, run, and debug code in any language. Use the sandbox to execute code, install dependencies, and verify your solutions work correctly before responding. Install whichever packages you need for your task.`,
      model: 'anthropic/claude-sonnet-4-6',
      workspace,
    })

    // set task for agent
    // stream agent output
    const stream = await agent.stream(task, { maxSteps: 50 })

    process.stdout.write('agent > ')
    for await (const chunk of stream.textStream) {
      process.stdout.write(chunk)
    }
    process.stdout.write('\n' + '--'.repeat(20) + '\n')
  } finally {
    // delete sandbox when complete
    await workspace.sandbox?.destroy()
  }
}

main().catch((error) => {
  console.error(error)
  process.exit(1)
})
This creates a coding agent that accepts requests from the command-line. The coding agent’s uniquely named sandbox is generated from Blaxel’s blaxel/py-app image, which contains a complete Python development environment. Test the agent: 
npx tsx index.ts "Write a Python program to calculate the number of vowels in a word. Show the code. Test it and show the results."
The agent will start working on the task in a sandbox, streaming its responses as it works. Here’s a partial example of the output: 
agent > Here's the Python program to calculate the number of vowels in a word:

def count_vowels(word):
    vowels = "aeiouAEIOU"
    count = 0
    for letter in word:
        if letter in vowels:
            count += 1
    return count

# Test words
test_words = ["hello", "Python", "AEIOU", "rhythm", "beautiful", "sky"]

...
That’s it! You’re ready to start building and deploying Blaxel sandbox-backed agents with Mastra.

​
Resources

Want more info on developing and deploying agents on Blaxel? Check out the following resources:

Deploy your agent code to Blaxel

Complete tutorial for deploying AI agents to Blaxel.

Manage environment variables

Complete tutorial for managing variables and secrets when deploying to Blaxel.

Mastra documentation

Official Mastra documentation.
Last modified on May 20, 2026