Running OpenCode in CLI and Web Mode: What to Configure and How

OpenCode is flexible enough to run as a terminal TUI, a headless server, or a web interface. That flexibility is useful, but it also means the startup path, config loading, and working directory rules matter more than people expect. If you point OpenCode at a local model server or a remote OpenAI-compatible endpoint, the difference between opencode, opencode serve, and opencode web determines how the project folder, config file, and model selection are resolved.

This guide shows the practical ways to run OpenCode, how to configure providers and models, and how to make web mode open against your current project instead of falling back to C:\.

---

Launch Modes at a Glance

OpenCode has three modes that matter for day-to-day use:

• CLI/TUI mode with opencode or opencode <project>
• Headless server mode with opencode serve
• Web UI mode with opencode web

The CLI/TUI is usually the simplest: start it in the folder you want to work on, and OpenCode uses that folder as the project root. The headless server and web UI add an extra layer, so you need to be more explicit about where the project is and which config file should be loaded.

Known TUI Issue on Windows ARM64

One problem I hit while testing OpenCode on Windows ARM64 was that the TUI could fail before becoming usable, even when the installation and config looked correct. The symptoms were noisy terminal output, an immediate exit, or a crash in the TUI path while the non-interactive run command still worked.

The practical takeaway is that the TUI can be the least reliable entry point on ARM64 Windows. If you see broken output or the session exits immediately, try these checks first:

node -p "process.arch"
opencode -v
where.exe opencode

If the machine architecture, Node architecture, and OpenCode binary do not line up, the TUI can behave strangely even though the rest of the CLI still starts. In my case, switching to the correct ARM64 OpenCode install and removing stale shims fixed the launcher path, but the TUI itself still had an upstream ARM64 limitation.

For that reason, the most dependable fallback on this platform is web mode or the headless server mode.

---

The Core Configuration File

OpenCode looks for opencode.json. In a project, place it in the repository root so it belongs to that workspace. A minimal configuration for a local OpenAI-compatible server looks like this:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "local": {
      "options": {
        "baseURL": "http://192.168.x.x:8080",
        "apiKey": "sk-dummy"
      },
      "models": {
        "qwen3": {}
      }
    }
  },
  "model": "local/qwen3"
}

The important part is the nesting:

• provider.local.options.baseURL points to the backend API.
• provider.local.options.apiKey can be a dummy value if your backend does not require auth.
• provider.local.models.qwen3 defines the model name OpenCode should expose.
• model sets the default selection in provider/model form.

If you use a built-in provider name like anthropic or openai, OpenCode may treat it differently from a custom provider. For a local proxy or remote compatible server, a custom name such as local is usually the cleanest option.

---

Running OpenCode in the Current Folder

For local development, the safest pattern is to start OpenCode from the folder you want to use as the project root:

Set-Location C:\Projects\GitHub\MyProject
opencode

That is the simplest way to make the current folder become the working directory.

If you want the interactive TUI to open on a specific folder without changing your shell first, use the positional project argument:

opencode C:\Projects\GitHub\MyProject

That works for the TUI startup path. It is the most direct way to tell OpenCode which repository to treat as the active workspace.

---

Running Web Mode

Web mode is the same idea, but it starts a server and opens the browser UI instead of the terminal TUI:

Set-Location C:\Projects\GitHub\MyProject
$env:OPENCODE_CONFIG = "C:\Projects\GitHub\MyProject\opencode.json"
$env:OPENCODE_SERVER_PASSWORD = "mypassword"
opencode web --port 4096 --print-logs --log-level INFO

Two details matter here:

• Start it from the project directory if you want the browser to reflect that workspace.
• Keep OPENCODE_CONFIG pointed at your project config when you want the server to resolve your custom provider and model.

In practice, web mode is more sensitive to the launch context than the CLI path. If the browser shows a root like C:\, that usually means the server was started from the wrong working directory or an old session is still selected.

---

Why Web Mode Can Show C:\

If the browser keeps showing C:\, the cause is usually one of these:

1. The server was started from the wrong folder.
2. An older session was resumed and still points to a different project.
3. The UI is showing a session path, not the server root.

The fix is straightforward:

Set-Location C:\Projects\GitHub\MyProject
opencode web --port 4096

Then create a new session in the web UI and verify the active project from a second terminal:

Invoke-RestMethod "http://127.0.0.1:4096/project/current" | ConvertTo-Json -Depth 6

That endpoint is the reliable source of truth for the server-side project root.

---

Remote Providers and Custom Models

OpenCode can talk to a remote server that exposes an OpenAI-compatible API, as long as the provider config is shaped correctly.

For example, a local proxy and an Anthropic-compatible endpoint can live in the same file:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "local": {
      "options": {
        "baseURL": "http://192.168.x.x:8080",
        "apiKey": "sk-dummy"
      },
      "models": {
        "qwen3": {}
      }
    },
    "anthropic": {
      "options": {
        "baseURL": "http://192.168.x.x:8082/v1",
        "apiKey": "any-value"
      }
    }
  },
  "model": "local/qwen3"
}

This setup gives you two useful properties:

• Your local or remote backend can be addressed through one stable provider name.
• You can switch between providers and models without rewriting your app settings.

For OpenCode, the model name is not just a label. The combination of provider plus model is what determines which backend is used.

---

Environment Variables Worth Knowing

When starting OpenCode from scripts or shell profiles, these variables are the ones that matter most:

• OPENCODE_CONFIG points OpenCode to a specific config file.
• OPENCODE_SERVER_PASSWORD protects the web server.
• --hostname (or the server.hostname config option) can be used when you want to bind more broadly than localhost.

For a local-only setup, keep the server on 127.0.0.1. If you want to access it from another machine on your network, bind to 0.0.0.0 or use the hostname option carefully and add authentication.

---

Recommended Start Commands

Here are the commands I would actually use:

CLI/TUI

Set-Location C:\Projects\GitHub\MyProject
opencode

Web server for the current repo

Set-Location C:\Projects\GitHub\MyProject
$env:OPENCODE_CONFIG = "C:\Projects\GitHub\MyProject\opencode.json"
$env:OPENCODE_SERVER_PASSWORD = "mypassword"
opencode web --port 4096 --print-logs --log-level INFO

Explicit project path

opencode C:\Projects\GitHub\MyProject

The first command is best when you want the shell session to define the workspace. The second is best when you want browser access. The third is best when you want a quick one-shot TUI launch from anywhere.

---

Troubleshooting Checklist

If OpenCode does not behave as expected, check these in order:

1. Confirm the config file is named opencode.json.
2. Confirm provider.<name>.options.baseURL is inside options.
3. Confirm the default model uses the provider/model format.
4. Start OpenCode from the correct folder.
5. Check http://127.0.0.1:4096/project/current for the active server workspace.
6. Create a new browser session instead of resuming an old one.

If the web UI still seems to point at C:\, the problem is usually not the provider config. It is almost always launch context or an older session state.

---

Final Notes

OpenCode is easiest to use when you treat the project folder, config file, and launch command as one unit. Put opencode.json in the repo root, start the server from that folder, and keep the provider/model mapping explicit. Once that is in place, web mode becomes predictable and you can switch between local and remote backends without guessing which model is active.

If you want a fully repeatable workflow, put the startup command into a PowerShell script or VS Code task so you always launch OpenCode the same way.