feat: add proxy extension

README.md

@@ -143,6 +143,93 @@ You can use the embedded live view to monitor and control the browser. The live
 - Audio streaming in the WebRTC implementation is currently non-functional and needs to be fixed.
 - The live view is read/write by default. You can set it to read-only by adding `-e ENABLE_READONLY_VIEW=true \` in `docker run`.
 
+## Proxy Configuration
+
+The headful image supports configuring an HTTP/SOCKS proxy for the browser using a Chrome extension. This is useful for:
+- Using residential/datacenter proxies (e.g., Bright Data, Oxylabs)
+- Geo-targeting specific locations
+- Rotating IP addresses
+
+### Quick Start
+
+1. **Start the container:**
+```bash
+cd images/chromium-headful
+IMAGE=kernel-docker ENABLE_WEBRTC=true ./run-docker.sh
+```
+
+2. **Upload the proxy extension:**
+```bash
+# Create zip from the extension folder (files must be at root level, not in a subdirectory)
+cd brightdata-proxy-extension && zip -r ../proxy-extension.zip . && cd ..
+
+# Upload via API
+curl -X POST "http://localhost:444/chromium/upload-extensions-and-restart" \
+  -F "extensions.zip_file=@proxy-extension.zip;filename=ext.zip" \
+  -F "extensions.name=proxy-extension"
+```
+
+3. **Configure the proxy:**
+```bash
+curl -X PUT http://localhost:444/proxy/config \
+  -H "Content-Type: application/json" \
+  -d '{
+    "host": "brd.superproxy.io",
+    "port": 33335,
+    "username": "brd-customer-XXXXX-zone-XXXXX",
+    "password": "your-password",
+    "scheme": "http"
+  }'
+```
+
+4. **Restart Chromium to apply:**
+```bash
+docker exec <container-name> supervisorctl restart chromium
+```
+
+### Geo-targeting
+
+Append the country code to the username for geo-targeting:
+
+| Country | Username Suffix |
+|---------|-----------------|
+| India | `-country-in` |
+| United States | `-country-us` |
+| United Kingdom | `-country-gb` |
+| Germany | `-country-de` |
+
+Example:
+```json
+"username": "brd-customer-XXXXX-zone-XXXXX-country-in"
+```
+
+### API Reference
+
+```bash
+# Set proxy configuration
+curl -X PUT http://localhost:444/proxy/config \
+  -H "Content-Type: application/json" \
+  -d '{
+    "host": "brd.superproxy.io",
+    "port": 33335,
+    "username": "brd-customer-XXXXX-zone-XXXXX",
+    "password": "your-password",
+    "scheme": "http"
+  }'
+
+# Get current proxy configuration
+curl http://localhost:444/proxy/config
+
+# Disable proxy
+curl -X DELETE http://localhost:444/proxy/config
+```
+
+### Notes
+- Port `444` maps to the kernel-images API (internal port `10001`)
+- After updating proxy config, restart Chromium for the extension to apply changes
+- Supported schemes: `http`, `https`, `socks4`, `socks5`
+- Default bypass list: `["localhost", "127.0.0.1"]`
+
 ## Replay Capture
 
 You can use the embedded recording server to capture recordings of the entire screen in our headful images. It allows for one recording at a time and can be enabled with `WITH_KERNEL_IMAGES_API=true`

brightdata-proxy-extension/background.js

@@ -0,0 +1,78 @@
+// Bright Data Proxy Extension - API Configured
+const CONFIG_URL = "http://127.0.0.1:10001/proxy/config";
+
+let proxyConfig = null;
+
+// Fetch proxy configuration from API
+async function fetchProxyConfig() {
+  try {
+    const response = await fetch(CONFIG_URL);
+    if (!response.ok) {
+      console.error("Failed to fetch proxy config:", response.status);
+      return null;
+    }
+    return await response.json();
+  } catch (error) {
+    console.error("Error fetching proxy config:", error);
+    return null;
+  }
+}
+
+// Apply proxy settings
+function applyProxySettings(config) {
+  if (!config || !config.host || !config.port) {
+    console.log("No valid proxy config, disabling proxy");
+    chrome.proxy.settings.clear({ scope: "regular" });
+    return;
+  }
+
+  proxyConfig = config;
+
+  chrome.proxy.settings.set({
+    value: {
+      mode: "fixed_servers",
+      rules: {
+        singleProxy: {
+          scheme: config.scheme || "http",
+          host: config.host,
+          port: config.port
+        },
+        bypassList: config.bypassList || ["localhost", "127.0.0.1"]
+      }
+    },
+    scope: "regular"
+  }, () => {
+    console.log("Proxy configured:", config.host + ":" + config.port);
+  });
+}
+
+// Handle proxy authentication
+chrome.webRequest.onAuthRequired.addListener(
+  (details, callbackFn) => {
+    if (proxyConfig && proxyConfig.username && proxyConfig.password) {
+      console.log("Auth required, providing credentials");
+      callbackFn({
+        authCredentials: {
+          username: proxyConfig.username,
+          password: proxyConfig.password
+        }
+      });
+    } else {
+      console.log("Auth required but no credentials available");
+      callbackFn({ cancel: false });
+    }
+  },
+  { urls: ["<all_urls>"] },
+  ["asyncBlocking"]
+);
+
+// Initialize proxy configuration
+async function init() {
+  const config = await fetchProxyConfig();
+  if (config) {
+    applyProxySettings(config);
+  }
+}
+
+init();
+console.log("Bright Data Proxy Extension loaded (API-configured)");

brightdata-proxy-extension/manifest.json

@@ -0,0 +1,17 @@
+{
+  "name": "Bright Data Proxy Auth",
+  "version": "1.0.0",
+  "manifest_version": 3,
+  "description": "Proxy authentication for Bright Data",
+  "permissions": [
+    "proxy",
+    "webRequest",
+    "webRequestAuthProvider"
+  ],
+  "host_permissions": [
+    "<all_urls>"
+  ],
+  "background": {
+    "service_worker": "background.js"
+  }
+}

images/chromium-headful/run-docker.sh

@@ -19,6 +19,13 @@ if [[ "$RUN_AS_ROOT" == "true" ]]; then
   CHROMIUM_FLAGS_DEFAULT="$CHROMIUM_FLAGS_DEFAULT --no-sandbox --no-zygote"
 fi
 CHROMIUM_FLAGS="${CHROMIUM_FLAGS:-$CHROMIUM_FLAGS_DEFAULT}"
+
+# Add proxy extension flags if proxy is enabled
+if [[ "${PROXY_ENABLED:-}" == "true" ]]; then
+  echo "Proxy enabled: $PROXY_HOST:$PROXY_PORT"
+  CHROMIUM_FLAGS="$CHROMIUM_FLAGS --load-extension=/home/kernel/extensions/brightdata-proxy --disable-extensions-except=/home/kernel/extensions/brightdata-proxy"
+fi
+
 rm -rf .tmp/chromium
 mkdir -p .tmp/chromium
 FLAGS_FILE="$(pwd)/.tmp/chromium/flags"
@@ -70,6 +77,16 @@ if [[ -n "${PLAYWRIGHT_ENGINE:-}" ]]; then
   RUN_ARGS+=( -e PLAYWRIGHT_ENGINE="$PLAYWRIGHT_ENGINE" )
 fi
 
+# Proxy environment variables
+if [[ "${PROXY_ENABLED:-}" == "true" ]]; then
+  RUN_ARGS+=( -e PROXY_ENABLED=true )
+  RUN_ARGS+=( -e PROXY_HOST="$PROXY_HOST" )
+  RUN_ARGS+=( -e PROXY_PORT="$PROXY_PORT" )
+  [[ -n "$PROXY_USERNAME" ]] && RUN_ARGS+=( -e PROXY_USERNAME="$PROXY_USERNAME" )
+  [[ -n "$PROXY_PASSWORD" ]] && RUN_ARGS+=( -e PROXY_PASSWORD="$PROXY_PASSWORD" )
+  [[ -n "$PROXY_SCHEME" ]] && RUN_ARGS+=( -e PROXY_SCHEME="$PROXY_SCHEME" )
+fi
+
 # WebRTC port mapping
 if [[ "${ENABLE_WEBRTC:-}" == "true" ]]; then
   echo "Running container with WebRTC"

server/cmd/api/api/proxy.go

@@ -0,0 +1,138 @@
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"sync"
+
+	"github.com/onkernel/kernel-images/server/lib/logger"
+	oapi "github.com/onkernel/kernel-images/server/lib/oapi"
+)
+
+const proxyConfigPath = "/chromium/proxy-config.json"
+
+var (
+	proxyConfigMu sync.RWMutex
+	proxyConfig   *oapi.ProxyConfig
+)
+
+// GetProxyConfig returns the current proxy configuration.
+func (s *ApiService) GetProxyConfig(ctx context.Context, _ oapi.GetProxyConfigRequestObject) (oapi.GetProxyConfigResponseObject, error) {
+	log := logger.FromContext(ctx)
+
+	proxyConfigMu.RLock()
+	defer proxyConfigMu.RUnlock()
+
+	// If we have a cached config, return it
+	if proxyConfig != nil {
+		log.Info("returning cached proxy config", "host", stringVal(proxyConfig.Host))
+		return oapi.GetProxyConfig200JSONResponse(*proxyConfig), nil
+	}
+
+	// Try to load from file
+	data, err := os.ReadFile(proxyConfigPath)
+	if err != nil {
+		if os.IsNotExist(err) {
+			// Return empty config if file doesn't exist
+			log.Info("no proxy config found, returning empty config")
+			return oapi.GetProxyConfig200JSONResponse(oapi.ProxyConfig{}), nil
+		}
+		log.Error("failed to read proxy config", "error", err)
+		return oapi.GetProxyConfig500JSONResponse{InternalErrorJSONResponse: oapi.InternalErrorJSONResponse{Message: "failed to read proxy config"}}, nil
+	}
+
+	var cfg oapi.ProxyConfig
+	if err := json.Unmarshal(data, &cfg); err != nil {
+		log.Error("failed to parse proxy config", "error", err)
+		return oapi.GetProxyConfig500JSONResponse{InternalErrorJSONResponse: oapi.InternalErrorJSONResponse{Message: "failed to parse proxy config"}}, nil
+	}
+
+	log.Info("returning proxy config from file", "host", stringVal(cfg.Host))
+	return oapi.GetProxyConfig200JSONResponse(cfg), nil
+}
+
+// SetProxyConfig sets the proxy configuration.
+func (s *ApiService) SetProxyConfig(ctx context.Context, request oapi.SetProxyConfigRequestObject) (oapi.SetProxyConfigResponseObject, error) {
+	log := logger.FromContext(ctx)
+
+	if request.Body == nil {
+		return oapi.SetProxyConfig400JSONResponse{BadRequestErrorJSONResponse: oapi.BadRequestErrorJSONResponse{Message: "request body required"}}, nil
+	}
+
+	cfg := request.Body
+
+	// Validate required fields
+	if cfg.Host == nil || *cfg.Host == "" {
+		return oapi.SetProxyConfig400JSONResponse{BadRequestErrorJSONResponse: oapi.BadRequestErrorJSONResponse{Message: "host is required"}}, nil
+	}
+	if cfg.Port == nil || *cfg.Port == 0 {
+		return oapi.SetProxyConfig400JSONResponse{BadRequestErrorJSONResponse: oapi.BadRequestErrorJSONResponse{Message: "port is required"}}, nil
+	}
+
+	// Set default scheme if not provided
+	if cfg.Scheme == nil {
+		defaultScheme := oapi.Http
+		cfg.Scheme = &defaultScheme
+	}
+
+	// Set default bypass list if not provided
+	if cfg.BypassList == nil {
+		cfg.BypassList = &[]string{"localhost", "127.0.0.1"}
+	}
+
+	proxyConfigMu.Lock()
+	defer proxyConfigMu.Unlock()
+
+	// Save to file
+	data, err := json.MarshalIndent(cfg, "", "  ")
+	if err != nil {
+		log.Error("failed to marshal proxy config", "error", err)
+		return oapi.SetProxyConfig500JSONResponse{InternalErrorJSONResponse: oapi.InternalErrorJSONResponse{Message: "failed to marshal proxy config"}}, nil
+	}
+
+	// Ensure the directory exists
+	if err := os.MkdirAll("/chromium", 0o755); err != nil {
+		log.Error("failed to create chromium dir", "error", err)
+		return oapi.SetProxyConfig500JSONResponse{InternalErrorJSONResponse: oapi.InternalErrorJSONResponse{Message: "failed to create chromium dir"}}, nil
+	}
+
+	if err := os.WriteFile(proxyConfigPath, data, 0o644); err != nil {
+		log.Error("failed to write proxy config", "error", err)
+		return oapi.SetProxyConfig500JSONResponse{InternalErrorJSONResponse: oapi.InternalErrorJSONResponse{Message: "failed to write proxy config"}}, nil
+	}
+
+	// Update cache
+	proxyConfig = cfg
+
+	log.Info("proxy config saved", "host", *cfg.Host, "port", *cfg.Port)
+	return oapi.SetProxyConfig200JSONResponse(*cfg), nil
+}
+
+// DeleteProxyConfig clears the proxy configuration.
+func (s *ApiService) DeleteProxyConfig(ctx context.Context, _ oapi.DeleteProxyConfigRequestObject) (oapi.DeleteProxyConfigResponseObject, error) {
+	log := logger.FromContext(ctx)
+
+	proxyConfigMu.Lock()
+	defer proxyConfigMu.Unlock()
+
+	// Clear cache
+	proxyConfig = nil
+
+	// Remove file
+	if err := os.Remove(proxyConfigPath); err != nil && !os.IsNotExist(err) {
+		log.Error("failed to remove proxy config file", "error", err)
+		return oapi.DeleteProxyConfig500JSONResponse{InternalErrorJSONResponse: oapi.InternalErrorJSONResponse{Message: "failed to remove proxy config file"}}, nil
+	}
+
+	log.Info("proxy config cleared")
+	return oapi.DeleteProxyConfig204Response{}, nil
+}
+
+// stringVal returns the value of a string pointer or empty string if nil
+func stringVal(s *string) string {
+	if s == nil {
+		return ""
+	}
+	return *s
+}

server/go.mod

@@ -13,6 +13,7 @@ require (
 	github.com/go-chi/chi/v5 v5.2.1
 	github.com/google/uuid v1.6.0
 	github.com/kelseyhightower/envconfig v1.4.0
+	github.com/klauspost/compress v1.18.3
 	github.com/m1k1o/neko/server v0.0.0-20251008185748-46e2fc7d3866
 	github.com/nrednav/cuid2 v1.1.0
 	github.com/oapi-codegen/runtime v1.1.2
@@ -33,7 +34,6 @@ require (
 	github.com/jinzhu/inflection v1.0.0 // indirect
 	github.com/jinzhu/now v1.1.5 // indirect
 	github.com/josharian/intern v1.0.0 // indirect
-	github.com/klauspost/compress v1.18.3 // indirect
 	github.com/mailru/easyjson v0.7.7 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 // indirect