Machine vs OpenCode config
The strict ownership boundary between machine.toml and the .machine/opencode/ config directory.
A Machine project's config has two owners, and the boundary is strict.
- Machine owns
machine.tomland.machine/Dockerfile— what a project is, its sandbox, secrets, triggers, apps. - OpenCode owns
.machine/opencode/— how the agent behaves. The platform never reads inside it; it only tells OpenCode where it is.
The config dir is declared via [opencode] config_dir (default .machine/opencode); the agent daemon launches OpenCode with OPENCODE_CONFIG_DIR pointed there.
Ownership table
| Concern | Lives in | Read by |
|---|---|---|
Project metadata (name, description) | machine.toml [project] | Machine |
| Env / secrets spec | machine.toml [env] | Machine |
| Sandbox base image | machine.toml [sandbox] + .machine/Dockerfile | Machine |
| Where the OpenCode config dir lives | machine.toml [opencode] config_dir | Machine |
| Triggers (cron + webhook) | machine.toml [[triggers]] | Machine |
| Apps (experimental) | machine.toml [[apps]] | Machine |
| Agent personas | .machine/opencode/agents/ | OpenCode |
| Skills | .machine/opencode/skills/ | OpenCode |
| Slash commands | .machine/opencode/ (commands) | OpenCode |
| Custom tools | .machine/opencode/ (tools) | OpenCode |
| Plugins | .machine/opencode/ (plugins) | OpenCode |
| MCP servers | .machine/opencode/opencode.jsonc | OpenCode |
| Model / provider config | .machine/opencode/opencode.jsonc | OpenCode |
Rule of thumb
If it describes the project, the sandbox, when work runs, or what gets deployed, it belongs in machine.toml. If it describes how the agent thinks, talks, or acts, it belongs under .machine/opencode/.
Full machine.toml field reference: machine.toml. The .machine/opencode/ directory follows OpenCode's standard layout; see opencode.ai/docs for each primitive.
Where the agent runs
The agent runtime is OpenCode, and Machine runs it in the cloud sandbox — the sandbox agent server launches OpenCode with OPENCODE_CONFIG_DIR set to your config_dir. There is no Machine command that runs the agent on your machine; the CLI is a cloud control plane, not a local runner.
Because .machine/opencode/ uses OpenCode's standard layout, the personas, skills, and tools are portable: install the upstream opencode binary and point its config dir at that folder and it reads the same files.
New files under .machine/opencode/ reach future sandbox sessions only after a change request merges them to main.