Merge pull request 'MCP Server' (#14) from feature/mcp-server into main

Reviewed-on: https://forgejo.tail9a847c.ts.net/sh/pixels/pulls/14

Author: deevus

README.md

@@ -328,6 +328,145 @@ Create `~/.config/pixels/config.toml`:
 | `PIXELS_PROVISION_DEVTOOLS` | `provision.devtools` |
 | `PIXELS_NETWORK_EGRESS` | `network.egress` |
 
+## Using `pixels` as an MCP code-sandbox server
+
+`pixels mcp` runs a streamable-HTTP MCP server that exposes container
+lifecycle, exec, and file CRUD as MCP tools. Run it once on your
+machine, then point any number of MCP clients at it.
+
+### Start the daemon
+
+    pixels mcp
+
+By default it binds to `http://127.0.0.1:8765/mcp` and refuses to start
+if another instance is already running (PID file at
+`~/.cache/pixels/mcp.pid`).
+
+### Configure your client
+
+Claude Code MCP entry:
+
+    {
+      "mcpServers": {
+        "pixels": {
+          "type": "http",
+          "url": "http://127.0.0.1:8765/mcp"
+        }
+      }
+    }
+
+### Tools
+
+| Tool | What it does |
+|---|---|
+| `create_sandbox` | Spin up a new ephemeral container (`base` for fast clone, `image` for raw) |
+| `list_sandboxes` | List tracked sandboxes (with status, error, IP) |
+| `list_bases` | List declared base pixels and their status |
+| `start_sandbox` / `stop_sandbox` / `destroy_sandbox` | Lifecycle |
+| `exec` | Run a command inside a sandbox |
+| `write_file` | Create or fully overwrite a file |
+| `read_file` | Read a file (optional truncation via `max_bytes`) |
+| `edit_file` | Replace `old_string` with `new_string` (with optional `replace_all`) |
+| `delete_file` | Remove a file |
+| `list_files` | List directory contents (optionally recursive) |
+
+### Base pixels
+
+A base is a container that sandboxes clone from. Bases are declared in
+config (or shipped as defaults) and built on demand.
+
+Three bases ship out of the box:
+
+- `dev` — Ubuntu 24.04 + git, curl, wget, jq, vim, build-essential
+- `python` — `dev` + python3, pip, pipx, venv
+- `node` — `dev` + Node 22 LTS, npm
+
+Add your own in config. Each base must declare exactly one of `parent_image` or `from`:
+
+```toml
+[mcp.bases.rust]
+parent_image = "ubuntu/24.04"
+setup_script = "~/.config/pixels/bases/rust.sh"
+description  = "Rust toolchain"
+```
+
+Or build on top of another base:
+
+```toml
+[mcp.bases.rust-dev]
+from = "dev"
+setup_script = "~/.config/pixels/bases/rust-dev.sh"
+description  = "Rust toolchain + dev tools"
+```
+
+Bases form a DAG via `from`. Cycle / missing-dep / both-set / neither-set
+are rejected at config load.
+
+Customise a base by mutating its container:
+
+```bash
+pixels start px-base-python
+pixels exec px-base-python -- apt install vim
+pixels stop px-base-python
+pixels checkpoint create px-base-python
+```
+
+The next `create_sandbox(base="python")` call clones from the new
+checkpoint. Existing sandboxes are unaffected (independent containers).
+
+**Checkpoint-advances-clone-source.** Any `pixels checkpoint create px-base-X`
+immediately advances the snapshot that future sandboxes clone from. If you take
+a *safety* checkpoint before mutating, new sandboxes will clone from that
+pre-mutation state until you take another checkpoint *after* the changes. Always
+re-checkpoint after mutating to ensure new clones pick up your changes.
+
+**Mutation-propagation gotcha.** Changes to `dev` do NOT auto-flow into
+`python` or `node`. Both are independent containers built when `dev` was
+in its prior state. To propagate: `pixels destroy px-base-python &&
+pixels base build python`. Same semantics as Docker layered images.
+
+CLI:
+
+| Command | Action |
+|---|---|
+| `pixels base list` | Show declared bases + status |
+| `pixels base build <name>` | Build the base; cascade-builds missing deps |
+| `pixels destroy px-base-<name>` | Delete a base (existing CLI) |
+| `pixels checkpoint create px-base-<name>` | Publish a new state for clones |
+
+Example `pixels base list` output:
+
+```
+$ pixels base list
+NAME    FROM/IMAGE              STATUS  LAST_CHECKPOINT       DESCRIPTION
+dev     ubuntu/24.04            ready   2026-04-27 12:30:00   Ubuntu 24.04 + git, curl, vim, ...
+node    dev                     missing                       dev + Node 22 LTS, npm
+python  dev                     ready   2026-04-27 12:35:00   dev + python3, pip, pipx, venv
+```
+
+**Force rebuild.** There is no `pixels base rebuild` command. To force a full
+rebuild of a base, run `pixels destroy px-base-<name> && pixels base build <name>`.
+
+### Provisioning is async
+
+`create_sandbox` returns immediately with `status: "provisioning"`.
+The agent should poll `list_sandboxes` until status flips to `running`
+or `failed`. A failed sandbox includes an `error` field describing
+what went wrong.
+
+For simple use without a base, provisioning takes ~30s. With a built
+base, ~5s. With an unbuilt base, several minutes (the build runs
+behind the scenes).
+
+### Lifetimes
+
+Two TTLs apply (configurable in `[mcp]` config):
+
+- `idle_stop_after` (default 1h) — running sandbox with no recent
+  activity gets stopped.
+- `hard_destroy_after` (default 24h) — any sandbox older than this is
+  destroyed and removed from state.
+
 ## Security
 
 Container egress filtering uses nftables rules inside the container. A root process with `cap_net_admin` could bypass these rules. The `pixel` user has restricted sudo that only permits safe-apt, dpkg-query, systemctl, journalctl, and nft list.

cmd/base.go

@@ -0,0 +1,189 @@
+package cmd
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"path/filepath"
+	"slices"
+	"time"
+
+	"github.com/briandowns/spinner"
+	mcppkg "github.com/deevus/pixels/internal/mcp"
+	"github.com/spf13/cobra"
+)
+
+var baseCmd = &cobra.Command{
+	Use:   "base",
+	Short: "Manage pixel bases (templates that sandboxes clone from)",
+}
+
+var baseListCmd = &cobra.Command{
+	Use:   "list",
+	Short: "List declared bases and their status",
+	RunE:  runBaseList,
+}
+
+var baseBuildCmd = &cobra.Command{
+	Use:   "build <name>",
+	Short: "Build a base from its setup script (cascade-builds dependencies if missing)",
+	Args:  cobra.ExactArgs(1),
+	RunE:  runBaseBuild,
+}
+
+func init() {
+	baseCmd.AddCommand(baseListCmd)
+	baseCmd.AddCommand(baseBuildCmd)
+	rootCmd.AddCommand(baseCmd)
+}
+
+func runBaseList(cmd *cobra.Command, args []string) error {
+	if cfg == nil {
+		return fmt.Errorf("config not loaded")
+	}
+	sb, err := openSandbox()
+	if err != nil {
+		return err
+	}
+	defer sb.Close()
+
+	// Load state from disk to check for build failures.
+	state, err := mcppkg.LoadState(cfg.MCPStateFile())
+	if err != nil {
+		return err
+	}
+
+	// Collect and sort base names for deterministic output.
+	names := make([]string, 0, len(cfg.MCP.Bases))
+	for name := range cfg.MCP.Bases {
+		names = append(names, name)
+	}
+	slices.Sort(names)
+
+	w := newTabWriter(cmd)
+	defer w.Flush()
+	fmt.Fprintln(w, "NAME\tFROM/IMAGE\tSTATUS\tLAST_CHECKPOINT\tDESCRIPTION")
+
+	for _, name := range names {
+		b := cfg.MCP.Bases[name]
+		container := mcppkg.BaseName(cfg, name)
+		fromOrImage := b.ParentImage
+		if b.From != "" {
+			fromOrImage = "from:" + b.From
+		}
+
+		var status, lastChk string
+		// Check container existence.
+		_, err := sb.Get(context.Background(), container)
+		if err != nil {
+			status = "missing"
+		} else {
+			status = "ready"
+			if latest, ok, err := mcppkg.LatestCheckpointFor(context.Background(), sb, container); err == nil && ok {
+				lastChk = latest.CreatedAt.UTC().Format("2006-01-02 15:04:05Z")
+			}
+		}
+
+		// Check for cached build failures in the on-disk state.
+		// A failed sandbox indicates a prior build failure.
+		if sbState, ok := state.Get(container); ok && sbState.Status == "failed" {
+			status = "failed"
+		}
+
+		fmt.Fprintf(w, "%s\t%s\t%s\t%s\t%s\n", name, fromOrImage, status, lastChk, b.Description)
+	}
+	return nil
+}
+
+func runBaseBuild(cmd *cobra.Command, args []string) error {
+	name := args[0]
+	if cfg == nil {
+		return fmt.Errorf("config not loaded")
+	}
+	if _, ok := cfg.MCP.Bases[name]; !ok {
+		return fmt.Errorf("base %q not declared in config", name)
+	}
+	sb, err := openSandbox()
+	if err != nil {
+		return err
+	}
+	defer sb.Close()
+
+	stderr := cmd.ErrOrStderr()
+
+	// Spinner for non-verbose mode — shows current phase on stderr.
+	var spin *spinner.Spinner
+	if !verbose {
+		spin = spinner.New(spinner.CharSets[14], 100*time.Millisecond, spinner.WithWriter(stderr))
+	}
+	setStatus := func(msg string) {
+		if spin != nil {
+			spin.Suffix = "  " + msg
+			if !spin.Active() {
+				spin.Start()
+			}
+		}
+	}
+	stopSpinner := func() {
+		if spin != nil && spin.Active() {
+			spin.Stop()
+		}
+	}
+	defer stopSpinner()
+
+	exists := func(container string) bool {
+		_, err := sb.Get(context.Background(), container)
+		return err == nil
+	}
+
+	build := func(baseName string) error {
+		baseCfg := cfg.MCP.Bases[baseName]
+
+		// File-lock per base name across CLI vs daemon.
+		lockDir := filepath.Dir(cfg.MCPStateFile())
+		bl, err := mcppkg.AcquireBuildLock(lockDir, baseName)
+		if err != nil {
+			return err
+		}
+		defer bl.Release()
+
+		// Cascade-build header (visible in both modes).
+		stopSpinner()
+		fmt.Fprintf(stderr, "==> Building base %s...\n", baseName)
+
+		// Choose Out writer + Progress callback per verbose mode.
+		var out io.Writer
+		var captured *bytes.Buffer
+		var progress func(string)
+		if verbose {
+			out = stderr
+			progress = func(phase string) { fmt.Fprintf(stderr, "==> %s\n", phase) }
+		} else {
+			captured = &bytes.Buffer{}
+			out = captured
+			progress = setStatus
+		}
+
+		start := time.Now()
+		err = mcppkg.BuildBase(context.Background(), sb, cfg, baseName, baseCfg, mcppkg.BuildBaseOpts{
+			Out:      out,
+			Progress: progress,
+		})
+		stopSpinner()
+		if err != nil {
+			// In non-verbose mode, dump captured script output before the error so the user
+			// can see why the script failed.
+			if captured != nil && captured.Len() > 0 {
+				fmt.Fprintln(stderr, "--- captured output ---")
+				_, _ = io.Copy(stderr, captured)
+				fmt.Fprintln(stderr, "--- end output ---")
+			}
+			return err
+		}
+		fmt.Fprintf(stderr, "Built %s in %s\n", baseName, time.Since(start).Truncate(100*time.Millisecond))
+		return nil
+	}
+
+	return mcppkg.BuildChain(context.Background(), cfg, name, exists, build)
+}

