Agent Builder

A minimal Mastra Agent Builder template with safe defaults. It includes only the Mastra and Agent Builder setup, with no starter agents, tools, or workflows.

Features

  • Agent Builder enabled by default
  • WorkOS AuthKit authentication and WorkOS-backed RBAC permissions
  • Local filesystem workspace at .mastra/workspace
  • No starter agents, tools, or workflows
  • Observational memory enabled for builder-created agents
  • Optional providers only register when their environment variables are configured

Prerequisites

  • Node.js 22.13 or newer
  • An OpenAI API key
  • A valid MASTRA_EE_LICENSE for Agent Builder
  • WorkOS AuthKit credentials for authentication/RBAC

Quickstart

  1. Create the project

    npx create-mastra@latest --template agent-builder

  2. Configure environment variables Copy .env.example to .env, then set:

    • MASTRA_EE_LICENSE — required; the template fails fast if it is missing or shorter than 32 characters.
    • OPENAI_API_KEY — required for builder-created agents that use the default OpenAI model.
    • WORKOS_API_KEY, WORKOS_CLIENT_ID, and WORKOS_COOKIE_PASSWORD — required for AuthKit login and RBAC. The cookie password must be at least 32 characters.
    • WORKOS_REDIRECT_URI — defaults to http://localhost:4111/api/auth/callback.

  3. Start Mastra

    npm run dev

  4. Open Studio Visit localhost:4111 and open Agent Builder.

Optional integrations

The template does not register optional integrations with empty credentials. They appear only after you set their required environment variables:

  • Composio: set COMPOSIO_API_KEY.
  • Slack: set SLACK_APP_CONFIG_TOKEN and SLACK_APP_CONFIG_REFRESH_TOKEN. SLACK_BASE_URL is optional.
  • Browserbase + Stagehand: set both BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID.

Git credentials are not needed for the default template. The workspace uses the local filesystem, so there are no GIT_* or GITHUB_TOKEN requirements.

Making it yours

Edit the files under src/mastra to add your own resources and adjust the setup:

  • index.ts configures Mastra, Agent Builder, auth/RBAC, and optional providers.
  • auth.ts configures WorkOS AuthKit and role-to-permission mappings.
  • workspace.ts configures the local filesystem workspace.
  • env.ts contains the environment variable helpers and license guard.

About Mastra templates

Mastra templates are ready-to-use projects that show what you can build with Mastra. They live in the Mastra monorepo and are synced to standalone repositories for easier cloning.