Add copilotHome option for configurable data directory (#1191)

patniko · web-flow · commit 662f270cab87 · 2026-05-04T12:59:42.000+01:00
diff --git a/dotnet/README.md b/dotnet/README.md
@@ -75,6 +75,7 @@ new CopilotClient(CopilotClientOptions? options = null)
 - `LogLevel` - Log level (default: "info")
 - `AutoStart` - Auto-start server (default: true)
 - `Cwd` - Working directory for the CLI process
+- `CopilotHome` - Base directory for Copilot data (session state, config, etc.). Sets `COPILOT_HOME` on the spawned CLI process. When not set, the CLI defaults to `~/.copilot`. Useful in restricted environments where only specific directories are writable. Ignored when using `CliUrl`.
 - `Environment` - Environment variables to pass to the CLI process
 - `Logger` - `ILogger` instance for SDK logging
 - `GitHubToken` - GitHub token for authentication. When provided, takes priority over other auth methods.
diff --git a/dotnet/src/Client.cs b/dotnet/src/Client.cs
@@ -1261,6 +1261,11 @@ private async Task VerifyProtocolVersionAsync(Connection connection, Cancellatio
             startInfo.Environment["COPILOT_CONNECTION_TOKEN"] = connectionToken;
         }
 
+        if (!string.IsNullOrEmpty(options.CopilotHome))
+        {
+            startInfo.Environment["COPILOT_HOME"] = options.CopilotHome;
+        }
+
         // Set telemetry environment variables if configured
         if (options.Telemetry is { } telemetry)
         {
diff --git a/dotnet/src/Types.cs b/dotnet/src/Types.cs
@@ -59,6 +59,7 @@ protected CopilotClientOptions(CopilotClientOptions? other)
         CliPath = other.CliPath;
         CliUrl = other.CliUrl;
         Cwd = other.Cwd;
+        CopilotHome = other.CopilotHome;
         Environment = other.Environment;
         GitHubToken = other.GitHubToken;
         Logger = other.Logger;
@@ -86,6 +87,14 @@ protected CopilotClientOptions(CopilotClientOptions? other)
     /// </summary>
     public string? Cwd { get; set; }
     /// <summary>
+    /// Base directory for Copilot data (session state, config, etc.).
+    /// Sets the <c>COPILOT_HOME</c> environment variable on the spawned CLI process.
+    /// When <see langword="null"/>, the CLI defaults to <c>~/.copilot</c>.
+    /// This option is only used when the SDK spawns the CLI process; it is ignored
+    /// when connecting to an external server via <see cref="CliUrl"/>.
+    /// </summary>
+    public string? CopilotHome { get; set; }
+    /// <summary>
     /// Port number for the CLI server when not using stdio transport.
     /// </summary>
     public int Port { get; set; }
diff --git a/dotnet/test/E2E/ClientOptionsE2ETests.cs b/dotnet/test/E2E/ClientOptionsE2ETests.cs
@@ -93,13 +93,19 @@ public async Task Should_Propagate_Process_Options_To_Spawned_Cli()
         var cliPath = Path.Join(Ctx.WorkDir, $"fake-cli-{Guid.NewGuid():N}.js");
         var capturePath = Path.Join(Ctx.WorkDir, $"fake-cli-capture-{Guid.NewGuid():N}.json");
         var telemetryPath = Path.Join(Ctx.WorkDir, "telemetry.jsonl");
+        var copilotHomeFromEnv = Path.Join(Ctx.WorkDir, "copilot-home-from-env");
+        var copilotHomeFromOption = Path.Join(Ctx.WorkDir, "copilot-home-from-option");
+        var clientEnv = Ctx.GetEnvironment().ToDictionary(pair => pair.Key, pair => pair.Value);
+        clientEnv["COPILOT_HOME"] = copilotHomeFromEnv;
         await File.WriteAllTextAsync(cliPath, FakeStdioCliScript);
 
         await using var client = Ctx.CreateClient(options: new CopilotClientOptions
         {
             AutoStart = false,
             CliPath = cliPath,
             CliArgs = ["--capture-file", capturePath],
+            CopilotHome = copilotHomeFromOption,
+            Environment = clientEnv,
             GitHubToken = "process-option-token",
             LogLevel = "debug",
             SessionIdleTimeoutSeconds = 17,
@@ -119,7 +125,7 @@ public async Task Should_Propagate_Process_Options_To_Spawned_Cli()
         using var capture = JsonDocument.Parse(await File.ReadAllTextAsync(capturePath));
         var root = capture.RootElement;
         var args = root.GetProperty("args").EnumerateArray().Select(e => e.GetString()).ToArray();
-        var env = root.GetProperty("env");
+        var capturedEnv = root.GetProperty("env");
 
         AssertArgumentValue(args, "--log-level", "debug");
         Assert.Contains("--stdio", args);
@@ -128,13 +134,14 @@ public async Task Should_Propagate_Process_Options_To_Spawned_Cli()
         AssertArgumentValue(args, "--session-idle-timeout", "17");
         Assert.Equal(Path.GetFullPath(Ctx.WorkDir), root.GetProperty("cwd").GetString());
 
-        Assert.Equal("process-option-token", env.GetProperty("COPILOT_SDK_AUTH_TOKEN").GetString());
-        Assert.Equal("true", env.GetProperty("COPILOT_OTEL_ENABLED").GetString());
-        Assert.Equal("http://127.0.0.1:4318", env.GetProperty("OTEL_EXPORTER_OTLP_ENDPOINT").GetString());
-        Assert.Equal(telemetryPath, env.GetProperty("COPILOT_OTEL_FILE_EXPORTER_PATH").GetString());
-        Assert.Equal("file", env.GetProperty("COPILOT_OTEL_EXPORTER_TYPE").GetString());
-        Assert.Equal("dotnet-sdk-e2e", env.GetProperty("COPILOT_OTEL_SOURCE_NAME").GetString());
-        Assert.Equal("true", env.GetProperty("OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT").GetString());
+        Assert.Equal(copilotHomeFromOption, capturedEnv.GetProperty("COPILOT_HOME").GetString());
+        Assert.Equal("process-option-token", capturedEnv.GetProperty("COPILOT_SDK_AUTH_TOKEN").GetString());
+        Assert.Equal("true", capturedEnv.GetProperty("COPILOT_OTEL_ENABLED").GetString());
+        Assert.Equal("http://127.0.0.1:4318", capturedEnv.GetProperty("OTEL_EXPORTER_OTLP_ENDPOINT").GetString());
+        Assert.Equal(telemetryPath, capturedEnv.GetProperty("COPILOT_OTEL_FILE_EXPORTER_PATH").GetString());
+        Assert.Equal("file", capturedEnv.GetProperty("COPILOT_OTEL_EXPORTER_TYPE").GetString());
+        Assert.Equal("dotnet-sdk-e2e", capturedEnv.GetProperty("COPILOT_OTEL_SOURCE_NAME").GetString());
+        Assert.Equal("true", capturedEnv.GetProperty("OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT").GetString());
 
         var session = await client.CreateSessionAsync(new SessionConfig
         {
@@ -281,6 +288,7 @@ function saveCapture() {
             cwd: process.cwd(),
             requests,
             env: {
+              COPILOT_HOME: process.env.COPILOT_HOME,
               COPILOT_SDK_AUTH_TOKEN: process.env.COPILOT_SDK_AUTH_TOKEN,
               COPILOT_OTEL_ENABLED: process.env.COPILOT_OTEL_ENABLED,
               OTEL_EXPORTER_OTLP_ENDPOINT: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
diff --git a/dotnet/test/Unit/CloneTests.cs b/dotnet/test/Unit/CloneTests.cs
@@ -26,6 +26,7 @@ public void CopilotClientOptions_Clone_CopiesAllProperties()
             Environment = new Dictionary<string, string> { ["KEY"] = "value" },
             GitHubToken = "ghp_test",
             UseLoggedInUser = false,
+            CopilotHome = "/custom/copilot/home",
             SessionIdleTimeoutSeconds = 600,
         };
 
@@ -43,6 +44,7 @@ public void CopilotClientOptions_Clone_CopiesAllProperties()
         Assert.Equal(original.Environment, clone.Environment);
         Assert.Equal(original.GitHubToken, clone.GitHubToken);
         Assert.Equal(original.UseLoggedInUser, clone.UseLoggedInUser);
+        Assert.Equal(original.CopilotHome, clone.CopilotHome);
         Assert.Equal(original.SessionIdleTimeoutSeconds, clone.SessionIdleTimeoutSeconds);
     }
 
diff --git a/go/README.md b/go/README.md
@@ -133,6 +133,7 @@ Event types: `SessionLifecycleCreated`, `SessionLifecycleDeleted`, `SessionLifec
 - `CLIPath` (string): Path to CLI executable (default: "copilot" or `COPILOT_CLI_PATH` env var)
 - `CLIUrl` (string): URL of existing CLI server (e.g., `"localhost:8080"`, `"http://127.0.0.1:9000"`, or just `"8080"`). When provided, the client will not spawn a CLI process.
 - `Cwd` (string): Working directory for CLI process
+- `CopilotHome` (string): Base directory for Copilot data (session state, config, etc.). Sets `COPILOT_HOME` on the spawned CLI process. When empty, the CLI defaults to `~/.copilot`. Useful in restricted environments where only specific directories are writable. Ignored when using `CLIUrl`. This does **not** affect where the Go SDK extracts the embedded CLI binary; use `embeddedcli.Config.Dir` for the extraction/cache location. You can vary `CopilotHome` per client independently of the shared extracted binary location.
 - `Port` (int): Server port for TCP mode (default: 0 for random)
 - `UseStdio` (bool): Use stdio transport instead of TCP (default: true)
 - `LogLevel` (string): Log level (default: "info")
diff --git a/go/client.go b/go/client.go
@@ -231,6 +231,9 @@ func NewClient(options *ClientOptions) *Client {
 		if options.Telemetry != nil {
 			opts.Telemetry = options.Telemetry
 		}
+		if options.CopilotHome != "" {
+			opts.CopilotHome = options.CopilotHome
+		}
 		opts.SessionIdleTimeoutSeconds = options.SessionIdleTimeoutSeconds
 	}
 
@@ -270,6 +273,19 @@ func getEnvValue(env []string, key string) string {
 	return ""
 }
 
+// setEnvValue returns a copy of env with all existing entries for key removed and
+// a single trailing KEY=VALUE entry added so SDK-managed values win deterministically.
+func setEnvValue(env []string, key string, value string) []string {
+	prefix := key + "="
+	filtered := make([]string, 0, len(env)+1)
+	for _, entry := range env {
+		if !strings.HasPrefix(entry, prefix) {
+			filtered = append(filtered, entry)
+		}
+	}
+	return append(filtered, key+"="+value)
+}
+
 // parseCliUrl parses a CLI URL into host and port components.
 //
 // Supports formats: "host:port", "http://host:port", "https://host:port", or just "port".
@@ -1462,37 +1478,40 @@ func (c *Client) startCLIServer(ctx context.Context) error {
 		c.process.Dir = c.options.Cwd
 	}
 
-	// Add auth token if needed.
-	c.process.Env = c.options.Env
+	c.process.Env = append([]string{}, c.options.Env...)
 	if c.options.GitHubToken != "" {
-		c.process.Env = append(c.process.Env, "COPILOT_SDK_AUTH_TOKEN="+c.options.GitHubToken)
+		c.process.Env = setEnvValue(c.process.Env, "COPILOT_SDK_AUTH_TOKEN", c.options.GitHubToken)
 	}
 
 	if c.effectiveConnectionToken != "" {
-		c.process.Env = append(c.process.Env, "COPILOT_CONNECTION_TOKEN="+c.effectiveConnectionToken)
+		c.process.Env = setEnvValue(c.process.Env, "COPILOT_CONNECTION_TOKEN", c.effectiveConnectionToken)
+	}
+
+	if c.options.CopilotHome != "" {
+		c.process.Env = setEnvValue(c.process.Env, "COPILOT_HOME", c.options.CopilotHome)
 	}
 
 	if c.options.Telemetry != nil {
 		t := c.options.Telemetry
-		c.process.Env = append(c.process.Env, "COPILOT_OTEL_ENABLED=true")
+		c.process.Env = setEnvValue(c.process.Env, "COPILOT_OTEL_ENABLED", "true")
 		if t.OTLPEndpoint != "" {
-			c.process.Env = append(c.process.Env, "OTEL_EXPORTER_OTLP_ENDPOINT="+t.OTLPEndpoint)
+			c.process.Env = setEnvValue(c.process.Env, "OTEL_EXPORTER_OTLP_ENDPOINT", t.OTLPEndpoint)
 		}
 		if t.FilePath != "" {
-			c.process.Env = append(c.process.Env, "COPILOT_OTEL_FILE_EXPORTER_PATH="+t.FilePath)
+			c.process.Env = setEnvValue(c.process.Env, "COPILOT_OTEL_FILE_EXPORTER_PATH", t.FilePath)
 		}
 		if t.ExporterType != "" {
-			c.process.Env = append(c.process.Env, "COPILOT_OTEL_EXPORTER_TYPE="+t.ExporterType)
+			c.process.Env = setEnvValue(c.process.Env, "COPILOT_OTEL_EXPORTER_TYPE", t.ExporterType)
 		}
 		if t.SourceName != "" {
-			c.process.Env = append(c.process.Env, "COPILOT_OTEL_SOURCE_NAME="+t.SourceName)
+			c.process.Env = setEnvValue(c.process.Env, "COPILOT_OTEL_SOURCE_NAME", t.SourceName)
 		}
 		if t.CaptureContent != nil {
 			val := "false"
 			if *t.CaptureContent {
 				val = "true"
 			}
-			c.process.Env = append(c.process.Env, "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT="+val)
+			c.process.Env = setEnvValue(c.process.Env, "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT", val)
 		}
 	}
 
diff --git a/go/client_test.go b/go/client_test.go
@@ -344,6 +344,26 @@ func TestClient_AuthOptions(t *testing.T) {
 	})
 }
 
+func TestClient_CopilotHome(t *testing.T) {
+	t.Run("should accept CopilotHome option", func(t *testing.T) {
+		client := NewClient(&ClientOptions{
+			CopilotHome: "/custom/copilot/home",
+		})
+
+		if client.options.CopilotHome != "/custom/copilot/home" {
+			t.Errorf("Expected CopilotHome to be '/custom/copilot/home', got %q", client.options.CopilotHome)
+		}
+	})
+
+	t.Run("should default CopilotHome to empty string", func(t *testing.T) {
+		client := NewClient(&ClientOptions{})
+
+		if client.options.CopilotHome != "" {
+			t.Errorf("Expected CopilotHome to be empty, got %q", client.options.CopilotHome)
+		}
+	})
+}
+
 func TestClient_EnvOptions(t *testing.T) {
 	t.Run("should store custom environment variables", func(t *testing.T) {
 		client := NewClient(&ClientOptions{
diff --git a/go/internal/e2e/client_options_e2e_test.go b/go/internal/e2e/client_options_e2e_test.go
@@ -141,6 +141,9 @@ func TestClientOptionsE2E(t *testing.T) {
 			opts.AutoStart = copilot.Bool(false)
 			opts.CLIPath = cliPath
 			opts.CLIArgs = []string{"--capture-file", capturePath}
+			opts.CopilotHome = filepath.Join(ctx.WorkDir, "copilot-home-from-option")
+			opts.Env = append([]string{}, opts.Env...)
+			opts.Env = append(opts.Env, "COPILOT_HOME="+filepath.Join(ctx.WorkDir, "copilot-home-from-env"))
 			opts.GitHubToken = "process-option-token"
 			opts.LogLevel = "debug"
 			opts.SessionIdleTimeoutSeconds = 17
@@ -179,6 +182,7 @@ func TestClientOptionsE2E(t *testing.T) {
 		}
 
 		expectEnv := map[string]string{
+			"COPILOT_HOME":                                       filepath.Join(ctx.WorkDir, "copilot-home-from-option"),
 			"COPILOT_SDK_AUTH_TOKEN":                             "process-option-token",
 			"COPILOT_OTEL_ENABLED":                               "true",
 			"OTEL_EXPORTER_OTLP_ENDPOINT":                        "http://127.0.0.1:4318",
@@ -402,6 +406,7 @@ function saveCapture() {
     cwd: process.cwd(),
     requests,
     env: {
+      COPILOT_HOME: process.env.COPILOT_HOME,
       COPILOT_SDK_AUTH_TOKEN: process.env.COPILOT_SDK_AUTH_TOKEN,
       COPILOT_OTEL_ENABLED: process.env.COPILOT_OTEL_ENABLED,
       OTEL_EXPORTER_OTLP_ENDPOINT: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
diff --git a/go/internal/embeddedcli/embeddedcli.go b/go/internal/embeddedcli/embeddedcli.go
@@ -84,12 +84,16 @@ func install() (path string) {
 	}
 	installDir := config.Dir
 	if installDir == "" {
-		var err error
-		if installDir, err = os.UserCacheDir(); err != nil {
-			// Fall back to temp dir if UserCacheDir is unavailable
-			installDir = os.TempDir()
+		if copilotHome := os.Getenv("COPILOT_HOME"); copilotHome != "" {
+			installDir = filepath.Join(copilotHome, "cache", "copilot-sdk")
+		} else {
+			var err error
+			if installDir, err = os.UserCacheDir(); err != nil {
+				// Fall back to temp dir if UserCacheDir is unavailable
+				installDir = os.TempDir()
+			}
+			installDir = filepath.Join(installDir, "copilot-sdk")
 		}
-		installDir = filepath.Join(installDir, "copilot-sdk")
 	}
 	path, err := installAt(installDir)
 	if err != nil {
diff --git a/go/types.go b/go/types.go
@@ -25,6 +25,14 @@ type ClientOptions struct {
 	CLIArgs []string
 	// Cwd is the working directory for the CLI process (default: "" = inherit from current process)
 	Cwd string
+	// CopilotHome is the base directory for Copilot data (session state, config, etc.).
+	// Sets the COPILOT_HOME environment variable on the spawned CLI process.
+	// When empty, the CLI defaults to ~/.copilot.
+	// This does not affect where the Go SDK extracts the embedded CLI binary;
+	// use embeddedcli.Config.Dir to control that install/cache location.
+	// This option is only used when the SDK spawns the CLI process; it is ignored
+	// when connecting to an external server via CLIUrl.
+	CopilotHome string
 	// Port for TCP transport (default: 0 = random port)
 	Port int
 	// UseStdio controls whether to use stdio transport instead of TCP.
diff --git a/nodejs/README.md b/nodejs/README.md
@@ -88,6 +88,7 @@ new CopilotClient(options?: CopilotClientOptions)
 - `autoStart?: boolean` - Auto-start server (default: true)
 - `gitHubToken?: string` - GitHub token for authentication. When provided, takes priority over other auth methods.
 - `useLoggedInUser?: boolean` - Whether to use logged-in user for authentication (default: true, but false when `gitHubToken` is provided). Cannot be used with `cliUrl`.
+- `copilotHome?: string` - Base directory for Copilot data (session state, config, etc.). Sets `COPILOT_HOME` on the spawned CLI process. When not set, the CLI defaults to `~/.copilot`. Useful in restricted environments where only specific directories are writable. Ignored when using `cliUrl`.
 - `telemetry?: TelemetryConfig` - OpenTelemetry configuration for the CLI process. Providing this object enables telemetry — no separate flag needed. See [Telemetry](#telemetry) below.
 - `onGetTraceContext?: TraceContextProvider` - Advanced: callback for linking your application's own OpenTelemetry spans into the same distributed trace as the CLI's spans. Not needed for normal telemetry collection. See [Telemetry](#telemetry) below.
 
diff --git a/nodejs/src/client.ts b/nodejs/src/client.ts
@@ -228,13 +228,15 @@ export class CopilotClient {
             | "onGetTraceContext"
             | "sessionFs"
             | "tcpConnectionToken"
+            | "copilotHome"
         >
     > & {
         cliPath?: string;
         cliUrl?: string;
         gitHubToken?: string;
         useLoggedInUser?: boolean;
         telemetry?: TelemetryConfig;
+        copilotHome?: string;
     };
     private isExternalServer: boolean = false;
     private forceStopping: boolean = false;
@@ -381,6 +383,7 @@ export class CopilotClient {
             // Default useLoggedInUser to false when gitHubToken is provided, otherwise true
             useLoggedInUser: options.useLoggedInUser ?? (options.gitHubToken ? false : true),
             telemetry: options.telemetry,
+            copilotHome: options.copilotHome,
             sessionIdleTimeoutSeconds: options.sessionIdleTimeoutSeconds ?? 0,
         };
     }
@@ -1496,6 +1499,10 @@ export class CopilotClient {
                 envWithoutNodeDebug.COPILOT_CONNECTION_TOKEN = this.effectiveConnectionToken;
             }
 
+            if (this.options.copilotHome) {
+                envWithoutNodeDebug.COPILOT_HOME = this.options.copilotHome;
+            }
+
             if (!this.options.cliPath) {
                 throw new Error(
                     "Path to Copilot CLI is required. Please provide it via the cliPath option, or use cliUrl to rely on a remote CLI."
diff --git a/nodejs/src/types.ts b/nodejs/src/types.ts
@@ -71,6 +71,15 @@ export interface CopilotClientOptions {
      */
     cwd?: string;
 
+    /**
+     * Base directory for Copilot data (session state, config, etc.).
+     * Sets the COPILOT_HOME environment variable on the spawned CLI process.
+     * When not set, the CLI defaults to ~/.copilot.
+     * This option is only used when the SDK spawns the CLI process; it is ignored
+     * when connecting to an external server via {@link cliUrl}.
+     */
+    copilotHome?: string;
+
     /**
      * Port for the CLI server (TCP mode only)
      * @default 0 (random available port)
diff --git a/nodejs/test/client.test.ts b/nodejs/test/client.test.ts
@@ -662,6 +662,23 @@ describe("CopilotClient", () => {
             expect((client as any).options.useLoggedInUser).toBe(false);
         });
 
+        it("should accept copilotHome option", () => {
+            const client = new CopilotClient({
+                copilotHome: "/custom/copilot/home",
+                logLevel: "error",
+            });
+
+            expect((client as any).options.copilotHome).toBe("/custom/copilot/home");
+        });
+
+        it("should leave copilotHome undefined when not provided", () => {
+            const client = new CopilotClient({
+                logLevel: "error",
+            });
+
+            expect((client as any).options.copilotHome).toBeUndefined();
+        });
+
         it("should throw error when gitHubToken is used with cliUrl", () => {
             expect(() => {
                 new CopilotClient({
diff --git a/nodejs/test/e2e/client_options.e2e.test.ts b/nodejs/test/e2e/client_options.e2e.test.ts
diff --git a/python/README.md b/python/README.md
diff --git a/python/copilot/client.py b/python/copilot/client.py
diff --git a/python/e2e/test_client_options_e2e.py b/python/e2e/test_client_options_e2e.py
diff --git a/python/test_client.py b/python/test_client.py

Original file line number	Diff line number	Diff line change
`@@ -1261,6 +1261,11 @@ private async Task VerifyProtocolVersionAsync(Connection connection, Cancellatio`
`1261`	`1261`	`startInfo.Environment["COPILOT_CONNECTION_TOKEN"] = connectionToken;`
`1262`	`1262`	`}`
`1263`	`1263`
	`1264`	`+ if (!string.IsNullOrEmpty(options.CopilotHome))`
	`1265`	`+ {`
	`1266`	`+ startInfo.Environment["COPILOT_HOME"] = options.CopilotHome;`
	`1267`	`+ }`
	`1268`	`+`
`1264`	`1269`	`// Set telemetry environment variables if configured`
`1265`	`1270`	`if (options.Telemetry is { } telemetry)`
`1266`	`1271`	`{`