cmd/create.go

@@ -122,36 +122,15 @@ func runCreate(cmd *cobra.Command, args []string) error {
 			setStatus(fmt.Sprintf("Cloning from %s checkpoint %q...", fromSource, fromLabel))
 		}
 
-		// Create a bare container (no provisioning/SSH wait) — we'll replace its rootfs.
-		logv(cmd, "Creating bare container %s...", name)
-		_, err := sb.Create(ctx, sandbox.CreateOpts{
-			Name:   name,
-			Image:  image,
-			CPU:    cpu,
-			Memory: memory * 1024 * 1024,
-			Bare:   true,
-		})
-		if err != nil {
-			return fmt.Errorf("creating instance: %w", err)
-		}
-
-		logv(cmd, "Stopping %s for rootfs replacement...", name)
-		if err := sb.Stop(ctx, name); err != nil {
-			return fmt.Errorf("stopping %s for clone: %w", name, err)
-		}
-
-		logv(cmd, "Cloning snapshot %s:%s...", fromSource, fromLabel)
+		logv(cmd, "Cloning from %s:%s...", fromSource, fromLabel)
 		if err := sb.CloneFrom(ctx, fromSource, fromLabel, name); err != nil {
-			_ = sb.Delete(ctx, name)
-			return fmt.Errorf("cloning checkpoint: %w", err)
-		}
-
-		if err := sb.Start(ctx, name); err != nil {
-			return fmt.Errorf("starting %s: %w", name, err)
+			return fmt.Errorf("cloning from %s: %w", fromSource, err)
 		}
 
 		setStatus("Waiting for SSH...")
-		_ = sb.Ready(ctx, name, 30*time.Second)
+		if err := sb.Ready(ctx, name, 30*time.Second); err != nil {
+			return fmt.Errorf("waiting for %s: %w", name, err)
+		}
 	} else {
 		// Normal create flow — sandbox handles provisioning, IP poll, SSH wait.
 		setStatus("Creating...")