Remote validation: route commands to a sidecar with auto-creation (#288)

So we can automatically run validation in sidecars.

The chunk validate command accepts a remote flag which is good for direct usage, but is limited for hooks since we can't easily vary the arguments to the hook command. Instead we make hooks use configuration based settings for specific validate commands that can run remotely. This also necessitated adding an image to use for sidecars when creating Chunk sidecars.

This also adds some falls backs for connectivity issues over ssh to run commands locally as a fall back. Execution tracking will depend on this.

---------

Co-authored-by: webster <michael@webster.fyi>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 3 people

.chunk/config.json

@@ -6,7 +6,8 @@
       "role": "gate",
       "fileExt": ".go",
       "timeout": 300,
-      "limit": 3
+      "limit": 3,
+      "remote": true
     },
     {
       "name": "test-changed",
@@ -46,7 +47,7 @@
       },
       {
         "name": "system",
-        "command": "sudo apt-get update \u0026\u0026 sudo apt-get install -y git --no-install-recommends \u0026\u0026 sudo rm -rf /var/lib/apt/lists/*"
+        "command": "sudo apt-get update && sudo apt-get install -y git --no-install-recommends && sudo rm -rf /var/lib/apt/lists/*"
       },
       {
         "name": "install",
@@ -55,5 +56,6 @@
     ],
     "image": "cimg/go",
     "image_version": "1.26.2"
-  }
+  },
+  "orgID": "f22b6566-597d-46d5-ba74-99ef5bb3d85c"
 }

internal/cmd/config.go

