Roles and Permissions

How Roles Work

Every session runs with a role. The role determines:

• System prompt -- instructions for the AI
• MCP server access -- which tool servers are available
• Tool permissions -- which specific tools can be used
• Model parameters -- temperature, top_p, top_k
• Pipeline -- optional deterministic script pre-processing (runs before workflow)
• Workflow -- optional AI-driven pre-processing pipeline

Built-in Roles

Octomind's default tap (muvon/octomind-tap) provides production-ready roles:

octomind run octomind:assistant    # Chat-only with tools
octomind run octomind:developer    # Full development tools

Defining Custom Roles

Define roles in [[roles]] config sections. Custom roles override tap-provided roles with the same name.

[[roles]]
name = "assistant"
temperature = 0.3
top_p = 0.7
top_k = 20
system = """
You are helpful and knowledgeable assistant.
Working directory: {{CWD}}
"""
welcome = "Hello! Working in {{CWD}} (Role: {{ROLE}})"

[roles.mcp]
server_refs = ["core", "runtime", "filesystem", "agent"]
allowed_tools = ["core:*", "runtime:*", "filesystem:*", "agent:*"]

Role Fields

When both pipeline and workflow are set, the execution order is: user message → pipeline (scripts) → workflow (AI) → main model. The pipeline's output replaces the user message as input to the workflow. See Pipelines for details.

Tool Permissions

Server References

server_refs lists which MCP servers this role can access:

[roles.mcp]
server_refs = ["core", "filesystem"]  # Only core and filesystem servers

Allowed Tools

allowed_tools controls which tools within those servers are available:

[roles.mcp]
server_refs = ["core", "runtime", "filesystem", "agent"]
allowed_tools = [
  "core:*",              # plan, schedule, capability, tap
  "runtime:mcp",         # only the mcp tool from runtime (skip agent / skill)
  "filesystem:view",     # Only view from filesystem
  "filesystem:shell",    # Only shell from filesystem
  "agent:*",             # All agent_* sub-agent tools
]

Builtin servers:

• core -- high-level day-to-day tools: plan, schedule, capability, tap.
• runtime -- low-level harness control: mcp (register servers), agent (register dynamic agents), skill (load skills). Most roles don't need this.
• agent -- dispatches to [[agents]]-defined ACP sub-agents (agent_<name> per entry).

Pattern syntax:

• "server:*" -- all tools from a server
• "server:tool_name" -- specific tool
• Empty array [] -- all tools from all referenced servers

Global Fallback

If a role doesn't specify allowed_tools, the global [mcp].allowed_tools is used:

[mcp]
allowed_tools = []  # No global restrictions (default)

Example Roles

Full Developer Access

[[roles]]
name = "developer"
temperature = 0.3
system = """
You are an expert software developer.
Working directory: {{CWD}}
Git status: {{GIT_STATUS}}
"""

[roles.mcp]
server_refs = ["core", "runtime", "filesystem", "agent"]
allowed_tools = ["core:*", "runtime:*", "filesystem:*", "agent:*"]

Read-Only Analyst

[[roles]]
name = "analyst"
temperature = 0.2
system = "You analyze code and provide insights. Do not modify files."

[roles.mcp]
server_refs = ["filesystem"]
allowed_tools = ["filesystem:view"]

Documentation Writer

[[roles]]
name = "docs"
model = "openrouter:openai/gpt-4o"
temperature = 0.4
system = "You write clear documentation."

[roles.mcp]
server_refs = ["filesystem"]
allowed_tools = ["filesystem:view", "filesystem:text_editor"]

Role with Workflow

[[roles]]
name = "planner"
workflow = "developer_workflow"
system = "You are a planning assistant."

[roles.mcp]
server_refs = ["core", "filesystem"]
allowed_tools = ["core:*", "filesystem:view"]

Using Roles

Starting a Session

# Use default role (from config `default` field)
octomind run

# Specify role by name
octomind run developer
octomind run assistant

# Use tap agent
octomind run octomind:developer
octomind run developer:general

Switching Roles Mid-Session

/role analyst
/role developer

Role Priority

When a role name matches both a config-defined role and a tap agent:

1. Config-defined [[roles]] take priority
2. Tap agents are used as fallback

Auto-Bind Servers

MCP servers can auto-attach to specific roles:

[[mcp.servers]]
name = "octocode"
type = "stdio"
command = "octocode"
args = ["mcp", "--path=."]
auto_bind = ["developer"]  # Automatically available in developer role

The server is automatically added to the role's server_refs even if not explicitly listed.