Configuration

Each lesson has a prompt you can copy and paste into OpenCode. The prompt includes your student ID and a link to this site, which gives OpenCode everything it needs to teach the lesson and track your progress.

In this lesson, you’ll create a global configuration file that will apply to every OpenCode session across every project on your machine. It includes settings like which AI model to use, what permissions to grant, and how the agent should behave. You’ll tweak your global configuration over time to make OpenCode work exactly the way you want.

If you’ve already created a global config file, that’s great — it won’t be overwritten. OpenCode will merge in any missing settings.

Create the global config file

When OpenCode starts, it looks for a global config file in this location:

~/.config/opencode/opencode.json

~/.config/opencode/opencode.json

~/.config/opencode/opencode.json

OpenCode will create the directory and file for you. If you see any confirmation prompts, choose “Allow Once.” You may see a couple of prompts during this step, so approve each one.

Set some basic configuration

Here’s what your config file will look like:

{
  "$schema": "https://opencode.ai/config.json",
  "default_agent": "plan",
  "permission": {
    "*": "allow",
    "external_directory": "ask",
    "bash": {
      "*": "allow",
      "rm *": "ask",
      "rmdir *": "ask"
    }
  },
  "instructions": [
    "https://<this-site>/api/instructions/<your-student-id>"
  ]
}

We’ll substitute your actual student ID when we create the file. A few things to note:

• "default_agent": "plan" means every new session starts in Plan mode — a read-only agent that can read your files and discuss your project but won’t make any changes. When you’re ready to act, you switch to Build. We’ll cover this in detail in the Agents lesson.
• "external_directory": "ask" means OpenCode will pause and ask before reading or editing files outside the current project directory. This is the default behavior, but setting it explicitly makes the config self-documenting.
• The "bash" block inside "permission" adds safety guardrails for shell commands. Most commands run automatically, but rm (delete files) and rmdir (remove directories) will pause and ask for your approval first. We’ll add more permission rules in the next lesson.
• The instructions URL lets OpenCode fetch your school enrollment at the start of every session, so it has your student profile on hand even when you’re working on something unrelated.

Restart OpenCode

Config changes take effect the next time OpenCode starts. Once the file is created, quit OpenCode Desktop and reopen it, then return to this chat session so OpenCode can verify your config.

Verify config is working

Let’s ask OpenCode to check that the config file exists and is being applied correctly.

The config also supports models, MCP servers, custom commands, agents, themes, and keybinds — we’ll get to those in later lessons. Full reference: OpenCode config docs.