Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

feat: no-instance strategy for hub-only deployments (#328)

luigiagent85e498c43cbe
diff --git a/dashboard/src/pages/SettingsPage.tsx b/dashboard/src/pages/SettingsPage.tsx
index 5b3d94c3..f901902b 100644
--- a/dashboard/src/pages/SettingsPage.tsx
+++ b/dashboard/src/pages/SettingsPage.tsx
@@ -901,7 +901,7 @@ export default function SettingsPage() {
>
<SettingRow
label="Strategy"
- description="Controls how shorthand routes are routed in dashboard mode."
+ description="Controls instance lifecycle and how shorthand routes are routed."
>
<select
value={backendConfig.multiInstance.strategy}
@@ -919,7 +919,21 @@ export default function SettingsPage() {
<option value="simple-autorestart">
Simple autorestart
</option>
+ <option value="no-instance">No instance (hub)</option>
</select>
+ <div className="mt-2 text-[11px] leading-relaxed text-text-muted">
+ {backendConfig.multiInstance.strategy === "always-on" &&
+ "Launches a default instance at boot and relaunches on crash."}
+ {backendConfig.multiInstance.strategy === "simple" &&
+ "Launches one instance on first request. No auto-restart."}
+ {backendConfig.multiInstance.strategy === "explicit" &&
+ "All instances managed via API. No automatic launches."}
+ {backendConfig.multiInstance.strategy ===
+ "simple-autorestart" &&
+ "Launches on first request and relaunches on crash."}
+ {backendConfig.multiInstance.strategy === "no-instance" &&
+ "No local Chrome processes. Acts as a hub for remote bridges only."}
+ </div>
</SettingRow>
<SettingRow
label="Allocation policy"
diff --git a/dashboard/src/types/index.ts b/dashboard/src/types/index.ts
index 4681ae54..1657e628 100644
--- a/dashboard/src/types/index.ts
+++ b/dashboard/src/types/index.ts
@@ -99,7 +99,12 @@ export interface BackendProfilesConfig {
}
export interface BackendMultiInstanceConfig {
- strategy: "simple" | "explicit" | "simple-autorestart" | "always-on";
+ strategy:
+ | "simple"
+ | "explicit"
+ | "simple-autorestart"
+ | "always-on"
+ | "no-instance";
allocationPolicy: "fcfs" | "round_robin" | "random";
instancePortStart: number;
instancePortEnd: number;
diff --git a/docs/guides/remote-bridge-orchestrator.md b/docs/guides/remote-bridge-orchestrator.md
index 49450db0..afd18513 100644
--- a/docs/guides/remote-bridge-orchestrator.md
+++ b/docs/guides/remote-bridge-orchestrator.md
@@ -295,6 +295,22 @@ The supported model is:
---
+## Hub-Only Mode
+
+If you only want remote bridges and never want local Chrome, use the `no-instance` strategy:
+
+```json
+{
+ "multiInstance": {
+ "strategy": "no-instance"
+ }
+}
+```
+
+This blocks all local launch endpoints and starts the server as a pure hub. Remote bridges attach via `POST /instances/attach-bridge` and shorthand routes proxy to the first connected bridge.
+
+---
+
## Summary
Use `POST /instances/attach-bridge` when you want:
@@ -304,4 +320,6 @@ Use `POST /instances/attach-bridge` when you want:
- agents still talking only to machine A
- remote browser work without remote process-management complexity
+Use `no-instance` strategy when you want a dedicated hub that never launches local Chrome.
+
This is the right feature when you want distributed execution with a single control plane.
diff --git a/docs/reference/config.md b/docs/reference/config.md
index e15f7c30..15071ee4 100644
--- a/docs/reference/config.md
+++ b/docs/reference/config.md
@@ -353,7 +353,7 @@ Valid enum values:
| `instanceDefaults.mode` | `headless`, `headed` |
| `instanceDefaults.stealthLevel` | `light`, `medium`, `full` |
| `instanceDefaults.tabEvictionPolicy` | `reject`, `close_oldest`, `close_lru` (default) |
-| `multiInstance.strategy` | `simple`, `explicit`, `simple-autorestart`, `always-on` (default) |
+| `multiInstance.strategy` | `simple`, `explicit`, `simple-autorestart`, `always-on` (default), `no-instance` |
| `multiInstance.allocationPolicy` | `fcfs`, `round_robin`, `random` |
| `security.attach.allowSchemes` | `ws`, `wss`, `http`, `https` |
diff --git a/internal/config/validate.go b/internal/config/validate.go
index c80e4f1f..3ea356e8 100644
--- a/internal/config/validate.go
+++ b/internal/config/validate.go
@@ -259,7 +259,7 @@ func isValidEvictionPolicy(policy string) bool {
func isValidStrategy(strategy string) bool {
switch strategy {
- case "simple", "explicit", "simple-autorestart", "always-on":
+ case "simple", "explicit", "simple-autorestart", "always-on", "no-instance":
return true
default:
return false
@@ -293,7 +293,7 @@ func ValidEvictionPolicies() []string {
}
func ValidStrategies() []string {
- return []string{"simple", "explicit", "simple-autorestart", "always-on"}
+ return []string{"simple", "explicit", "simple-autorestart", "always-on", "no-instance"}
}
// validateIDPIConfig validates the security.idpi sub-section.
diff --git a/internal/orchestrator/handlers.go b/internal/orchestrator/handlers.go
index b0244c5c..a3deae9d 100644
--- a/internal/orchestrator/handlers.go
+++ b/internal/orchestrator/handlers.go
@@ -14,9 +14,21 @@ func registerCapabilityRoute(mux *http.ServeMux, route string, enabled bool, fea
mux.HandleFunc(route, httpx.DisabledEndpointHandler(feature, setting, code))
}
+// RegisterHandlersNoLaunch registers all orchestrator handlers except
+// local instance launch endpoints (start, launch). Used by the no-instance strategy.
+func (o *Orchestrator) RegisterHandlersNoLaunch(mux *http.ServeMux) {
+ o.registerHandlers(mux, true)
+}
+
func (o *Orchestrator) RegisterHandlers(mux *http.ServeMux) {
+ o.registerHandlers(mux, false)
+}
+
+func (o *Orchestrator) registerHandlers(mux *http.ServeMux, skipLaunch bool) {
// Profile management
- mux.HandleFunc("POST /profiles/{id}/start", o.handleStartByID)
+ if !skipLaunch {
+ mux.HandleFunc("POST /profiles/{id}/start", o.handleStartByID)
+ }
mux.HandleFunc("POST /profiles/{id}/stop", o.handleStopByID)
mux.HandleFunc("GET /profiles/{id}/instance", o.handleProfileInstance)
@@ -25,11 +37,15 @@ func (o *Orchestrator) RegisterHandlers(mux *http.ServeMux) {
mux.HandleFunc("GET /instances/{id}", o.handleGetInstance)
mux.HandleFunc("GET /instances/tabs", o.handleAllTabs)
mux.HandleFunc("GET /instances/metrics", o.handleAllMetrics)
- mux.HandleFunc("POST /instances/start", o.handleStartInstance)
- mux.HandleFunc("POST /instances/launch", o.handleLaunchByName)
+ if !skipLaunch {
+ mux.HandleFunc("POST /instances/start", o.handleStartInstance)
+ mux.HandleFunc("POST /instances/launch", o.handleLaunchByName)
+ }
mux.HandleFunc("POST /instances/attach", o.handleAttachInstance)
mux.HandleFunc("POST /instances/attach-bridge", o.handleAttachBridge)
- mux.HandleFunc("POST /instances/{id}/start", o.handleStartByInstanceID)
+ if !skipLaunch {
+ mux.HandleFunc("POST /instances/{id}/start", o.handleStartByInstanceID)
+ }
mux.HandleFunc("POST /instances/{id}/stop", o.handleStopByInstanceID)
mux.HandleFunc("GET /instances/{id}/logs", o.handleLogsByID)
mux.HandleFunc("GET /instances/{id}/logs/stream", o.handleLogsStreamByID)
diff --git a/internal/server/server.go b/internal/server/server.go
index 314f4d6e..d74d6566 100644
--- a/internal/server/server.go
+++ b/internal/server/server.go
@@ -28,6 +28,7 @@ import (
_ "github.com/pinchtab/pinchtab/internal/strategy/alwayson"
_ "github.com/pinchtab/pinchtab/internal/strategy/autorestart"
_ "github.com/pinchtab/pinchtab/internal/strategy/explicit"
+ _ "github.com/pinchtab/pinchtab/internal/strategy/noinstance"
_ "github.com/pinchtab/pinchtab/internal/strategy/simple"
)
diff --git a/internal/strategy/noinstance/noinstance.go b/internal/strategy/noinstance/noinstance.go
new file mode 100644
index 00000000..dd8c0fd3
--- /dev/null
+++ b/internal/strategy/noinstance/noinstance.go
@@ -0,0 +1,81 @@
+// Package noinstance implements the "no-instance" strategy.
+// No local browser instances are launched. The server acts as a hub
+// that only accepts remote bridges via /instances/attach-bridge.
+package noinstance
+
+import (
+ "context"
+ "fmt"
+ "net/http"
+
+ "github.com/pinchtab/pinchtab/internal/httpx"
+ "github.com/pinchtab/pinchtab/internal/orchestrator"
+ "github.com/pinchtab/pinchtab/internal/proxy"
+ "github.com/pinchtab/pinchtab/internal/strategy"
+)
+
+func init() {
+ strategy.MustRegister("no-instance", func() strategy.Strategy {
+ return &Strategy{}
+ })
+}
+
+// Strategy accepts only remote bridges — no local Chrome processes.
+type Strategy struct {
+ orch *orchestrator.Orchestrator
+}
+
+func (s *Strategy) Name() string { return "no-instance" }
+
+func (s *Strategy) SetOrchestrator(o *orchestrator.Orchestrator) {
+ s.orch = o
+}
+
+func (s *Strategy) Start(_ context.Context) error { return nil }
+func (s *Strategy) Stop() error { return nil }
+
+func (s *Strategy) RegisterRoutes(mux *http.ServeMux) {
+ // Register orchestrator handlers without local launch endpoints
+ s.orch.RegisterHandlersNoLaunch(mux)
+
+ // Shorthand endpoints proxy to first running (remote) instance
+ shorthandRoutes := []string{
+ "GET /snapshot", "GET /screenshot", "GET /text", "GET /pdf", "POST /pdf",
+ "POST /navigate", "POST /back", "POST /forward", "POST /reload",
+ "POST /action", "POST /actions",
+ "POST /tab", "POST /tab/lock", "POST /tab/unlock",
+ "GET /cookies", "POST /cookies",
+ "GET /stealth/status", "POST /fingerprint/rotate",
+ "POST /find",
+ }
+ for _, route := range shorthandRoutes {
+ mux.HandleFunc(route, s.proxyToFirst)
+ }
+ strategy.RegisterCapabilityRoute(mux, "POST /evaluate", s.orch.AllowsEvaluate(), "evaluate", "security.allowEvaluate", "evaluate_disabled", s.proxyToFirst)
+ strategy.RegisterCapabilityRoute(mux, "GET /download", s.orch.AllowsDownload(), "download", "security.allowDownload", "download_disabled", s.proxyToFirst)
+ strategy.RegisterCapabilityRoute(mux, "POST /upload", s.orch.AllowsUpload(), "upload", "security.allowUpload", "upload_disabled", s.proxyToFirst)
+ strategy.RegisterCapabilityRoute(mux, "GET /screencast", s.orch.AllowsScreencast(), "screencast", "security.allowScreencast", "screencast_disabled", s.proxyToFirst)
+ strategy.RegisterCapabilityRoute(mux, "GET /screencast/tabs", s.orch.AllowsScreencast(), "screencast", "security.allowScreencast", "screencast_disabled", s.proxyToFirst)
+ strategy.RegisterCapabilityRoute(mux, "POST /macro", s.orch.AllowsMacro(), "macro", "security.allowMacro", "macro_disabled", s.proxyToFirst)
+
+ mux.HandleFunc("GET /tabs", s.handleTabs)
+}
+
+func (s *Strategy) proxyToFirst(w http.ResponseWriter, r *http.Request) {
+ target := s.orch.FirstRunningURL()
+ if target == "" {
+ httpx.Error(w, 503, fmt.Errorf("no remote instances connected — attach a bridge first"))
+ return
+ }
+ strategy.EnrichForTarget(r, s.orch, target)
+ proxy.HTTP(w, r, target+r.URL.Path)
+}
+
+func (s *Strategy) handleTabs(w http.ResponseWriter, r *http.Request) {
+ target := s.orch.FirstRunningURL()
+ if target == "" {
+ httpx.JSON(w, 200, map[string]any{"tabs": []any{}})
+ return
+ }
+ proxy.HTTP(w, r, target+"/tabs")
+}
diff --git a/internal/strategy/noinstance/noinstance_test.go b/internal/strategy/noinstance/noinstance_test.go
new file mode 100644
index 00000000..d1080b34
--- /dev/null
+++ b/internal/strategy/noinstance/noinstance_test.go
@@ -0,0 +1,17 @@
+package noinstance
+
+import (
+ "testing"
+
+ "github.com/pinchtab/pinchtab/internal/strategy"
+)
+
+func TestNoInstanceStrategyRegistered(t *testing.T) {
+ s, err := strategy.New("no-instance")
+ if err != nil {
+ t.Fatalf("strategy.New(%q) error = %v", "no-instance", err)
+ }
+ if s.Name() != "no-instance" {
+ t.Fatalf("Name() = %q, want %q", s.Name(), "no-instance")
+ }
+}
diff --git a/scripts/check.sh b/scripts/check.sh
index 638c31e4..1298e241 100755
--- a/scripts/check.sh
+++ b/scripts/check.sh
@@ -78,6 +78,8 @@ section "Lint"
LINT_CMD=""
if command -v golangci-lint >/dev/null 2>&1; then
LINT_CMD="golangci-lint"
+elif [ -x "${GOPATH:-$HOME/go}/bin/golangci-lint" ]; then
+ LINT_CMD="${GOPATH:-$HOME/go}/bin/golangci-lint"
elif [ -x "$HOME/bin/golangci-lint" ]; then
LINT_CMD="$HOME/bin/golangci-lint"
elif [ -x "/usr/local/bin/golangci-lint" ]; then
diff --git a/scripts/doctor.sh b/scripts/doctor.sh
index f5773aac..f3681f99 100755
--- a/scripts/doctor.sh
+++ b/scripts/doctor.sh
@@ -104,8 +104,15 @@ fi
# ── golangci-lint ────────────────────────────────────────────────────
+GOLANGCI_LINT=""
if command -v golangci-lint &>/dev/null; then
- LINT_VERSION=$(golangci-lint version --short 2>/dev/null || golangci-lint --version 2>/dev/null | head -1 | awk '{print $4}')
+ GOLANGCI_LINT="golangci-lint"
+elif [ -x "${GOPATH:-$HOME/go}/bin/golangci-lint" ]; then
+ GOLANGCI_LINT="${GOPATH:-$HOME/go}/bin/golangci-lint"
+fi
+
+if [ -n "$GOLANGCI_LINT" ]; then
+ LINT_VERSION=$($GOLANGCI_LINT version --short 2>/dev/null || $GOLANGCI_LINT --version 2>/dev/null | head -1 | awk '{print $4}')
ok "golangci-lint $LINT_VERSION"
else
fail "golangci-lint" "Required for pre-commit hooks and CI."