Allow configuration of external opencode serve process (#295)

* feature: Allow configuration of external opencode serve process (rather than spawning automatically). This lets a developer connect to a containerized or other remote opencode server instance.

---------

Co-authored-by: Francis Belanger <francis.belanger@gmail.com>

Author: sei-dwtompkins

README.md

@@ -49,15 +49,19 @@ Refer to the [Quick Chat](#-quick-chat) section for more details.
 - [Installation](#-installation)
 - [Configuration](#️-configuration)
 - [Usage](#-usage)
+- [Permissions](#-permissions)
 - [Context](#-context)
 - [Agents](#-agents)
-- [User Commands](#user-commands)
+- [Custom/External Server Configuration](#-customexternal-server-configuration)
+- [User Commands and Slash Commands](#user-commands-and-slash-commands)
 - [Contextual Actions for Snapshots](#-contextual-actions-for-snapshots)
-- [Prompt Guard](#-prompt-guard)
+- [Contextual Restore points](#-contextual-restore-points)
+- [Highlight Groups](#highlight-groups)
+- [Prompt Guard](#️-prompt-guard)
 - [Custom user hooks](#-custom-user-hooks)
 - [Server-Sent Events (SSE) autocmds](#-server-sent-events-sse-autocmds)
-- [Quick Chat](#-quick-chat)
-- [Setting up opencode](#-setting-up-opencode)
+- [Quick Chat](#quick-chat)
+- [Setting up Opencode](#-setting-up-opencode)
 
 ## ⚠️Caution
 
@@ -120,6 +124,17 @@ require('opencode').setup({
   default_system_prompt = nil, -- Custom system prompt to use for all sessions. If nil, uses the default built-in system prompt
   keymap_prefix = '<leader>o', -- Default keymap prefix for global keymaps change to your preferred prefix and it will be applied to all keymaps starting with <leader>o
   opencode_executable = 'opencode', -- Name of your opencode binary
+
+  -- Server configuration for custom/external opencode servers
+  server = {
+    url = nil,             -- URL/hostname (e.g., 'http://192.168.1.100', 'localhost', 'https://myserver.com')
+    port = nil,            -- Port number (e.g., 8080), 'auto' for random port
+    timeout = 5,           -- Health check timeout in seconds when connecting
+    spawn_command = nil,   -- Optional function to start the server: function(port, url) ... end
+    auto_kill = true,      -- Kill spawned servers when last nvim instance exits (default: true) Only applies to servers spawned by the plugin with spawn_command/kill_command
+    path_map = nil,        -- Map host paths to server paths: string ('/app') or function(path) -> string
+  },
+
   keymap = {
     editor = {
       ['<leader>og'] = { 'toggle' }, -- Open opencode. Close if opened
@@ -757,6 +772,177 @@ You can create custom agents through your opencode config file. Each agent can h
 
 See [Opencode Agents Documentation](https://opencode.ai/docs/agents/) for full configuration options.
 
+## 🔌 Custom/External Server Configuration
+
+By default, opencode.nvim spawns a local `opencode serve` process. You can instead connect to an external or containerized opencode server by configuring the `server` table.
+
+### Basic Connection
+
+Connect to an existing server:
+
+```lua
+require('opencode').setup({
+  server = {
+    url = 'localhost',     -- or 'http://192.168.1.100'
+    port = 8080,
+    timeout = 5,
+  },
+})
+```
+
+### Auto-Spawning with Docker
+
+Use `spawn_command` to automatically start your server and `kill_command` to stop it:
+
+```lua
+require('opencode').setup({
+  server = {
+    url = 'localhost',
+    port = 'auto',  -- Random port for project isolation
+    -- Path mapping: translate host paths to container paths
+    path_map = function(host_path)
+      local cwd = vim.fn.getcwd()
+      -- Replace host project directory with container mount point
+      return host_path:gsub(vim.pesc(cwd), '/app')
+    end,
+    -- Spawn command: start Docker container with opencode server
+    spawn_command = function(port, url)
+      local dir_name = string.lower(vim.fn.fnamemodify(vim.fn.getcwd(), ":t"))
+      local cwd = vim.fn.getcwd()
+      local container_name = string.format('opencode-%s', dir_name)
+
+      -- Check if container is already running
+      local check_cmd = string.format('docker ps --filter "name=%s" --format "{{.Names}}"', container_name)
+      local handle = io.popen(check_cmd)
+      local result = handle:read("*a")
+      handle:close()
+
+      if result and result:match(container_name) then
+        print(string.format("[opencode.nvim] Container %s is already running, skipping start", container_name))
+        return true
+      end
+
+      -- First, try to stop any existing container with the same name
+      os.execute(string.format('docker stop %s 2>/dev/null || true', container_name))
+
+      local cmd = string.format([[
+docker run -d --rm \
+--name %s \
+-p %d:4096 \
+-v ~/.local/state/opencode:/home/node/.local/state/opencode \
+-v ~/.local/share/opencode:/home/node/.local/share/opencode \
+-v ~/.config/opencode:/home/node/.config/opencode \
+-v "%s":/app:rw \
+opencode:latest opencode serve --port 4096 --hostname '0.0.0.0']],
+        container_name,
+        port,
+        cwd
+      )
+
+      print(string.format("[opencode.nvim] Starting OpenCode container: %s on port %d", container_name, port))
+      return os.execute(cmd)
+    end,
+    -- Kill command: stop Docker container when auto_kill is triggered
+    kill_command = function(port, url)
+      local dir_name = string.lower(vim.fn.fnamemodify(vim.fn.getcwd(), ":t"))
+      local container_name = string.format('opencode-%s', dir_name)
+
+      print(string.format("[opencode.nvim] Stopping OpenCode container: %s", container_name))
+      return os.execute(string.format('docker stop %s 2>/dev/null', container_name))
+    end,
+    auto_kill = true,  -- Enable automatic cleanup when last nvim exits
+  },
+})
+```
+
+### Path Mapping for Containers/WSL
+
+When paths on the server differ from your host (e.g., `/app` in container vs `/home/user/project` on host):
+
+```lua
+require('opencode').setup({
+  server = {
+    url = 'localhost',
+    port = 8080,
+    path_map = '/app',  -- Simple string replacement
+  },
+})
+```
+
+### Auto-Spawning with WSL
+
+Run opencode server inside WSL while using Neovim on Windows:
+
+```lua
+require('opencode').setup({
+  server = {
+    url = 'localhost',
+    port = 'auto',  -- Random port for project isolation
+
+    -- Spawn opencode server inside WSL
+    spawn_command = function(port, url)
+      local cmd = string.format(
+        'wsl.exe -e bash -c "opencode serve --hostname 127.0.0.1 --port %d"',
+        port
+      )
+      print(string.format('[opencode.nvim] Starting WSL server on port %d', port))
+      return vim.fn.jobstart(cmd, { detach = 1 })
+    end,
+
+    -- Kill WSL opencode process
+    kill_command = function(port, url)
+      print(string.format('[opencode.nvim] Stopping WSL server on port %d', port))
+      vim.fn.jobstart('wsl.exe -e pkill -f "opencode serve.*--port ' .. port .. '"')
+    end,
+
+    -- Windows → WSL path translation (for requests)
+    path_map = function(host_path)
+      if vim.fn.has('win32') == 1 then
+        -- Convert C:\Users\... → /mnt/c/Users/...
+        local drive, rest = host_path:match('^([A-Za-z]):(.*)$')
+        if drive then
+          local wsl_path = '/mnt/' .. drive:lower() .. rest:gsub('\\', '/')
+          return wsl_path
+        end
+      end
+      return host_path
+    end,
+
+    -- WSL → Windows path translation (for responses)
+    reverse_path_map = function(server_path)
+      -- Convert /mnt/c/Users/... → C:\Users\...
+      local drive, rest = server_path:match('^/mnt/([a-z])(.*)$')
+      if drive then
+        local windows_path = drive:upper() .. ':' .. rest:gsub('/', '\\')
+        return windows_path
+      end
+      return server_path
+    end,
+
+    auto_kill = true,  -- Kill server when last nvim instance exits
+  },
+})
+```
+
+### Configuration Options
+
+- `url` (string | nil): Server hostname/URL (e.g., 'localhost', 'http://192.168.1.100')
+- `port` (number | 'auto' | nil): Port number, `'auto'` for random port, or nil for default (4096)
+- `timeout` (number): Health check timeout in seconds (default: 5)
+- `spawn_command` (function | nil): Optional function to start server: `function(port, url) ... end`
+- `kill_command` (function | nil): Optional function to stop server when `auto_kill` triggers: `function(port, url) ... end`
+- `auto_kill` (boolean): Kill spawned servers when last nvim instance exits (default: true)
+- `path_map` (string | function | nil): Transform host paths to server paths (for outgoing requests)
+- `reverse_path_map` (function | nil): Transform server paths back to host paths (for incoming responses/events)
+
+### Multi-Instance Support
+
+When `port = 'auto'` is used, opencode.nvim:
+
+- Tracks which nvim instances are using each port
+- Only kills the server when the last nvim instance exits (if `auto_kill = true`). Only applies to servers spawned by the plugin with `spawn_command`/`kill_command`.
+- Locally spawned servers will be killed automatically regardless of the auto_kill setting if they are the last nvim instance using them
+
 ## User Commands and Slash Commands
 
 You can run predefined user commands and built-in slash commands from the input window by typing `/`. This opens a command picker where you can select a command to execute. The output of the command will be included in your prompt context.

lua/opencode/api_client.lua

@@ -1,5 +1,29 @@
 local server_job = require('opencode.server_job')
 local state = require('opencode.state')
+local url_encode = require('opencode.util').url_encode
+local apply_path_map = require('opencode.util').apply_path_map
+local reverse_transform_paths_recursive = require('opencode.util').reverse_transform_paths_recursive
+
+--- Transform file paths in API payloads using configured path_map
+--- @param data any The data to transform (table, string, or other)
+--- @return any transformed_data The data with paths transformed
+local function transform_paths_recursive(data)
+  if type(data) ~= 'table' then
+    return data
+  end
+
+  local result = {}
+  for key, value in pairs(data) do
+    if type(value) == 'string' and (key == 'filePath' or key == 'path' or key == 'directory') then
+      result[key] = apply_path_map(value)
+    elseif type(value) == 'table' then
+      result[key] = transform_paths_recursive(value)
+    else
+      result[key] = value
+    end
+  end
+  return result
+end
 
 --- @class OpencodeApiClient
 --- @field base_url string The base URL of the opencode server
@@ -67,11 +91,13 @@ function OpencodeApiClient:_call(endpoint, method, body, query)
       query.directory = state.current_cwd or vim.fn.getcwd()
     end
 
+    query = transform_paths_recursive(query)
+
     local params = {}
 
     for k, v in pairs(query) do
       if v ~= nil then
-        table.insert(params, k .. '=' .. tostring(v))
+        table.insert(params, url_encode(k) .. '=' .. url_encode(v))
       end
     end
 
@@ -80,7 +106,13 @@ function OpencodeApiClient:_call(endpoint, method, body, query)
     end
   end
 
-  return server_job.call_api(url, method, body)
+  if body and type(body) == 'table' then
+    body = transform_paths_recursive(body)
+  end
+
+  return server_job.call_api(url, method, body):and_then(function(result)
+    return reverse_transform_paths_recursive(result)
+  end)
 end
 
 -- Project endpoints
@@ -433,15 +465,16 @@ function OpencodeApiClient:subscribe_to_events(directory, on_event)
   self:_ensure_base_url()
   local url = self.base_url .. '/event'
   if directory then
-    url = url .. '?directory=' .. directory
+    local mapped_directory = apply_path_map(directory)
+    url = url .. '?directory=' .. url_encode(mapped_directory)
   end
 
   return server_job.stream_api(url, 'GET', nil, function(chunk)
-    -- strip data: prefix if present
     chunk = chunk:gsub('^data:%s*', '')
     local ok, event = pcall(vim.json.decode, vim.trim(chunk))
     if ok and event then
-      on_event(event --[[@as table]])
+      local transformed_event = reverse_transform_paths_recursive(event)
+      on_event(transformed_event --[[@as table]])
     end
   end)
 end

lua/opencode/config.lua

@@ -14,6 +14,21 @@ M.defaults = {
   legacy_commands = true,
   keymap_prefix = '<leader>o',
   opencode_executable = 'opencode',
+  server = {
+    url = nil,
+    port = nil,
+    timeout = 5,
+    retry_delay = 2000,
+    spawn_command = nil,
+    kill_command = nil,
+    auto_kill = true,
+    path_map = function(path)
+      return path
+    end,
+    reverse_path_map = function(path)
+      return path
+    end,
+  },
   keymap = {
     editor = {
       ['<leader>og'] = { 'toggle', desc = 'Toggle Opencode window' },

lua/opencode/curl.lua

@@ -28,6 +28,11 @@ local function build_curl_args(opts)
     table.insert(args, opts.proxy)
   end
 
+  if opts.timeout then
+    table.insert(args, '--max-time')
+    table.insert(args, tostring(math.ceil(opts.timeout / 1000)))
+  end
+
   table.insert(args, opts.url)
 
   return args
@@ -76,6 +81,9 @@ end
 function M.request(opts)
   local args = build_curl_args(opts)
 
+  local log = require('opencode.log')
+  log.debug('curl.request: executing command: %s', table.concat(args, ' '))
+
   if opts.stream then
     local buffer = ''
     -- job.pid is not cleared on process exit
@@ -157,7 +165,8 @@ function M.request(opts)
     vim.system(args, job_opts, function(result)
       if result.code ~= 0 then
         if opts.on_error then
-          opts.on_error({ message = result.stderr or 'curl failed' })
+          local err_msg = (result.stderr and result.stderr ~= '') and result.stderr or 'curl failed'
+          opts.on_error({ message = err_msg })
         end
         return
       end