feat: add multi-server workspace distribution (ISS-43)

Auto-select least-loaded server for workspace placement via parallel
SSH resource queries (nproc, free -b, /proc/loadavg). Three-tier
server resolution in devbox up: --server flag → config → pool auto-select.
Cross-server filtering in devbox list with --server flag. Server field
in devbox.yaml is now optional when a server pool is configured.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: chuongld20

cmd/devbox/main.go

@@ -120,17 +120,61 @@ func upCmd(wm workspace.Manager) *cobra.Command {
 				return fmt.Errorf("devbox up: %w", err)
 			}
 
-			// Apply flag overrides
-			if s, _ := cmd.Flags().GetString("server"); s != "" {
-				cfg.Server = s
-			}
 			if b, _ := cmd.Flags().GetString("branch"); b != "" {
 				cfg.Branch = b
 			}
 
-			if cfg.Server == "" {
-				return fmt.Errorf("devbox up: server is required — add 'server:' to devbox.yaml or use --server flag")
+			// Load server pool (best-effort).
+			configPath, _ := server.DefaultConfigPath()
+			sshExec, err := devboxssh.New()
+			if err != nil {
+				return fmt.Errorf("devbox up: %w", err)
+			}
+			defer sshExec.Close()
+
+			pool, poolErr := server.NewFilePool(configPath, sshExec)
+			var poolServers []server.Server
+			if poolErr == nil {
+				poolServers, _ = pool.List()
+			}
+			poolConfigured := len(poolServers) > 0
+
+			// 3-tier server resolution: --server flag → config.Server → auto-select from pool.
+			targetServer := cfg.Server
+			serverFlag, _ := cmd.Flags().GetString("server")
+
+			if serverFlag != "" {
+				// Tier 1: --server flag — look up from pool by name.
+				found := false
+				for _, srv := range poolServers {
+					if srv.Name == serverFlag {
+						targetServer = server.SSHHost(&srv)
+						found = true
+						break
+					}
+				}
+				if !found {
+					// Not in pool — use as raw hostname (backward compat).
+					targetServer = serverFlag
+				}
+			} else if targetServer == "" && poolConfigured {
+				// Tier 3: Auto-select from pool.
+				selector := server.NewLeastLoaded(sshExec)
+				selected, err := selector.Select(cmd.Context(), poolServers)
+				if err != nil {
+					return fmt.Errorf("devbox up: %w", err)
+				}
+				targetServer = server.SSHHost(selected)
+				fmt.Fprintf(os.Stderr, "Using server: %s (%s)\n", selected.Name, selected.Host)
 			}
+			// Tier 2: config.Server is already set in targetServer.
+
+			if err := cfg.ValidateForUp(poolConfigured); err != nil {
+				if targetServer == "" {
+					return fmt.Errorf("devbox up: %w", err)
+				}
+			}
+			cfg.Server = targetServer
 
 			// Merge resource limits: server defaults <- workspace overrides.
 			globalCfg, err := config.LoadGlobal()
@@ -173,13 +217,6 @@ func upCmd(wm workspace.Manager) *cobra.Command {
 			}
 
 			// Expose ports via Tailscale on the remote server
-			sshExec, err := devboxssh.New()
-			if err != nil {
-				ui.StopSpinner(spin, false)
-				return fmt.Errorf("devbox up: %w", err)
-			}
-			defer sshExec.Close()
-
 			tm := tailscale.NewManager(remoteRunner(sshExec, cfg.Server))
 			for name, port := range cfg.Ports {
 				if err := tm.Serve(port, ws.Name); err != nil {
@@ -199,7 +236,7 @@ func upCmd(wm workspace.Manager) *cobra.Command {
 		},
 	}
 	cmd.Flags().String("branch", "", "Git branch to checkout")
-	cmd.Flags().String("server", "", "Target server (overrides devbox.yaml)")
+	cmd.Flags().String("server", "", "Target server name from pool (or hostname)")
 	return cmd
 }
 
@@ -233,17 +270,42 @@ func stopCmd(wm workspace.Manager) *cobra.Command {
 }
 
 func listCmd(wm workspace.Manager) *cobra.Command {
-	return &cobra.Command{
+	cmd := &cobra.Command{
 		Use:     "list",
 		Aliases: []string{"ls"},
 		Short:   "List all workspaces",
-		Long:    "List all workspaces across all configured servers.\nShows status, resource limits, and server for each workspace.",
+		Long:    "List all workspaces across all configured servers.\nShows status, resource limits, and server for each workspace.\nUse --server to filter to a specific server.",
 		RunE: func(cmd *cobra.Command, args []string) error {
 			workspaces, err := wm.List()
 			if err != nil {
 				return fmt.Errorf("devbox list: %w", err)
 			}
 
+			// Filter by --server if provided.
+			serverFilter, _ := cmd.Flags().GetString("server")
+			if serverFilter != "" {
+				// Resolve server name from pool if possible.
+				resolvedHost := serverFilter
+				configPath, _ := server.DefaultConfigPath()
+				if pool, err := server.NewFilePool(configPath, nil); err == nil {
+					if servers, err := pool.List(); err == nil {
+						for _, srv := range servers {
+							if srv.Name == serverFilter {
+								resolvedHost = server.SSHHost(&srv)
+								break
+							}
+						}
+					}
+				}
+				filtered := make([]workspace.Workspace, 0)
+				for _, ws := range workspaces {
+					if ws.ServerHost == resolvedHost || ws.ServerHost == serverFilter {
+						filtered = append(filtered, ws)
+					}
+				}
+				workspaces = filtered
+			}
+
 			if len(workspaces) == 0 {
 				fmt.Println("No workspaces found")
 				return nil
@@ -331,6 +393,8 @@ func listCmd(wm workspace.Manager) *cobra.Command {
 			return nil
 		},
 	}
+	cmd.Flags().String("server", "", "Filter workspaces by server name or hostname")
+	return cmd
 }
 
 func destroyCmd(wm workspace.Manager) *cobra.Command {

internal/config/config.go

@@ -120,14 +120,6 @@ func Load(path string) (*DevboxConfig, error) {
 		)
 	}
 
-	if cfg.Server == "" {
-		return nil, devboxerr.NewConfigError(
-			fmt.Sprintf("config file %s: 'server' is required", path),
-			"Add 'server: your-server' to devbox.yaml",
-			nil,
-		)
-	}
-
 	if cfg.Resources != nil {
 		if err := cfg.Resources.Validate(); err != nil {
 			return nil, devboxerr.NewConfigError(
@@ -141,6 +133,19 @@ func Load(path string) (*DevboxConfig, error) {
 	return &cfg, nil
 }
 
+// ValidateForUp checks that the config has enough info to create a workspace.
+// If poolConfigured is true, the server field is optional (auto-select from pool).
+func (c *DevboxConfig) ValidateForUp(poolConfigured bool) error {
+	if c.Server == "" && !poolConfigured {
+		return devboxerr.NewConfigError(
+			"'server' is required when no server pool is configured",
+			"Add 'server: your-server' to devbox.yaml, use --server flag, or run 'devbox server add'",
+			nil,
+		)
+	}
+	return nil
+}
+
 // ServerDefaults holds per-server default settings.
 type ServerDefaults struct {
 	Resources Resources `yaml:"resources"`

internal/config/config_test.go

@@ -120,17 +120,25 @@ func TestLoad_MissingServer(t *testing.T) {
 
 	os.WriteFile(path, []byte("name: myproject\n"), 0644)
 
-	_, err := Load(path)
-	if err == nil {
-		t.Fatal("expected error for missing server")
+	// Load should succeed — server is now optional (validated at use time).
+	cfg, err := Load(path)
+	if err != nil {
+		t.Fatalf("Load() unexpected error: %v", err)
 	}
-	if !strings.Contains(err.Error(), "'server' is required") {
-		t.Errorf("error = %q, want it to contain 'server' is required", err.Error())
+	if cfg.Server != "" {
+		t.Errorf("Server = %q, want empty", cfg.Server)
 	}
 
-	var ce *devboxerr.ConfigError
-	if !errors.As(err, &ce) {
-		t.Fatalf("expected ConfigError, got %T", err)
+	// ValidateForUp without pool should error.
+	err = cfg.ValidateForUp(false)
+	if err == nil {
+		t.Fatal("ValidateForUp(false) should error when server is empty")
+	}
+
+	// ValidateForUp with pool should succeed.
+	err = cfg.ValidateForUp(true)
+	if err != nil {
+		t.Fatalf("ValidateForUp(true) unexpected error: %v", err)
 	}
 }
 

internal/config/devcontainer_test.go

@@ -4,7 +4,6 @@ import (
 	"errors"
 	"os"
 	"path/filepath"
-	"strings"
 	"testing"
 
 	devboxerr "github.com/junixlabs/devbox/internal/errors"
@@ -327,10 +326,10 @@ func TestLoadFromDir_NeitherExists(t *testing.T) {
 	}
 }
 
-func TestLoadFromDir_MalformedDevboxYaml_NoFallback(t *testing.T) {
+func TestLoadFromDir_DevboxYamlWithoutServer_NoFallback(t *testing.T) {
 	dir := t.TempDir()
 
-	// Create a malformed devbox.yaml (missing server).
+	// Create devbox.yaml without server (now valid — server is optional).
 	os.WriteFile(
 		filepath.Join(dir, "devbox.yaml"),
 		[]byte("name: broken-project\n"),
@@ -346,18 +345,13 @@ func TestLoadFromDir_MalformedDevboxYaml_NoFallback(t *testing.T) {
 		0644,
 	)
 
-	_, err := LoadFromDir(dir)
-	if err == nil {
-		t.Fatal("expected error for malformed devbox.yaml, should not fall back to devcontainer.json")
-	}
-
-	// Should report the devbox.yaml error, not silently fall back.
-	var ce *devboxerr.ConfigError
-	if !errors.As(err, &ce) {
-		t.Fatalf("expected ConfigError, got %T", err)
+	// LoadFromDir should use devbox.yaml (not fall back to devcontainer.json).
+	cfg, err := LoadFromDir(dir)
+	if err != nil {
+		t.Fatalf("LoadFromDir() unexpected error: %v", err)
 	}
-	if !strings.Contains(err.Error(), "'server' is required") {
-		t.Errorf("error = %q, want it to mention server is required", err.Error())
+	if cfg.Name != "broken-project" {
+		t.Errorf("Name = %q, want %q (from devbox.yaml, not devcontainer)", cfg.Name, "broken-project")
 	}
 }
 

internal/server/pool.go

@@ -142,7 +142,7 @@ func (p *filePool) checkServer(srv *Server) *HealthStatus {
 		return status
 	}
 
-	host := sshHost(srv)
+	host := SSHHost(srv)
 	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
 	defer cancel()