Welcome to your new Mastra project! We're excited to see what you'll build.

Start the development server:

npm run dev

Open http://localhost:4111 in your browser to access Mastra Studio. It provides an interactive UI for building and testing your agents, along with a REST API that exposes your Mastra application as a local service. This lets you start building without worrying about integration right away.

You can start editing files inside the src/mastra directory. The development server will automatically reload whenever you make changes.

To learn more about Mastra, visit our documentation. Your bootstrapped project includes example code for agents, tools, workflows, scorers, and observability.

If you're new to AI agents, check out our course and YouTube videos. You can also join our Discord community to get help and share your projects.

This repo now includes a hybrid four-role GitHub delivery flow for personal side projects:

• Product manager selects or creates the next GitHub issue in Mastra
• Software architect turns that issue into an implementation plan in Mastra
• Software engineer executes the plan in an isolated Sandcastle worktree / sandbox and opens a pull request
• Code reviewer inspects the PR in an isolated Sandcastle run and submits the final GitHub review

Mastra owns orchestration, durable-ish workflow state, task progression, and GitHub coordination. Sandcastle owns isolated engineer / reviewer execution.

The orchestration is registered as githubSideProjectWorkflow, and the specialist agents are also available individually from src/mastra/agents.

For autonomous repository and pull request operations, set GITHUB_TOKEN.

For GitHub webhook / @mention handling through @chat-adapter/github, configure either:

• GITHUB_TOKEN for the simplest personal-project setup, or
• GITHUB_APP_ID, GITHUB_PRIVATE_KEY, and optionally GITHUB_INSTALLATION_ID for GitHub App mode

When using GitHub webhooks, also set:

• GITHUB_WEBHOOK_SECRET
• GITHUB_BOT_USERNAME

To run the engineer and reviewer stages, configure Sandcastle in .env:

• Set SANDCASTLE_PROVIDER to docker or podman
• Set SANDCASTLE_IMAGE_NAME to an image that has the tooling your target repos need
• Set SANDCASTLE_AGENT_PROVIDER and SANDCASTLE_AGENT_MODEL
• Provide the matching API key such as ANTHROPIC_API_KEY or OPENAI_API_KEY
• Optionally set SANDCASTLE_SANDBOX_READY_COMMANDS for one-time sandbox bootstrapping like pnpm install --frozen-lockfile

The hybrid workflow writes Sandcastle logs under each target repo's .sandcastle/logs/ directory.

See docs/hybrid-architecture.md for the full MVP architecture, required env vars, and an example workflow input.

The Mastra platform provides two products for deploying and managing AI applications built with the Mastra framework:

• Studio: A hosted visual environment for testing agents, running workflows, and inspecting traces
• Server: A production deployment target that runs your Mastra application as an API server

Learn more in the Mastra platform documentation.