Merge branch 'main' into fix-video-sync

Author: rgarcia

AGENTS.md

@@ -0,0 +1,44 @@
+# AGENTS.md
+
+## Cursor Cloud specific instructions
+
+### Project overview
+
+Kernel Images is a sandboxed cloud browser infrastructure platform. The Go server (under `server/`) provides a REST API for screen recording, process execution, file management, and a CDP (Chrome DevTools Protocol) WebSocket proxy. Everything runs inside a single Docker container orchestrated by supervisord.
+
+### Development commands
+
+- **Lint**: `cd server && go vet ./...`
+- **Unit tests** (skip e2e): `cd server && go test -v -race $(go list ./... | grep -v /e2e$)`
+- **Full tests** (requires Docker + pre-built images): `cd server && make test`
+- **Build server**: `cd server && make build`
+- **Build headless image**: `cd /workspace && DOCKER_BUILDKIT=1 docker build -f images/chromium-headless/image/Dockerfile -t kernel-headless-test .`
+- **Run headless container**: `docker run -d --name kernel-headless -p 10001:10001 -p 9222:9222 --shm-size=2g kernel-headless-test`
+- See `server/README.md` and `server/Makefile` for additional commands and configuration.
+
+### Docker in Cloud VM
+
+The Cloud VM runs inside a Firecracker microVM. Docker requires:
+- `fuse-overlayfs` storage driver (configured in `/etc/docker/daemon.json`)
+- `iptables-legacy` (not nftables)
+- Start daemon with `sudo dockerd &>/tmp/dockerd.log &` then `sudo chmod 666 /var/run/docker.sock`
+
+### Key gotchas
+
+1. **`UKC_METRO` must be the full API URL** (e.g., `https://api.<region>.<domain>/v1`), not just the metro short name. The kraft CLI defaults to `*.kraft.cloud` but this org uses a custom domain — check the `UKC_METRO` environment variable for the correct value.
+
+2. **Some kraft cloud subcommands need `--metro "<full-url>"` explicitly** even when the `UKC_METRO` env var is set.
+
+3. **CDP proxy on port 9222 routes ALL WebSocket connections to the browser-level endpoint** (ignores request path). Use `Target.createTarget` + `Target.attachToTarget` with `flatten: true` for page-level interaction. Playwright/Puppeteer handle this automatically.
+
+4. **The default recorder cannot be restarted after stop+delete within the same process lifetime.** Restart the container or use a custom `recorder_id`.
+
+5. **The server (`make dev`) only runs inside the Docker container** — it exits on bare host because it waits for Chromium devtools upstream on port 9223.
+
+6. **Image naming convention**: Cursor Cloud agents use `onkernel/cursor-agent-<type>:latest` for test images pushed to KraftCloud. Always check quota with `kraft cloud quota` before pushing. Never auto-delete images — present them to the user for approval.
+
+7. **Image storage quota is tight** (~80 GiB limit). Old `kernel-cu` and `chromium-headless` versions consume most of it.
+
+8. **E2e tests** use `testcontainers-go` and require Docker + pre-built images. Set `E2E_CHROMIUM_HEADFUL_IMAGE` and `E2E_CHROMIUM_HEADLESS_IMAGE` env vars to point to the correct image tags.
+
+9. **Go version**: The project requires Go 1.25.0 (per `server/go.mod`). The system Go may be older — ensure `/usr/local/go/bin` is on PATH.

images/chromium-headless/image/Dockerfile

@@ -136,6 +136,7 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked,id=$CACHEIDPREFIX-ap
     dbus-x11 \
     xvfb \
     x11-utils \
+    xclip \
     xdotool \
     fontconfig \
     fonts-noto-cjk \

server/cmd/api/api/computer.go

@@ -1136,6 +1136,54 @@ func clampPoints(points [][2]int, screenWidth, screenHeight int) {
 	}
 }
 
