Mason runs your agents in secure Docker containers scoped to what they need with Roles.
mason is a TypeScript command-line tool that runs your agents in containers. You'll need three things:
npm install -g @clawmasons/masonRun a project configured for claude code in a secure container
cd your-project-dir
mason claudeYou can also run projects with other agents using the claude config
mason codex --source claudeOr vice versa if your project was setup with codex
mason claude --source codexThe mason project uses roles to strictly define what an agent can do.
When mason is run without the "--role" argument, it builds an in-memory role that has all of the "source" skills, mcp-servers, etc, and the container is configured to allow all of those operations.
Have your agent configure your project's roles with mason.
cd ~/your-project
mason configure --agent claudemason claude --role {project-role}Follow the instructions generated in .mason/initial-role-plan.md to test the roles.
Joe is a DevOps engineer running a project. He has admin-level AWS, GitHub, and Jira credentials on his laptop. He also has skills loaded up in .claude ready to use all those credentials as needed for his workflow.
This is a powder keg waiting for either a prompt injection attack or an agent to accidentally run the wrong skill at the wrong time.
Joe installs and runs mason configure to get roles that look like:
Devops
- skills: terraform, ship-it
- tools: aws
Lead
- skills: review-pr, merge-pr, create-story, create-bug
- tools: github-pr-merge
Developer
- skills: openspec, implement-story, fix-bug
- tools: github-pr-create
Joe runs Claude and interacts with it like it was running on his host computer. If he needs to write code:
mason claude --role developerThis locks the agent into a secure Docker container, with only access to that role's skills, tools, and the project directory. Furthermore, MCP servers for the tools (and the credentials necessary to run them) are executed in an MCP proxy sidecar container. No risk of an overly helpful agent or prompt injection attack deleting AWS resources.
The container environment provides both security and allows the agent to focus on their current role.
That's the dream, and the goal for our developer experience.
| Command | Description |
|---|---|
mason run <agent> --role <name> |
Run a role on the specified agent runtime |
mason <agent> --role <name> |
Shorthand for run |
mason run <agent> --role <name> --acp |
Run as an ACP agent which proxies to the agent in the container |
mason run <agent> --role <name> --dev-container |
Run project in a dev container with the agent enabled within VS Code |
| Doc | Description |
|---|---|
| Overview | What Mason is and why it matters |
| Getting Started | Install and run your first role |
| Core Concepts | Roles, tasks, skills, apps, and how they compose |
| Architecture | Runtime architecture with sequence diagrams |
| CLI Reference | Complete command reference |
| Security Model | Credentials, permissions, audit logging |
| MCP Proxy | Tool filtering and routing |
| Credential Service | Secure credential resolution |
See Development for build instructions, project structure, and the programmatic API.
MIT