feat(paths): follow XDG Base Directory Specification

cmd/root/a2a.go

@@ -1,14 +1,11 @@
 package root
 
 import (
-	"path/filepath"
-
 	"github.com/spf13/cobra"
 
 	"github.com/docker/docker-agent/pkg/a2a"
 	"github.com/docker/docker-agent/pkg/cli"
 	"github.com/docker/docker-agent/pkg/config"
-	"github.com/docker/docker-agent/pkg/paths"
 	"github.com/docker/docker-agent/pkg/telemetry"
 )
 
@@ -34,7 +31,7 @@ func newA2ACmd() *cobra.Command {
 
 	cmd.PersistentFlags().StringVarP(&flags.agentName, "agent", "a", "", "Name of the agent to run (defaults to the team's first agent)")
 	cmd.PersistentFlags().StringVarP(&flags.listenAddr, "listen", "l", "127.0.0.1:8082", "Address to listen on")
-	cmd.PersistentFlags().StringVarP(&flags.sessionDB, "session-db", "s", filepath.Join(paths.GetHomeDir(), ".cagent", "session.db"), "Path to the session database")
+	cmd.PersistentFlags().StringVarP(&flags.sessionDB, "session-db", "s", "", "Path to the session database (default: <data-dir>/session.db)")
 	addRuntimeConfigFlags(cmd, &flags.runConfig)
 
 	return cmd
@@ -57,5 +54,5 @@ func (f *a2aFlags) runA2ACommand(cmd *cobra.Command, args []string) (commandErr
 	defer cleanup()
 
 	out.Println("Listening on", ln.Addr().String())
-	return a2a.Run(ctx, agentFilename, f.agentName, f.sessionDB, &f.runConfig, ln)
+	return a2a.Run(ctx, agentFilename, f.agentName, defaultSessionDB(f.sessionDB), &f.runConfig, ln)
 }

cmd/root/acp.go

@@ -1,14 +1,11 @@
 package root
 
 import (
-	"path/filepath"
-
 	"github.com/spf13/cobra"
 
 	"github.com/docker/docker-agent/pkg/acp"
 	"github.com/docker/docker-agent/pkg/config"
 	pathx "github.com/docker/docker-agent/pkg/path"
-	"github.com/docker/docker-agent/pkg/paths"
 	"github.com/docker/docker-agent/pkg/telemetry"
 )
 
@@ -31,7 +28,7 @@ func newACPCmd() *cobra.Command {
 		RunE: flags.runACPCommand,
 	}
 
-	cmd.Flags().StringVarP(&flags.sessionDB, "session-db", "s", filepath.Join(paths.GetHomeDir(), ".cagent", "session.db"), "Path to the session database")
+	cmd.Flags().StringVarP(&flags.sessionDB, "session-db", "s", "", "Path to the session database (default: <data-dir>/session.db)")
 	addRuntimeConfigFlags(cmd, &flags.runConfig)
 
 	return cmd
@@ -47,7 +44,7 @@ func (f *acpFlags) runACPCommand(cmd *cobra.Command, args []string) (commandErr
 	agentFilename := args[0]
 
 	// Expand tilde in session database path
-	sessionDB, err := pathx.ExpandHomeDir(f.sessionDB)
+	sessionDB, err := pathx.ExpandHomeDir(defaultSessionDB(f.sessionDB))
 	if err != nil {
 		return err
 	}

cmd/root/payload.go

@@ -22,7 +22,7 @@ func (f *runExecFlags) createSessionRequest(workingDir string) runtime.CreateSes
 		AgentName:         f.agentName,
 		ToolsApproved:     f.autoApprove,
 		HideToolResults:   f.hideToolResults,
-		SessionDB:         f.sessionDB,
+		SessionDB:         defaultSessionDB(f.sessionDB),
 		ResumeSessionID:   f.sessionID,
 		SnapshotsEnabled:  f.snapshotsEnabled,
 		GlobalPermissions: f.globalPermissions,

cmd/root/root.go

@@ -58,6 +58,10 @@ func NewRootCmd() *cobra.Command {
 				paths.SetDataDir(dir)
 			}
 
+			// Relocate legacy ~/.cagent and ~/.config/cagent to the
+			// XDG/native dirs. After the overrides above so they're honoured.
+			paths.MigrateLegacy()
+
 			// Set the version for automatic telemetry initialization
 			telemetry.SetGlobalTelemetryVersion(version.Version)
 
@@ -143,10 +147,10 @@ We collect anonymous usage data to help improve docker agent. To disable:
 	// Add persistent debug flag available to all commands
 	cmd.PersistentFlags().BoolVarP(&flags.debugMode, "debug", "d", false, "Enable debug logging")
 	cmd.PersistentFlags().BoolVarP(&flags.enableOtel, "otel", "o", false, "Enable OpenTelemetry tracing")
-	cmd.PersistentFlags().StringVar(&flags.logFilePath, "log-file", "", "Path to debug log file (default: ~/.cagent/cagent.debug.log; only used with --debug)")
-	cmd.PersistentFlags().StringVar(&flags.cacheDir, "cache-dir", "", "Override the cache directory (default: ~/Library/Caches/cagent on macOS)")
-	cmd.PersistentFlags().StringVar(&flags.configDir, "config-dir", "", "Override the config directory (default: ~/.config/cagent)")
-	cmd.PersistentFlags().StringVar(&flags.dataDir, "data-dir", "", "Override the data directory (default: ~/.cagent)")
+	cmd.PersistentFlags().StringVar(&flags.logFilePath, "log-file", "", "Path to debug log file (default: <data-dir>/cagent.debug.log; only used with --debug)")
+	cmd.PersistentFlags().StringVar(&flags.cacheDir, "cache-dir", "", "Override the cache directory (default: $XDG_CACHE_HOME/cagent, or the OS-native cache dir)")
+	cmd.PersistentFlags().StringVar(&flags.configDir, "config-dir", "", "Override the config directory (default: $XDG_CONFIG_HOME/cagent, or the OS-native config dir)")
+	cmd.PersistentFlags().StringVar(&flags.dataDir, "data-dir", "", "Override the data directory (default: $XDG_DATA_HOME/cagent, or the OS-native data dir)")
 
 	// Define groups
 	cmd.AddGroup(

cmd/root/run.go

@@ -133,6 +133,16 @@ func newRunCmd() *cobra.Command {
 	return cmd
 }
 
+// defaultSessionDB returns the explicit --session-db value, or
+// <data-dir>/session.db. Resolved at run time (not flag-registration time) so
+// --data-dir and [paths.SetRoot] are honoured.
+func defaultSessionDB(explicit string) string {
+	if explicit != "" {
+		return explicit
+	}
+	return filepath.Join(paths.GetDataDir(), "session.db")
+}
+
 func addRunOrExecFlags(cmd *cobra.Command, flags *runExecFlags) {
 	cmd.PersistentFlags().StringVarP(&flags.agentName, "agent", "a", "", "Name of the agent to run (defaults to the team's first agent)")
 	cmd.PersistentFlags().BoolVar(&flags.autoApprove, "yolo", false, "Automatically approve all tool calls without prompting")
@@ -142,7 +152,7 @@ func addRunOrExecFlags(cmd *cobra.Command, flags *runExecFlags) {
 	cmd.PersistentFlags().StringArrayVar(&flags.modelOverrides, "model", nil, "Override agent model: [agent=]provider/model (repeatable)")
 	cmd.PersistentFlags().BoolVar(&flags.dryRun, "dry-run", false, "Initialize the agent without executing anything")
 	cmd.PersistentFlags().StringVar(&flags.remoteAddress, "remote", "", "Use remote runtime with specified address")
-	cmd.PersistentFlags().StringVarP(&flags.sessionDB, "session-db", "s", filepath.Join(paths.GetHomeDir(), ".cagent", "session.db"), "Path to the session database")
+	cmd.PersistentFlags().StringVarP(&flags.sessionDB, "session-db", "s", "", "Path to the session database (default: <data-dir>/session.db)")
 	cmd.PersistentFlags().StringVar(&flags.sessionID, "session", "", "Continue from a previous session by ID or relative offset (e.g., -1 for last session). An explicit ID that does not exist yet is created with that ID.")
 	cmd.PersistentFlags().StringVar(&flags.fakeResponses, "fake", "", "Replay AI responses from cassette file (for testing)")
 	cmd.PersistentFlags().IntVar(&flags.fakeStreamDelay, "fake-stream", 0, "Simulate streaming with delay in ms between chunks (default 15ms if no value given)")

cmd/root/sandbox.go

@@ -260,6 +260,10 @@ func dockerAgentArgs(cmd *cobra.Command, args []string, configDir string) []stri
 		"sbx":        true,
 		"config-dir": true,
 		"no-kit":     true,
+		// Only the config dir is bind-mounted into the sandbox. Forwarding a
+		// host data/cache path would point the inner agent at a missing mount.
+		"data-dir":  true,
+		"cache-dir": true,
 	}
 
 	var dockerAgentArgs []string

cmd/root/session_db_test.go

@@ -0,0 +1,26 @@
+package root
+
+import (
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"github.com/docker/docker-agent/pkg/paths"
+)
+
+// TestDefaultSessionDB checks the session DB path is resolved lazily from the
+// data dir so --data-dir and SetRoot are honoured (regression: the old flag
+// default baked ~/.cagent/session.db at registration time, splitting sessions).
+func TestDefaultSessionDB(t *testing.T) {
+	// Mutates the process-global data-dir override; cannot run in parallel.
+	dataDir := t.TempDir()
+	paths.SetDataDir(dataDir)
+	t.Cleanup(func() { paths.SetDataDir("") })
+
+	assert.Equal(t, filepath.Join(dataDir, "session.db"), defaultSessionDB(""),
+		"empty value must resolve to <data-dir>/session.db after an override")
+
+	assert.Equal(t, "/explicit/path.db", defaultSessionDB("/explicit/path.db"),
+		"an explicit --session-db value must be returned unchanged")
+}

docs/community/opentelemetry/index.md

@@ -98,7 +98,7 @@ docker agent run agent.yaml --otel
 
 ## Inspecting traces locally
 
-Use `--debug` to print telemetry activity to the debug log (`~/.cagent/cagent.debug.log` by default) without standing up a backend:
+Use `--debug` to print telemetry activity to the debug log (`<data-dir>/cagent.debug.log` by default) without standing up a backend:
 
 ```bash
 docker agent run agent.yaml --otel --debug

docs/community/troubleshooting/index.md

@@ -52,7 +52,7 @@ agents:
 The first step for any issue is enabling debug logging. This provides detailed information about what docker-agent is doing internally.
 
 ```bash
-# Enable debug logging (writes to ~/.cagent/cagent.debug.log)
+# Enable debug logging (writes to <data-dir>/cagent.debug.log)
 $ docker agent run config.yaml --debug
 
 # Write debug logs to a custom file
@@ -69,6 +69,10 @@ $ docker agent run config.yaml --otel
 
 </div>
 
+### Where docker-agent stores files
+
+State moved out of `~/.cagent` (data) into the XDG data directory (`~/.local/share/cagent` on Linux; the OS-native data dir on macOS and Windows). On first run docker-agent automatically relocates existing `~/.cagent` and `~/.config/cagent` contents to the new locations. The `--data-dir`, `--config-dir`, and `--cache-dir` flags and the `XDG_*` environment variables override these defaults.
+
 ## Agent Not Responding
 
 ### API keys not set

docs/configuration/overview/index.md

@@ -193,7 +193,7 @@ API keys and secrets are read from environment variables — never stored in con
 | Variable              | Description                                                     |
 | --------------------- | --------------------------------------------------------------- |
 | `DOCKER_AGENT_AUTO_INSTALL` | Set to `false` to disable automatic tool installation           |
-| `DOCKER_AGENT_TOOLS_DIR`    | Override the base directory for installed tools (default: `~/.cagent/tools/`) |
+| `DOCKER_AGENT_TOOLS_DIR`    | Override the base directory for installed tools (default: `<data-dir>/tools/`) |
 
 **Runtime overrides:**
 

docs/configuration/tools/index.md

@@ -136,7 +136,7 @@ When configuring MCP or LSP tools that require a binary command, docker agent ca
 ### How It Works
 
 1. When a toolset with a `command` is loaded, docker agent checks if the command is available in your `PATH`
-2. If not found, it checks the docker agent tools directory (`~/.cagent/tools/bin/`)
+2. If not found, it checks the docker agent tools directory (`~/.local/share/cagent/tools/bin/`)
 3. If still not found, it looks up the command in the aqua registry and installs it automatically
 
 ### Explicit Package Reference
@@ -202,10 +202,10 @@ export DOCKER_AGENT_AUTO_INSTALL=false
 | Variable                     | Default            | Description                                      |
 | ---------------------------- | ------------------ | ------------------------------------------------ |
 | `DOCKER_AGENT_AUTO_INSTALL`  | (enabled)          | Set to `false` to disable all auto-installation  |
-| `DOCKER_AGENT_TOOLS_DIR`     | `~/.cagent/tools/` | Base directory for installed tools               |
+| `DOCKER_AGENT_TOOLS_DIR`     | `<data-dir>/tools/` | Base directory for installed tools               |
 | `GITHUB_TOKEN`               | —                  | GitHub token to raise API rate limits (optional) |
 
-Installed binaries are placed in `~/.cagent/tools/bin/` and cached so they are only downloaded once.
+Installed binaries are placed in `~/.local/share/cagent/tools/bin/` and cached so they are only downloaded once.
 
 <div class="callout callout-tip" markdown="1">
 <div class="callout-title">Tip

docs/features/acp/index.md

@@ -69,7 +69,7 @@ docker agent serve acp <agent-file>|<registry-ref> [flags]
 
 | Flag                              | Default                | Description                                                                                                          |
 | --------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `-s, --session-db <path>`         | `~/.cagent/session.db` | Path to the SQLite session database.                                                                                 |
+| `-s, --session-db <path>`         | `<data-dir>/session.db` | Path to the SQLite session database.                                                                                 |
 | `--working-dir <path>`            | current dir            | Working directory the agent runs in.                                                                                 |
 | `--env-from-file <file>`          | (none)                 | Load additional environment variables from a `.env` file (repeatable).                                               |
 | `--models-gateway <url>`          | (none)                 | Route all provider traffic through a models gateway URL.                                                             |

docs/features/cli/index.md

@@ -31,7 +31,7 @@ $ docker agent run [config] [message...] [flags]
 | `--yolo`                                | Auto-approve all tool calls                                                                                                               |
 | `--model <ref>`                         | Override model(s). Use `provider/model` for all agents, or `agent=provider/model` for specific agents. Comma-separate multiple overrides. |
 | `--session <id>`                        | Resume a previous session. Supports relative refs (`-1` = last, `-2` = second to last). An explicit ID that does not exist yet is created with that ID, so a supervisor can own the session ID upfront and reuse it across runs. |
-| `-s, --session-db <path>`               | Path to the SQLite session database (default: `~/.cagent/session.db`)                                                                     |
+| `-s, --session-db <path>`               | Path to the SQLite session database (default: `<data-dir>/session.db`)                                                                     |
 | `--session-read-only`                   | Open the TUI in read-only mode: conversation history is displayed but no new messages can be sent to the LLM. Cannot be used with `--exec`. |
 | `--prompt-file <path>`                  | Include file contents as additional system context (repeatable)                                                                           |
 | `--attach <path>`                       | Attach an image file to the initial message                                                                                               |
@@ -294,7 +294,7 @@ $ docker agent serve acp <config> [flags]
 
 | Flag                      | Default                     | Description                                       |
 | ------------------------- | --------------------------- | ------------------------------------------------- |
-| `-s, --session-db <path>` | `~/.cagent/session.db`      | Path to the SQLite session database.              |
+| `-s, --session-db <path>` | `<data-dir>/session.db`      | Path to the SQLite session database.              |
 
 All [runtime configuration flags](#runtime-configuration-flags) are also accepted.
 
@@ -521,14 +521,16 @@ These flags are available on every `docker agent` command:
 
 | Flag                      | Description                                                                            |
 | ------------------------- | -------------------------------------------------------------------------------------- |
-| `-d, --debug`             | Enable debug logging (default location: `~/.cagent/cagent.debug.log`)                  |
+| `-d, --debug`             | Enable debug logging (default location: `<data-dir>/cagent.debug.log`)                  |
 | `--log-file <path>`       | Custom debug log location (only used with `--debug`)                                   |
 | `-o, --otel`              | Enable OpenTelemetry observability: traces, metrics, and logs. Requires `OTEL_EXPORTER_OTLP_ENDPOINT` to export to a collector. |
 | `--cache-dir <path>`      | Override the cache directory (default: `~/Library/Caches/cagent` on macOS)             |
-| `--config-dir <path>`     | Override the config directory (default: `~/.config/cagent`)                            |
-| `--data-dir <path>`       | Override the data directory (default: `~/.cagent`)                                     |
+| `--config-dir <path>`     | Override the config directory (default: `$XDG_CONFIG_HOME/cagent (or OS-native config dir)`)                            |
+| `--data-dir <path>`       | Override the data directory (default: `$XDG_DATA_HOME/cagent (or OS-native data dir)`)                                     |
 | `--help`                  | Show help for any command                                                              |
 
+docker-agent follows the XDG Base Directory Specification: set `XDG_DATA_HOME`/`XDG_CONFIG_HOME`/`XDG_CACHE_HOME` to relocate state; otherwise the OS-native directories are used.
+
 ### OpenTelemetry environment variables
 
 When `--otel` is enabled, the standard [OTel SDK env vars](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/) are honored (`OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_RESOURCE_ATTRIBUTES`, etc.). Two additional docker-agent-specific variables control GenAI instrumentation:

docs/features/snapshots/index.md

@@ -86,7 +86,7 @@ when snapshots are turned off.
 
 - **Shadow repository.** The first time a snapshot is taken for a worktree,
   docker-agent initializes a separate shadow git directory under the data
-  directory (`~/.cagent/snapshot/...` by default), keyed by a hash of the
+  directory (`~/.local/share/cagent/snapshot/...` by default), keyed by a hash of the
   worktree path. The shadow repo stores tree objects only — it never writes
   commits and never touches your source repository's `.git`.
 - **Ignore rules are mirrored.** Before each capture, the source repository's

docs/features/tui/index.md

@@ -334,10 +334,10 @@ Customize the TUI appearance with built-in or custom themes:
 
 ### Custom Themes
 
-Create theme files in `~/.cagent/themes/` as YAML. Theme files are **partial overrides** — you only need to specify the colors you want to change. Any omitted keys fall back to the built-in default theme values.
+Create theme files in `~/.local/share/cagent/themes/` as YAML. Theme files are **partial overrides** — you only need to specify the colors you want to change. Any omitted keys fall back to the built-in default theme values.
 
 ```yaml
-# ~/.cagent/themes/my-theme.yaml
+# ~/.local/share/cagent/themes/my-theme.yaml
 name: "My Custom Theme"
 
 colors:
@@ -380,7 +380,7 @@ markdown:
 
 ```yaml
 settings:
-  theme: my-theme # References ~/.cagent/themes/my-theme.yaml
+  theme: my-theme # References ~/.local/share/cagent/themes/my-theme.yaml
 ```
 
 **At launch:** Pass `--theme <name>` to `docker agent run` to preselect a theme for that session. This overrides `settings.theme` in your config but is not saved. Invalid theme names print an error at startup listing the available options. Has no effect in `--exec` mode.
@@ -397,7 +397,7 @@ settings:
 <div class="callout callout-warning" markdown="1">
 <div class="callout-title">Partial overrides
 </div>
-  <p>All user themes are applied on top of the <code>default</code> theme. If you want to customize a built-in theme (e.g., <code>dracula</code>), copy its full YAML from the <a href="https://github.com/docker/docker-agent/tree/main/pkg/tui/styles/themes">built-in themes on GitHub</a> into <code>~/.cagent/themes/</code> and edit the copy. Otherwise, omitted values will use <code>default</code> colors, not the original theme's colors.</p>
+  <p>All user themes are applied on top of the <code>default</code> theme. If you want to customize a built-in theme (e.g., <code>dracula</code>), copy its full YAML from the <a href="https://github.com/docker/docker-agent/tree/main/pkg/tui/styles/themes">built-in themes on GitHub</a> into <code>~/.local/share/cagent/themes/</code> and edit the copy. Otherwise, omitted values will use <code>default</code> colors, not the original theme's colors.</p>
 
 </div>