feat(docker): move opencode runtime and align XDG mounts

Relocate opencode binaries/UI to /opt to avoid bind-mount shadowing, add
state/cache mounts, and align default mount paths plus XDG envs for data
persistence. Update status and wizard copy to reflect the new mount layout.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: pRizz

packages/cli-rust/src/commands/status.rs

@@ -14,8 +14,9 @@ use opencode_cloud_core::Config;
 use opencode_cloud_core::bollard::service::MountTypeEnum;
 use opencode_cloud_core::config;
 use opencode_cloud_core::docker::{
-    CONTAINER_NAME, HealthError, MOUNT_APP_DATA, MOUNT_CONFIG, MOUNT_PROJECTS, MOUNT_SESSION,
-    OPENCODE_WEB_PORT, ParsedMount, check_health, get_cli_version, get_image_version, load_state,
+    CONTAINER_NAME, HealthError, MOUNT_CACHE, MOUNT_CONFIG, MOUNT_PROJECTS, MOUNT_SESSION,
+    MOUNT_STATE, OPENCODE_WEB_PORT, ParsedMount, check_health, get_cli_version, get_image_version,
+    load_state,
 };
 use opencode_cloud_core::platform::{get_service_manager, is_service_registration_supported};
 use std::collections::HashMap;
@@ -531,10 +532,11 @@ fn display_mounts_section(
 
 fn mount_purpose(target: &str) -> Option<&'static str> {
     match target {
-        MOUNT_APP_DATA => Some("sessions + app data"),
+        MOUNT_SESSION => Some("opencode data"),
+        MOUNT_STATE => Some("opencode state"),
+        MOUNT_CACHE => Some("opencode cache"),
         MOUNT_PROJECTS => Some("workspace files"),
         MOUNT_CONFIG => Some("opencode config"),
-        MOUNT_SESSION => Some("opencode runtime + binaries"),
         _ => None,
     }
 }

packages/cli-rust/src/wizard/mod.rs

@@ -121,7 +121,7 @@ fn display_mounts_info(step: usize, total: usize, mounts: &[String]) -> Result<(
         return Ok(());
     }
 
