feat: add sandbox create command (#68)

Add explicit sandbox creation commands so users can provision a reusable sandbox without running a dummy exec first. This improves the long-running sandbox workflow while keeping default output script-friendly.

Author: lox

README.md

@@ -76,6 +76,19 @@ Run a command in a sandbox:
 cleanroom exec -- npm test
 ```
 
+Pre-create a long-running sandbox without running a command:
+
+```bash
+SANDBOX_ID="$(cleanroom create)"
+cleanroom exec --sandbox-id "$SANDBOX_ID" -- npm run lint
+```
+
+Equivalent namespaced command:
+
+```bash
+cleanroom sandbox create
+```
+
 The sandbox stays running after the command completes. List sandboxes and run more commands:
 
 ```bash

internal/cli/cli.go

@@ -72,6 +72,7 @@ type CLI struct {
 	Policy  PolicyCommand  `cmd:"" help:"Policy commands"`
 	Config  ConfigCommand  `cmd:"" help:"Runtime config commands"`
 	Image   ImageCommand   `cmd:"" help:"Manage OCI image cache artifacts"`
+	Create  CreateCommand  `cmd:"" help:"Create a sandbox"`
 	Exec    ExecCommand    `cmd:"" help:"Execute a command in a cleanroom backend"`
 	Console ConsoleCommand `cmd:"" help:"Attach an interactive console to a cleanroom execution"`
 	Serve   ServeCommand   `cmd:"" help:"Run the cleanroom control-plane server"`
@@ -168,6 +169,22 @@ type ExecCommand struct {
 	Command []string `arg:"" passthrough:"" required:"" help:"Command to execute"`
 }
 
+type SandboxCreateCommand struct {
+	clientFlags
+	Chdir         string `short:"c" help:"Change to this directory before running commands"`
+	Backend       string `help:"Execution backend (defaults to runtime config or firecracker)"`
+	LaunchSeconds int64  `help:"VM boot/guest-agent readiness timeout in seconds"`
+	JSON          bool   `help:"Print sandbox as JSON"`
+}
+
+type CreateCommand struct {
+	clientFlags
+	Chdir         string `short:"c" help:"Change to this directory before running commands"`
+	Backend       string `help:"Execution backend (defaults to runtime config or firecracker)"`
+	LaunchSeconds int64  `help:"VM boot/guest-agent readiness timeout in seconds"`
+	JSON          bool   `help:"Print sandbox as JSON"`
+}
+
 type ConsoleCommand struct {
 	clientFlags
 	Chdir     string `short:"c" help:"Change to this directory before running commands"`
@@ -202,6 +219,7 @@ type DoctorCommand struct {
 }
 
 type SandboxCommand struct {
+	Create    SandboxCreateCommand    `cmd:"" help:"Create a sandbox"`
 	List      SandboxListCommand      `name:"ls" aliases:"list" cmd:"" help:"List active sandboxes"`
 	Terminate SandboxTerminateCommand `name:"rm" aliases:"terminate" cmd:"" help:"Terminate a sandbox"`
 }
@@ -656,6 +674,56 @@ func (c *SandboxTerminateCommand) Run(ctx *runtimeContext) error {
 	return err
 }
 
+func runSandboxCreate(ctx *runtimeContext, connectFlags clientFlags, chdir, backend string, launchSeconds int64, outputJSON bool) error {
+	client, err := connectFlags.connect()
+	if err != nil {
+		return err
+	}
+
+	cwd, err := resolveCWD(ctx.CWD, chdir)
+	if err != nil {
+		return err
+	}
+	compiled, _, err := ctx.Loader.LoadAndCompile(cwd)
+	if err != nil {
+		return err
+	}
+
+	resp, err := client.CreateSandbox(context.Background(), &cleanroomv1.CreateSandboxRequest{
+		Backend: backend,
+		Options: &cleanroomv1.SandboxOptions{
+			LaunchSeconds: launchSeconds,
+		},
+		Policy: compiled.ToProto(),
+	})
+	if err != nil {
+		return fmt.Errorf("create sandbox: %w", err)
+	}
+
+	sandbox := resp.GetSandbox()
+	sandboxID := strings.TrimSpace(sandbox.GetSandboxId())
+	if sandboxID == "" {
+		return errors.New("create sandbox: response missing sandbox id")
+	}
+
+	if outputJSON {
+		enc := json.NewEncoder(ctx.Stdout)
+		enc.SetIndent("", "  ")
+		return enc.Encode(sandbox)
+	}
+
+	_, err = fmt.Fprintln(ctx.Stdout, sandboxID)
+	return err
+}
+
+func (c *SandboxCreateCommand) Run(ctx *runtimeContext) error {
+	return runSandboxCreate(ctx, c.clientFlags, c.Chdir, c.Backend, c.LaunchSeconds, c.JSON)
+}
+
+func (c *CreateCommand) Run(ctx *runtimeContext) error {
+	return runSandboxCreate(ctx, c.clientFlags, c.Chdir, c.Backend, c.LaunchSeconds, c.JSON)
+}
+
 func (e *ExecCommand) Run(ctx *runtimeContext) error {
 	logger, err := newLogger(e.LogLevel, "client")
 	if err != nil {

internal/cli/cli_parse_test.go

@@ -95,6 +95,24 @@ func TestConfigInitParses(t *testing.T) {
 	}
 }
 
+func TestSandboxCreateParses(t *testing.T) {
+	c := &CLI{}
+	parser := newParserForTest(t, c)
+
+	if _, err := parser.Parse([]string{"sandbox", "create"}); err != nil {
+		t.Fatalf("parse sandbox create returned error: %v", err)
+	}
+}
+
+func TestTopLevelCreateParses(t *testing.T) {
+	c := &CLI{}
+	parser := newParserForTest(t, c)
+
+	if _, err := parser.Parse([]string{"create"}); err != nil {
+		t.Fatalf("parse create returned error: %v", err)
+	}
+}
+
 func TestServeCommandParsesWithoutAction(t *testing.T) {
 	c := &CLI{}
 	parser := newParserForTest(t, c)

internal/cli/sandbox_create_integration_test.go

@@ -0,0 +1,99 @@
+package cli
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	cleanroomv1 "github.com/buildkite/cleanroom/internal/gen/cleanroom/v1"
+)
+
+func runSandboxCreateWithCapture(cmd SandboxCreateCommand, ctx runtimeContext) execOutcome {
+	return runWithCapture(func(runCtx *runtimeContext) error {
+		return cmd.Run(runCtx)
+	}, nil, ctx)
+}
+
+func runCreateAliasWithCapture(cmd CreateCommand, ctx runtimeContext) execOutcome {
+	return runWithCapture(func(runCtx *runtimeContext) error {
+		return cmd.Run(runCtx)
+	}, nil, ctx)
+}
+
+func TestSandboxCreateIntegrationPrintsSandboxID(t *testing.T) {
+	host, _ := startIntegrationServer(t, &integrationAdapter{})
+	cwd := t.TempDir()
+
+	outcome := runSandboxCreateWithCapture(SandboxCreateCommand{
+		clientFlags: clientFlags{Host: host},
+		Chdir:       cwd,
+	}, runtimeContext{
+		CWD:    cwd,
+		Loader: integrationLoader{},
+	})
+	if outcome.cause != nil {
+		t.Fatalf("capture failure: %v", outcome.cause)
+	}
+	if outcome.err != nil {
+		t.Fatalf("SandboxCreateCommand.Run returned error: %v", outcome.err)
+	}
+
+	id := strings.TrimSpace(outcome.stdout)
+	if id == "" {
+		t.Fatalf("expected sandbox id output, got %q", outcome.stdout)
+	}
+
+	client := mustNewControlClient(t, host)
+	requireSandboxStatus(t, client, id, cleanroomv1.SandboxStatus_SANDBOX_STATUS_READY)
+}
+
+func TestSandboxCreateIntegrationJSONOutput(t *testing.T) {
+	host, _ := startIntegrationServer(t, &integrationAdapter{})
+	cwd := t.TempDir()
+
+	outcome := runSandboxCreateWithCapture(SandboxCreateCommand{
+		clientFlags: clientFlags{Host: host},
+		Chdir:       cwd,
+		JSON:        true,
+	}, runtimeContext{
+		CWD:    cwd,
+		Loader: integrationLoader{},
+	})
+	if outcome.cause != nil {
+		t.Fatalf("capture failure: %v", outcome.cause)
+	}
+	if outcome.err != nil {
+		t.Fatalf("SandboxCreateCommand.Run returned error: %v", outcome.err)
+	}
+
+	var payload map[string]any
+	if err := json.Unmarshal([]byte(outcome.stdout), &payload); err != nil {
+		t.Fatalf("expected json output, got parse error: %v (output=%q)", err, outcome.stdout)
+	}
+	rawID, ok := payload["sandbox_id"].(string)
+	if !ok || strings.TrimSpace(rawID) == "" {
+		t.Fatalf("expected sandbox_id in JSON output, got %v", payload)
+	}
+}
+
+func TestCreateAliasIntegrationPrintsSandboxID(t *testing.T) {
+	host, _ := startIntegrationServer(t, &integrationAdapter{})
+	cwd := t.TempDir()
+
+	outcome := runCreateAliasWithCapture(CreateCommand{
+		clientFlags: clientFlags{Host: host},
+		Chdir:       cwd,
+	}, runtimeContext{
+		CWD:    cwd,
+		Loader: integrationLoader{},
+	})
+	if outcome.cause != nil {
+		t.Fatalf("capture failure: %v", outcome.cause)
+	}
+	if outcome.err != nil {
+		t.Fatalf("CreateCommand.Run returned error: %v", outcome.err)
+	}
+	if strings.TrimSpace(outcome.stdout) == "" {
+		t.Fatalf("expected sandbox id output, got %q", outcome.stdout)
+	}
+}