OpenCode Runtime
How Studio's execution engine works under the hood.
DOT Studio uses OpenCode as its execution runtime. The separation is simple:
| Layer | Responsibility |
|---|---|
| Studio | Workspace and composition — where you build |
| OpenCode | Execution — where things run |
On this page you'll learn:
- What OpenCode handles vs what Studio handles
- How models, sessions, tools, and safe mode work
- Common troubleshooting scenarios
Architecture Overview#
┌───────────────────────────────┐
│ DOT Studio │
│ ┌─────────────────────────┐ │
│ │ Performer Configuration│ │
│ │ Act Choreography │ │
│ │ Mode Selection │ │
│ └──────────┬──────────────┘ │
│ │ prepares │
│ ▼ │
│ ┌─────────────────────────┐ │
│ │ OpenCode Runtime │ │
│ │ ┌───────────────────┐ │ │
│ │ │ Model Execution │ │ │
│ │ │ Tool Execution │ │ │
│ │ │ Session Handling │ │ │
│ │ │ Provider APIs │ │ │
│ │ └───────────────────┘ │ │
│ └─────────────────────────┘ │
└───────────────────────────────┘
What OpenCode Is Responsible For#
When you run a Performer or Act, OpenCode handles:
- Model execution — sending prompts, streaming responses
- Tool execution — running function calls
- Session handling — context management and continuity
- Provider integration — connecting to Anthropic, OpenAI, etc.
Studio does not replace that runtime authority. It configures and drives it.
What Studio Prepares Before Execution#
Before a run, Studio packages the runtime inputs:
| For Performers | For Acts |
|---|---|
| Selected Tal | Participant contexts |
| Active Dances | Relation definitions |
| Model + variant | Act rules |
| Collaboration config | |
| Direct/safe mode | Direct/safe mode |
Models in Studio#
The models you see in Studio come from the runtime environment:
- If a model is available in the runtime → Studio can use it
- If it's not configured → Studio cannot invent it
Typical model configuration:
{
"provider": "anthropic",
"modelId": "claude-sonnet-4"
}
Sessions#
Sessions make conversations continuous instead of stateless.
| Session Type | Behavior | Best For |
|---|---|---|
| Standalone Performer | Each thread is a separate session | Independent conversations |
| Act Participant | Sessions are managed per-participant within the Act thread | Collaborative workflows |
When does this matter?
- Continuing a Performer chat
- Continuing an Act thread
- Deciding when a participant should react to new signals via subscriptions
Tools#
When a Performer runs, the runtime can use built-in runtime tools (filesystem, etc.).
Safe Mode vs Direct Mode#
One of the most important runtime ideas:
Safe mode changes the execution workspace, not the execution engine.
| Direct Mode | Safe Mode | |
|---|---|---|
| Target | Real project directory | Shadow workspace |
| Changes | Applied immediately | Held for review |
| User gets | Speed | Freedom + review step |
| Best for | Low-risk, trusted work | Risky code tasks |
What Happens When You Run a Performer#
1. Select or open a Performer
2. Studio prepares runtime config
3. OpenCode runs the model with tools/session
4. Results stream back into Studio
That's why a Performer can feel simple in the UI while still being grounded in a structured runtime underneath.
What Happens When You Run an Act#
1. Send a message in an Act thread
2. Studio prepares Act definition (participants, relations, subscriptions, rules)
3. OpenCode executes participant behavior & tools
4. Subscriptions wake up relevant participants
5. Results accumulate inside the thread
The choreography comes from Act configuration, but execution belongs to the runtime. You can update the Act definition while it's running — Studio syncs changes to active threads.
Why This Boundary Matters — FAQ#
"Why can I configure something in Studio but not run it yet?"#
Because Studio can express a configuration that the runtime still needs to satisfy — like a model that isn't available yet.
"Why is tool access missing?"#
Check auth state.
"Why is safe mode different from direct mode?"#
Because the runtime executes against a different workspace target, even though the execution engine is the same.
Troubleshooting Checklist#
| Symptom | What to Check |
|---|---|
| No models available | Runtime may not have model config yet |
| Thread feels wrong | Try creating a new thread to reset state |
| Safe mode results not in project | Expected — review and apply the diff first |
Bottom Line#
If you're using Studio successfully, you don't need to think about OpenCode every minute.
But when troubleshooting or designing advanced workflows, remember:
The Rule: Studio defines the workspace and choreography. OpenCode executes the work.