@@ -2,6 +2,7 @@ package cmd
 
 import (
 	"fmt"
+	"os"
 
 	"github.com/spf13/cobra"
 
@@ -61,16 +62,43 @@ func newConfigSetCmd() *cobra.Command {
 	return &cobra.Command{
 		Use:   "set <key> <value>",
 		Short: "Set a config value",
-		Long:  "Set a config value (model). Use 'chunk auth set <provider>' to store credentials with validation.",
+		Long:  "Set a config value. Use 'chunk auth set <provider>' to store credentials with validation.\n\nUser keys: model\nProject keys: orgID, validation.sidecarImage",
 		Args:  cobra.ExactArgs(2),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			io := iostream.FromCmd(cmd)
 			key, value := args[0], args[1]
 
+			if config.ValidProjectConfigKeys[key] {
+				workDir, err := os.Getwd()
+				if err != nil {
+					return err
+				}
+				projCfg, err := config.LoadProjectConfig(workDir)
+				if err != nil {
+					projCfg = &config.ProjectConfig{}
+				}
+				switch key {
+				case "orgID":
+					projCfg.OrgID = value
+				case "validation.sidecarImage":
+					if projCfg.Validation == nil {
+						projCfg.Validation = &config.ValidationConfig{}
+					}
+					projCfg.Validation.SidecarImage = value
+				default:
+					return fmt.Errorf("internal: unhandled project config key %q", key)
+				}
+				if err := config.SaveProjectConfig(workDir, projCfg); err != nil {
+					return &userError{msg: "Could not save project configuration.", suggestion: configFilePermHint, err: err}
+				}
+				io.Printf("%s\n", ui.Success(fmt.Sprintf("Set %s to %s", key, value)))
+				return nil
+			}
+
 			if !config.ValidConfigKeys[key] {
 				return &userError{
 					msg:    fmt.Sprintf("Unknown config key: %q.", key),
-					detail: "Supported keys: model.",
+					detail: "Supported keys: model, orgID, validation.sidecarImage.",
 					errMsg: fmt.Sprintf("unknown config key %q", key),
 				}
 			}

internal/cmd/validate.go

@@ -8,6 +8,7 @@ import (
 	"fmt"
 	"io"
 	"os"
+	"path/filepath"
 	"strings"
 
 	"github.com/spf13/cobra"
@@ -60,7 +61,7 @@ func detectHook(r io.Reader) *hookContext {
 }
 
 func newValidateCmd() *cobra.Command {
-	var sidecarID, identityFile, workdir string
+	var sidecarID, identityFile, workdir, orgID string
 	var dryRun, list, save, remote bool
 	var inlineCmd, projectDir string
 
@@ -135,13 +136,35 @@ func newValidateCmd() *cobra.Command {
 				return mapValidateError(validate.RunDryRun(cfg, name, statusFn))
 			}
 
+			// allRemote is true when the caller explicitly targets the sidecar
+			// (--remote or --sidecar-id), meaning every command runs there.
+			// Per-command routing only applies when the sidecar is resolved implicitly.
+			allRemote := remote || sidecarID != ""
+
+			image := resolveImage(name, cfg)
+
 			if remote {
-				if err := resolveSidecarID(&sidecarID); err != nil {
+				// --remote: force all commands to sidecar, creating one if needed.
+				if err := resolveOrCreateSidecarID(cmd.Context(), &sidecarID, orgID, image, workDir, streams); err != nil {
 					return err
 				}
+				statusFn(iostream.LevelInfo, fmt.Sprintf("running all commands on sidecar %s", sidecarID))
+			} else if cfg.HasRemoteCommands() {
+				// Per-command remote: use active sidecar if available.
+				if active, err := sidecar.LoadActive(); err == nil && active != nil {
+					sidecarID = active.SidecarID
+					statusFn(iostream.LevelInfo, fmt.Sprintf("using sidecar %s for remote commands", sidecarID))
+				} else if hook != nil {
+					// In Stop hook context: auto-create a sandbox if possible.
+					if err := resolveOrCreateSidecarID(cmd.Context(), &sidecarID, orgID, image, workDir, streams); err != nil {
+						streams.ErrPrintf("warning: no sandbox available (%v); run 'chunk config set orgID <id>' to enable remote validation, running locally instead\n", err)
+					}
+				} else {
+					statusFn(iostream.LevelWarn, "no active sidecar found — remote commands will run locally")
+				}
 			}
 
-			execErr := runValidate(cmd.Context(), workDir, name, inlineCmd, save, sidecarID, identityFile, workdir, cfg, statusFn, streams)
+			execErr := runValidate(cmd.Context(), workDir, name, inlineCmd, save, sidecarID, identityFile, workdir, allRemote, cfg, statusFn, streams)
 
 			if hook != nil {
 				maxAttempts := cfg.StopHookMaxAttempts
@@ -154,8 +177,9 @@ func newValidateCmd() *cobra.Command {
 		},
 	}
 
-	cmd.Flags().BoolVar(&remote, "remote", false, "Run on active sidecar (reads .chunk/sidecar.json)")
+	cmd.Flags().BoolVar(&remote, "remote", false, "Run on active sidecar, or create one if none is set")
 	cmd.Flags().StringVar(&sidecarID, "sidecar-id", "", "Sidecar ID for remote execution")
+	cmd.Flags().StringVar(&orgID, "org-id", "", "Organization ID (used when creating a new sidecar)")
 	cmd.Flags().StringVar(&identityFile, "identity-file", "", "SSH identity file (uses ssh-agent or ~/.ssh/chunk_ai when omitted)")
 	cmd.Flags().StringVar(&workdir, "workdir", "", "Working directory on sidecar (reads from sidecar.json, defaults to ./workspace)")
 	cmd.Flags().BoolVar(&dryRun, "dry-run", false, "Show commands without executing")
@@ -169,8 +193,10 @@ func newValidateCmd() *cobra.Command {
 
 // runValidate dispatches to the appropriate Run* function based on the
 // provided options. It is shared by both direct and hook invocations.
-func runValidate(ctx context.Context, workDir, name, inlineCmd string, save bool, sidecarID, identityFile, workdir string, cfg *config.ProjectConfig, statusFn iostream.StatusFunc, streams iostream.Streams) error {
-	// --cmd: inline command
+// allRemote is true when --remote is passed explicitly (all commands run on the
+// sidecar); false means only commands with Remote:true are routed to the sidecar.
+func runValidate(ctx context.Context, workDir, name, inlineCmd string, save bool, sidecarID, identityFile, workdir string, allRemote bool, cfg *config.ProjectConfig, statusFn iostream.StatusFunc, streams iostream.Streams) error {
+	// --cmd: inline command (always local in per-command mode)
 	if inlineCmd != "" {
 		cmdName := name
 		if cmdName == "" {
@@ -182,23 +208,65 @@ func runValidate(ctx context.Context, workDir, name, inlineCmd string, save bool
 			}
 			streams.ErrPrintf("%s\n", ui.Success(fmt.Sprintf("Saved %s to .chunk/config.json", cmdName)))
 		}
-		if sidecarID != "" {
+		if sidecarID != "" && allRemote {
 			execFn, dest, err := openSSHSession(ctx, sidecarID, identityFile, workdir, streams)
 			if err != nil {
 				return err
 			}
-			return validate.RunRemoteInline(ctx, execFn, cmdName, inlineCmd, dest, streams)
+			return validate.RunRemoteInline(ctx, execFn, cmdName, inlineCmd, dest, statusFn, streams)
 		}
 		return validate.RunInline(ctx, workDir, cmdName, inlineCmd, statusFn, streams)
 	}
 
-	// Remote execution
-	if sidecarID != "" {
+	// All-remote execution (--remote flag): send everything to the sidecar.
+	if sidecarID != "" && allRemote {
 		execFn, dest, err := openSSHSession(ctx, sidecarID, identityFile, workdir, streams)
 		if err != nil {
 			return err
 		}
-		return validate.RunRemote(ctx, execFn, cfg, name, dest, streams)
+		return validate.RunRemote(ctx, execFn, cfg, name, dest, statusFn, streams)
+	}
+
+	// Per-command remote routing: commands with Remote:true go to the sidecar,
+	// the rest run locally.
+	if sidecarID != "" {
+		if name != "" {
+			if cmd := cfg.FindCommand(name); cmd != nil && cmd.Remote {
+				statusFn(iostream.LevelInfo, fmt.Sprintf("running %s on sidecar %s", name, sidecarID))
+				execFn, dest, err := openSSHSession(ctx, sidecarID, identityFile, workdir, streams)
+				if err != nil {
+					return err
+				}
+				return validate.RunRemote(ctx, execFn, cfg, name, dest, statusFn, streams)
+			}
+			statusFn(iostream.LevelInfo, fmt.Sprintf("running %s locally (not marked remote)", name))
+			// Named command is not marked remote; fall through to local execution.
+		} else {
+			remoteCfg, localCfg := splitByRemote(cfg)
+			if len(remoteCfg.Commands) > 0 {
+				names := commandNames(remoteCfg.Commands)
+				statusFn(iostream.LevelInfo, fmt.Sprintf("running on sidecar %s: %s", sidecarID, names))
+			}
+			if len(localCfg.Commands) > 0 {
+				statusFn(iostream.LevelInfo, fmt.Sprintf("running locally: %s", commandNames(localCfg.Commands)))
+			}
+			var runErr error
+			if len(remoteCfg.Commands) > 0 {
+				execFn, dest, err := openSSHSession(ctx, sidecarID, identityFile, workdir, streams)
+				if err != nil {
+					streams.ErrPrintf("warning: could not reach sidecar (%v); running %s locally instead\n", err, commandNames(remoteCfg.Commands))
+					localCfg.Commands = append(remoteCfg.Commands, localCfg.Commands...)
+				} else {
+					runErr = validate.RunRemote(ctx, execFn, remoteCfg, "", dest, statusFn, streams)
+				}
+			}
+			if len(localCfg.Commands) > 0 {
+				if err := mapValidateError(validate.RunAll(ctx, workDir, localCfg, statusFn, streams)); err != nil {
+					runErr = errors.Join(runErr, err)
+				}
+			}
+			return runErr
+		}
 	}
 
 	// Named command
@@ -270,6 +338,108 @@ func openSSHSession(ctx context.Context, sidecarID, identityFile, workdir string
 	return execFn, dest, nil
 }
 
+// splitByRemote partitions cfg.Commands into two configs: one containing only
+// commands with Remote:true, and one containing the rest.
+func splitByRemote(cfg *config.ProjectConfig) (remote, local *config.ProjectConfig) {
+	remote = &config.ProjectConfig{}
+	local = &config.ProjectConfig{}
+	for _, cmd := range cfg.Commands {
+		if cmd.Remote {
+			remote.Commands = append(remote.Commands, cmd)
+		} else {
+			local.Commands = append(local.Commands, cmd)
+		}
+	}
+	return remote, local
+}
+
+// commandNames returns a comma-separated list of command names.
+func commandNames(cmds []config.Command) string {
+	names := make([]string, len(cmds))
+	for i, c := range cmds {
+		names[i] = c.Name
+	}
+	return strings.Join(names, ", ")
+}
+
+// resolveImage returns the sidecar image to use for sandbox creation.
+// A per-command sidecarImage takes precedence over the project-level default.
+func resolveImage(name string, cfg *config.ProjectConfig) string {
+	if name != "" && cfg != nil {
+		if cmd := cfg.FindCommand(name); cmd != nil && cmd.SidecarImage != "" {
+			return cmd.SidecarImage
+		}
+	}
+	if cfg != nil && cfg.Validation != nil {
+		return cfg.Validation.SidecarImage
+	}
+	return ""
+}
+
+// resolveOrCreateSidecarID fills sidecarID from the active sidecar, or creates
+// a new sandbox when none is configured.
+func resolveOrCreateSidecarID(ctx context.Context, sidecarID *string, orgID, image, workDir string, streams iostream.Streams) error {
+	if *sidecarID != "" {
+		return nil
+	}
+	active, err := sidecar.LoadActive()
+	if err != nil {
+		return &userError{msg: "Could not load the active sidecar.", suggestion: configFilePermHint, err: err}
+	}
+	if active != nil {
+		*sidecarID = active.SidecarID
+		return nil
+	}
+	streams.ErrPrintf("No active sidecar found, creating a new sandbox...\n")
+	client, err := ensureCircleCIClient(ctx, streams, tui.PromptHidden)
+	if err != nil {
+		return err
+	}
+	// Fallback: read org ID from project config if not provided via flag or env.
+	if orgID == "" {
+		if projCfg, loadErr := config.LoadProjectConfig(workDir); loadErr == nil && projCfg.OrgID != "" {
+			orgID = projCfg.OrgID
+		}
+	}
+	resolvedOrgID, err := resolveOrgID(orgID, orgPicker(ctx, client))
+	if err != nil {
+		return err
+	}
+	provider := os.Getenv(config.EnvSidecarProvider)
+	if provider == "" {
+		provider = defaultProvider
+	}
+	sandboxName := filepath.Base(workDir) + "-validate"
+	sc, err := sidecar.Create(ctx, client, resolvedOrgID, sandboxName, provider, image)
+	if err != nil {
+		if authErr := notAuthorized("create sidecars", err); authErr != nil {
+			return authErr
+		}
+		return &userError{
+			msg:        "Could not create a sandbox.",
+			suggestion: "Check your network connection or run 'chunk sidecar create' manually.",
+			err:        err,
+		}
+	}
+	if saveErr := sidecar.SaveActive(sidecar.ActiveSidecar{SidecarID: sc.ID, Name: sc.Name}); saveErr != nil {
+		streams.ErrPrintf("warning: could not save active sidecar: %v\n", saveErr)
+	}
+	// Persist the org ID so future sandbox creation skips the picker.
+	projCfg, loadErr := config.LoadProjectConfig(workDir)
+	if loadErr != nil {
+		projCfg = &config.ProjectConfig{}
+	}
+	if projCfg.OrgID == "" {
+		projCfg.OrgID = resolvedOrgID
+		if saveErr := config.SaveProjectConfig(workDir, projCfg); saveErr != nil {
+			streams.ErrPrintf("warning: could not save org ID to project config: %v\n", saveErr)
+		}
+	}
+	streams.ErrPrintf("%s\n", ui.Success(fmt.Sprintf("Created sandbox %s (%s)", sc.Name, sc.ID)))
+	*sidecarID = sc.ID
+	return nil
+}
+
 func mapValidateError(err error) error {
 	if errors.Is(err, validate.ErrNotConfigured) {
 		return &userError{

internal/config/config.go

@@ -256,9 +256,16 @@ func MaskKey(key string) string {
 	return strings.Repeat("*", len(key)-4) + key[len(key)-4:]
 }
 
-// ValidConfigKeys are the keys accepted by "config set".
+// ValidConfigKeys are the keys accepted by "config set" that write to the user config.
 // Credentials (anthropicAPIKey, circleCIToken) are intentionally excluded —
 // users should use "auth set" which validates before storing.
 var ValidConfigKeys = map[string]bool{
 	"model": true,
 }
+
+// ValidProjectConfigKeys are the keys accepted by "config set" that write to
+// the project config (.chunk/config.json).
+var ValidProjectConfigKeys = map[string]bool{
+	"orgID":                   true,
+	"validation.sidecarImage": true,
+}