+func (s *ApiService) ReadClipboard(ctx context.Context, request oapi.ReadClipboardRequestObject) (oapi.ReadClipboardResponseObject, error) {
+	log := logger.FromContext(ctx)
+
+	s.inputMu.Lock()
+	defer s.inputMu.Unlock()
+
+	display := s.resolveDisplayFromEnv()
+	cmd := exec.CommandContext(ctx, "xclip", "-selection", "clipboard", "-o")
+	cmd.Env = append(os.Environ(), fmt.Sprintf("DISPLAY=%s", display))
+	output, err := cmd.Output()
+	if err != nil {
+		var exitErr *exec.ExitError
+		if errors.As(err, &exitErr) && exitErr.ExitCode() == 1 {
+			return oapi.ReadClipboard200JSONResponse{Text: ""}, nil
+		}
+		log.Error("xclip read failed", "err", err)
+		return oapi.ReadClipboard500JSONResponse{InternalErrorJSONResponse: oapi.InternalErrorJSONResponse{
+			Message: fmt.Sprintf("failed to read clipboard: %v", err)},
+		}, nil
+	}
+	return oapi.ReadClipboard200JSONResponse{Text: string(output)}, nil
+}
+
+func (s *ApiService) WriteClipboard(ctx context.Context, request oapi.WriteClipboardRequestObject) (oapi.WriteClipboardResponseObject, error) {
+	log := logger.FromContext(ctx)
+
+	s.inputMu.Lock()
+	defer s.inputMu.Unlock()
+
+	if request.Body == nil {
+		return oapi.WriteClipboard400JSONResponse{BadRequestErrorJSONResponse: oapi.BadRequestErrorJSONResponse{
+			Message: "request body is required"},
+		}, nil
+	}
+
+	display := s.resolveDisplayFromEnv()
+	cmd := exec.CommandContext(ctx, "xclip", "-selection", "clipboard")
+	cmd.Env = append(os.Environ(), fmt.Sprintf("DISPLAY=%s", display))
+	cmd.Stdin = strings.NewReader(request.Body.Text)
+	if err := cmd.Run(); err != nil {
+		log.Error("xclip write failed", "err", err)
+		return oapi.WriteClipboard500JSONResponse{InternalErrorJSONResponse: oapi.InternalErrorJSONResponse{
+			Message: fmt.Sprintf("failed to write to clipboard: %v", err)},
+		}, nil
+	}
+	return oapi.WriteClipboard200Response{}, nil
+}
+
 // generateRelativeSteps produces a sequence of relative steps that approximate a
 // straight line from (0,0) to (dx,dy) using at most the provided number of
 // steps. Each returned element is a pair {stepX, stepY}. The steps are

server/e2e/e2e_chromium_test.go

@@ -169,6 +169,43 @@ func TestDisplayResolutionChange(t *testing.T) {
 	t.Log("all resolution changes verified successfully")
 }
 
+func TestClipboardHeadless(t *testing.T) {
+	t.Parallel()
+
+	if _, err := exec.LookPath("docker"); err != nil {
+		t.Skipf("docker not available: %v", err)
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Minute)
+	defer cancel()
+
+	c := NewTestContainer(t, headlessImage)
+	require.NoError(t, c.Start(ctx, ContainerConfig{}), "failed to start container")
+	defer c.Stop(ctx)
+
+	require.NoError(t, c.WaitReady(ctx), "api not ready")
+
+	specResp, err := http.Get(c.APIBaseURL() + "/spec.yaml")
+	require.NoError(t, err)
+	specBody, _ := io.ReadAll(specResp.Body)
+	specResp.Body.Close()
+	require.True(t, strings.Contains(string(specBody), "/computer/clipboard/write"),
+		"API spec does not include clipboard routes - rebuild the image with: cd kernel-images/images/chromium-headless && docker build --no-cache -f image/Dockerfile -t %s ../..", headlessImage)
+
+	client, err := c.APIClient()
+	require.NoError(t, err, "failed to create API client")
+
+	writeResp, err := client.WriteClipboardWithResponse(ctx, instanceoapi.WriteClipboardRequest{Text: "e2e-clipboard-test"})
+	require.NoError(t, err, "WriteClipboard request failed")
+	require.Equal(t, http.StatusOK, writeResp.StatusCode(), "unexpected write status: %s body=%s", writeResp.Status(), string(writeResp.Body))
+
+	readResp, err := client.ReadClipboardWithResponse(ctx)
+	require.NoError(t, err, "ReadClipboard request failed")
+	require.Equal(t, http.StatusOK, readResp.StatusCode(), "unexpected read status: %s body=%s", readResp.Status(), string(readResp.Body))
+	require.NotNil(t, readResp.JSON200, "expected JSON200 response")
+	require.Equal(t, "e2e-clipboard-test", readResp.JSON200.Text, "clipboard content mismatch")
+}
+
 func TestExtensionUploadAndActivation(t *testing.T) {
 	t.Parallel()
 	ensurePlaywrightDeps(t)