-    println!("Persist opencode sessions, workspace, and config on your host using these mounts:");
+    println!("Persist opencode data, state, cache, workspace, and config using these mounts:");
     println!();
     for mount in mounts {
         println!("  {}", style(mount).cyan());

packages/core/src/config/mod.rs

@@ -15,7 +15,6 @@ use anyhow::{Context, Result};
 use jsonc_parser::parse_to_serde_value;
 
 use crate::docker::mount::ParsedMount;
-use crate::docker::volume::MOUNT_SESSION;
 pub use paths::{get_config_dir, get_config_path, get_data_dir, get_hosts_path, get_pid_path};
 pub use schema::{Config, default_mounts, validate_bind_address};
 pub use validation::{
@@ -114,11 +113,12 @@ pub fn load_config() -> Result<Config> {
             Ok(parsed) => parsed,
             Err(_) => return true,
         };
-        if parsed.container_path == MOUNT_SESSION {
+        if parsed.container_path == "/opt/opencode"
+            || parsed.container_path.starts_with("/opt/opencode/")
+        {
             removed_shadowing_mounts = true;
             tracing::warn!(
-                "Skipping bind mount that overrides opencode binaries; use {} instead: {}",
-                crate::docker::volume::MOUNT_APP_DATA,
+                "Skipping bind mount that overrides opencode binaries: {}",
                 mount_str
             );
             return false;
@@ -127,7 +127,7 @@ pub fn load_config() -> Result<Config> {
     });
 
     if removed_shadowing_mounts {
-        tracing::info!("Removed bind mounts that shadow {}", MOUNT_SESSION);
+        tracing::info!("Removed bind mounts that shadow /opt/opencode");
     }
 
     ensure_default_mount_dirs(&config)?;

packages/core/src/config/schema.rs

@@ -2,8 +2,10 @@
 //!
 //! Defines the structure and defaults for the config.json file.
 
-use super::paths::{get_config_dir, get_data_dir};
-use crate::docker::volume::{MOUNT_APP_DATA, MOUNT_CONFIG, MOUNT_PROJECTS};
+use crate::docker::volume::{
+    MOUNT_CACHE, MOUNT_CONFIG, MOUNT_PROJECTS, MOUNT_SESSION, MOUNT_STATE,
+};
+use directories::BaseDirs;
 use serde::{Deserialize, Serialize};
 use std::net::{IpAddr, Ipv4Addr};
 /// Main configuration structure for opencode-cloud
@@ -176,18 +178,21 @@ fn default_update_check() -> String {
 }
 
 pub fn default_mounts() -> Vec<String> {
-    let maybe_data_dir = get_data_dir();
-    let maybe_config_dir = get_config_dir();
-    let (Some(data_dir), Some(config_dir)) = (maybe_data_dir, maybe_config_dir) else {
+    let Some(base_dirs) = BaseDirs::new() else {
         return Vec::new();
     };
+    let home_dir = base_dirs.home_dir();
 
-    let app_data_dir = data_dir.join("container-data");
+    let data_dir = home_dir.join(".local").join("share").join("opencode");
+    let state_dir = home_dir.join(".local").join("state").join("opencode");
+    let cache_dir = home_dir.join(".cache").join("opencode");
+    let config_dir = home_dir.join(".config").join("opencode");
     let workspace_dir = data_dir.join("workspace");
-    let config_dir = config_dir.join("container");
 
     vec![
-        format!("{}:{MOUNT_APP_DATA}", app_data_dir.display()),
+        format!("{}:{MOUNT_SESSION}", data_dir.display()),
+        format!("{}:{MOUNT_STATE}", state_dir.display()),
+        format!("{}:{MOUNT_CACHE}", cache_dir.display()),
         format!("{}:{MOUNT_PROJECTS}", workspace_dir.display()),
         format!("{}:{MOUNT_CONFIG}", config_dir.display()),
     ]

packages/core/src/docker/Dockerfile

@@ -164,6 +164,7 @@ RUN mkdir -p \
     /home/opencode/.config \
     /home/opencode/.local/bin \
     /home/opencode/.local/share \
+    /home/opencode/.local/state \
     /home/opencode/.cache \
     /home/opencode/workspace
 
@@ -529,16 +530,15 @@ RUN OPENCODE_COMMIT="c7fb116c1cf59a76b184f842ed3eb0113d93196b" \
     && bun run build-single-ui \
     && rm -rf /home/opencode/.bun/install/cache /home/opencode/.bun/cache /home/opencode/.cache/bun \
     && cd /tmp/opencode-repo \
-    && mkdir -p /home/opencode/.local/share/opencode/bin \
-    && mkdir -p /home/opencode/.local/share/opencode/ui \
-    && cp /tmp/opencode-repo/packages/opencode/dist/opencode-*/bin/opencode /home/opencode/.local/share/opencode/bin/opencode \
-    && cp -R /tmp/opencode-repo/packages/opencode/dist/opencode-*/ui/. /home/opencode/.local/share/opencode/ui/ \
-    && chown -R opencode:opencode /home/opencode/.local/share/opencode \
-    && chmod +x /home/opencode/.local/share/opencode/bin/opencode \
-    && /home/opencode/.local/share/opencode/bin/opencode --version
+    && sudo mkdir -p /opt/opencode/bin /opt/opencode/ui \
+    && sudo cp /tmp/opencode-repo/packages/opencode/dist/opencode-*/bin/opencode /opt/opencode/bin/opencode \
+    && sudo cp -R /tmp/opencode-repo/packages/opencode/dist/opencode-*/ui/. /opt/opencode/ui/ \
+    && sudo chown -R opencode:opencode /opt/opencode \
+    && sudo chmod +x /opt/opencode/bin/opencode \
+    && /opt/opencode/bin/opencode --version
 
 # Add opencode to PATH
-ENV PATH="/home/opencode/.local/share/opencode/bin:${PATH}"
+ENV PATH="/opt/opencode/bin:${PATH}"
 
 # -----------------------------------------------------------------------------
 # opencode-broker Installation
@@ -651,10 +651,10 @@ RUN printf '%s\n' \
     'Type=simple' \
     'User=opencode' \
     'WorkingDirectory=/home/opencode/workspace' \
-    'ExecStart=/home/opencode/.local/share/opencode/bin/opencode web --port 3000 --hostname 0.0.0.0' \
+    'ExecStart=/opt/opencode/bin/opencode web --port 3000 --hostname 0.0.0.0' \
     'Restart=always' \
     'RestartSec=5' \
-    'Environment=PATH=/home/opencode/.local/share/opencode/bin:/home/opencode/.local/bin:/home/opencode/.cargo/bin:/home/opencode/.local/share/mise/shims:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin' \
+    'Environment=PATH=/opt/opencode/bin:/home/opencode/.local/bin:/home/opencode/.cargo/bin:/home/opencode/.local/share/mise/shims:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin' \
     '' \
     '[Install]' \
     'WantedBy=multi-user.target' \
@@ -700,7 +700,7 @@ RUN printf '%s\n' \
     '    install -d -m 0755 /run/opencode' \
     '    /usr/local/bin/opencode-broker &' \
     '    # Use runuser to switch to opencode user without password prompt' \
-    '    exec runuser -u opencode -- sh -lc "cd /home/opencode/workspace && /home/opencode/.local/share/opencode/bin/opencode web --port 3000 --hostname 0.0.0.0"' \
+    '    exec runuser -u opencode -- sh -lc "cd /home/opencode/workspace && /opt/opencode/bin/opencode web --port 3000 --hostname 0.0.0.0"' \
     'fi' \
     > /usr/local/bin/entrypoint.sh && chmod +x /usr/local/bin/entrypoint.sh
 

packages/core/src/docker/container.rs

@@ -6,8 +6,8 @@
 use super::dockerfile::{IMAGE_NAME_GHCR, IMAGE_TAG_DEFAULT};
 use super::mount::ParsedMount;
 use super::volume::{
-    MOUNT_APP_DATA, MOUNT_CONFIG, MOUNT_PROJECTS, MOUNT_SESSION, VOLUME_CONFIG, VOLUME_PROJECTS,
-    VOLUME_SESSION,
+    MOUNT_CACHE, MOUNT_CONFIG, MOUNT_PROJECTS, MOUNT_SESSION, MOUNT_STATE, VOLUME_CACHE,
+    VOLUME_CONFIG, VOLUME_PROJECTS, VOLUME_SESSION, VOLUME_STATE,
 };
 use super::{DockerClient, DockerError};
 use bollard::container::{
@@ -117,6 +117,8 @@ pub async fn create_container(
         });
     };
     add_volume_mount(MOUNT_SESSION, VOLUME_SESSION);
+    add_volume_mount(MOUNT_STATE, VOLUME_STATE);
+    add_volume_mount(MOUNT_CACHE, VOLUME_CACHE);
     add_volume_mount(MOUNT_PROJECTS, VOLUME_PROJECTS);
     add_volume_mount(MOUNT_CONFIG, VOLUME_CONFIG);
 
@@ -201,7 +203,16 @@ pub async fn create_container(
     // Build environment variables
     let mut env = env_vars.unwrap_or_default();
     if !has_env_key(&env, "XDG_DATA_HOME") {
-        env.push(format!("XDG_DATA_HOME={MOUNT_APP_DATA}"));
+        env.push("XDG_DATA_HOME=/home/opencode/.local/share".to_string());
+    }
+    if !has_env_key(&env, "XDG_STATE_HOME") {
+        env.push("XDG_STATE_HOME=/home/opencode/.local/state".to_string());
+    }
+    if !has_env_key(&env, "XDG_CONFIG_HOME") {
+        env.push("XDG_CONFIG_HOME=/home/opencode/.config".to_string());
+    }
+    if !has_env_key(&env, "XDG_CACHE_HOME") {
+        env.push("XDG_CACHE_HOME=/home/opencode/.cache".to_string());
     }
     // Add USE_SYSTEMD=1 when Cockpit is enabled to tell entrypoint to use systemd
     if cockpit_enabled_val && !has_env_key(&env, "USE_SYSTEMD") {

packages/core/src/docker/mod.rs

@@ -60,9 +60,9 @@ pub use users::{
 
 // Volume management
 pub use volume::{
-    MOUNT_APP_DATA, MOUNT_CONFIG, MOUNT_PROJECTS, MOUNT_SESSION, VOLUME_CONFIG, VOLUME_NAMES,
-    VOLUME_PROJECTS, VOLUME_SESSION, ensure_volumes_exist, remove_all_volumes, remove_volume,
-    volume_exists,
+    MOUNT_CACHE, MOUNT_CONFIG, MOUNT_PROJECTS, MOUNT_SESSION, MOUNT_STATE, VOLUME_CACHE,
+    VOLUME_CONFIG, VOLUME_NAMES, VOLUME_PROJECTS, VOLUME_SESSION, VOLUME_STATE,
+    ensure_volumes_exist, remove_all_volumes, remove_volume, volume_exists,
 };
 
 // Bind mount parsing and validation

packages/core/src/docker/volume.rs

@@ -11,26 +11,41 @@ use tracing::debug;
 /// Volume name for opencode data
 pub const VOLUME_SESSION: &str = "opencode-data";
 
+/// Volume name for opencode state
+pub const VOLUME_STATE: &str = "opencode-state";
+
+/// Volume name for opencode cache
+pub const VOLUME_CACHE: &str = "opencode-cache";
+
 /// Volume name for project files
 pub const VOLUME_PROJECTS: &str = "opencode-workspace";
 
 /// Volume name for opencode configuration
 pub const VOLUME_CONFIG: &str = "opencode-config";
 
 /// All volume names as array for iteration
-pub const VOLUME_NAMES: [&str; 3] = [VOLUME_SESSION, VOLUME_PROJECTS, VOLUME_CONFIG];
+pub const VOLUME_NAMES: [&str; 5] = [
+    VOLUME_SESSION,
+    VOLUME_STATE,
+    VOLUME_CACHE,
+    VOLUME_PROJECTS,
+    VOLUME_CONFIG,
+];
 
 /// Mount point for opencode data inside container
-pub const MOUNT_SESSION: &str = "/home/opencode/.local/share";
+pub const MOUNT_SESSION: &str = "/home/opencode/.local/share/opencode";
+
+/// Mount point for opencode state inside container
+pub const MOUNT_STATE: &str = "/home/opencode/.local/state/opencode";
 
-/// Mount point for opencode app data inside container (XDG_DATA_HOME)
-pub const MOUNT_APP_DATA: &str = "/home/opencode/.local/share/opencode-cloud";
+/// Mount point for opencode cache inside container
+pub const MOUNT_CACHE: &str = "/home/opencode/.cache/opencode";
 
 /// Mount point for project files inside container
 pub const MOUNT_PROJECTS: &str = "/home/opencode/workspace";
 
 /// Mount point for configuration inside container
-pub const MOUNT_CONFIG: &str = "/home/opencode/.config";
+pub const MOUNT_CONFIG: &str = "/home/opencode/.config/opencode";
 
 /// Ensure all required volumes exist
 ///
@@ -126,23 +141,28 @@ mod tests {
     #[test]
     fn volume_constants_are_correct() {
         assert_eq!(VOLUME_SESSION, "opencode-data");
+        assert_eq!(VOLUME_STATE, "opencode-state");
+        assert_eq!(VOLUME_CACHE, "opencode-cache");
         assert_eq!(VOLUME_PROJECTS, "opencode-workspace");
         assert_eq!(VOLUME_CONFIG, "opencode-config");
     }
 
     #[test]
     fn volume_names_array_has_all_volumes() {
-        assert_eq!(VOLUME_NAMES.len(), 3);
+        assert_eq!(VOLUME_NAMES.len(), 5);
         assert!(VOLUME_NAMES.contains(&VOLUME_SESSION));
+        assert!(VOLUME_NAMES.contains(&VOLUME_STATE));
+        assert!(VOLUME_NAMES.contains(&VOLUME_CACHE));
         assert!(VOLUME_NAMES.contains(&VOLUME_PROJECTS));
         assert!(VOLUME_NAMES.contains(&VOLUME_CONFIG));
     }
 
     #[test]
     fn mount_points_are_correct() {
-        assert_eq!(MOUNT_SESSION, "/home/opencode/.local/share");
-        assert_eq!(MOUNT_APP_DATA, "/home/opencode/.local/share/opencode-cloud");
+        assert_eq!(MOUNT_SESSION, "/home/opencode/.local/share/opencode");
+        assert_eq!(MOUNT_STATE, "/home/opencode/.local/state/opencode");
+        assert_eq!(MOUNT_CACHE, "/home/opencode/.cache/opencode");
         assert_eq!(MOUNT_PROJECTS, "/home/opencode/workspace");
-        assert_eq!(MOUNT_CONFIG, "/home/opencode/.config");
+        assert_eq!(MOUNT_CONFIG, "/home/opencode/.config/opencode");
     }
 }