Skip to content

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

fix: include mode in instance responses and update docs

Luigi Agostie36d944e9d3b
diff --git a/dashboard/src/activities/ActivityPage.test.tsx b/dashboard/src/activities/ActivityPage.test.tsx
index 9dd9c4ca..0855db7d 100644
--- a/dashboard/src/activities/ActivityPage.test.tsx
+++ b/dashboard/src/activities/ActivityPage.test.tsx
@@ -48,6 +48,7 @@ describe("ActivityPage", () => {
profileId: "prof_default",
profileName: "default",
port: "9988",
+ mode: "headless",
headless: true,
status: "running",
startTime: "2026-03-16T08:00:00Z",
diff --git a/dashboard/src/components/molecules/NavBar.test.tsx b/dashboard/src/components/molecules/NavBar.test.tsx
index f50eafbf..22b84bc9 100644
--- a/dashboard/src/components/molecules/NavBar.test.tsx
+++ b/dashboard/src/components/molecules/NavBar.test.tsx
@@ -28,6 +28,7 @@ describe("NavBar", () => {
profileId: "prof_alpha",
profileName: "alpha",
port: "9988",
+ mode: "headed",
headless: false,
status: "running",
startTime: "2026-04-09T10:00:00Z",
diff --git a/dashboard/src/components/molecules/ServerStatusBadge.test.tsx b/dashboard/src/components/molecules/ServerStatusBadge.test.tsx
index fe2262f8..70d38c77 100644
--- a/dashboard/src/components/molecules/ServerStatusBadge.test.tsx
+++ b/dashboard/src/components/molecules/ServerStatusBadge.test.tsx
@@ -9,6 +9,7 @@ const runningInstance: Instance = {
profileId: "prof_alpha",
profileName: "alpha",
port: "9988",
+ mode: "headed",
headless: false,
status: "running",
startTime: "2026-04-09T10:00:00Z",
diff --git a/dashboard/src/components/molecules/StartInstanceModal.test.tsx b/dashboard/src/components/molecules/StartInstanceModal.test.tsx
index 85392a97..4e4652b0 100644
--- a/dashboard/src/components/molecules/StartInstanceModal.test.tsx
+++ b/dashboard/src/components/molecules/StartInstanceModal.test.tsx
@@ -58,6 +58,7 @@ describe("StartInstanceModal", () => {
profileId: "prof_alpha",
profileName: "alpha",
port: "9988",
+ mode: "headed",
headless: false,
status: "running",
startTime: "2026-03-06T10:00:00Z",
diff --git a/dashboard/src/generated/types.ts b/dashboard/src/generated/types.ts
index a1fc89dd..57086afe 100644
--- a/dashboard/src/generated/types.ts
+++ b/dashboard/src/generated/types.ts
@@ -43,6 +43,7 @@ export interface Instance {
profileName: string;
port: string; // Note: string not int
url?: string;
+ mode: string;
headless: boolean;
status: string; // starting/running/stopping/stopped/error
startTime: string;
diff --git a/dashboard/src/pages/MonitoringPage.test.tsx b/dashboard/src/pages/MonitoringPage.test.tsx
index 5d514160..0cc1a620 100644
--- a/dashboard/src/pages/MonitoringPage.test.tsx
+++ b/dashboard/src/pages/MonitoringPage.test.tsx
@@ -15,6 +15,7 @@ vi.mock("../services/api", () => ({
profileId: "default",
profileName: "default",
port: "9868",
+ mode: "headed",
headless: false,
status: "starting",
startTime: "2026-03-06T10:00:00Z",
@@ -37,6 +38,7 @@ const instances: Instance[] = [
profileId: "prof_beta",
profileName: "beta",
port: "9988",
+ mode: "headed",
headless: false,
status: "running",
startTime: "2026-03-06T10:00:00Z",
diff --git a/dashboard/src/pages/ProfilesPage.test.tsx b/dashboard/src/pages/ProfilesPage.test.tsx
index 9873ac45..0a3a3aa1 100644
--- a/dashboard/src/pages/ProfilesPage.test.tsx
+++ b/dashboard/src/pages/ProfilesPage.test.tsx
@@ -49,6 +49,7 @@ const instances: Instance[] = [
profileId: "prof_beta",
profileName: "beta",
port: "9988",
+ mode: "headed",
headless: false,
status: "running",
startTime: "2026-03-06T10:00:00Z",
diff --git a/dashboard/src/profiles/ProfileCard.test.tsx b/dashboard/src/profiles/ProfileCard.test.tsx
index 6c11004d..12bebf3f 100644
--- a/dashboard/src/profiles/ProfileCard.test.tsx
+++ b/dashboard/src/profiles/ProfileCard.test.tsx
@@ -19,6 +19,7 @@ const mockRunningInstance: Instance = {
profileId: "prof_123",
profileName: "test-profile",
port: "9868",
+ mode: "headed",
headless: false,
status: "running",
startTime: new Date().toISOString(),
diff --git a/dashboard/src/services/api.ts b/dashboard/src/services/api.ts
index d31e7c4a..084ea451 100644
--- a/dashboard/src/services/api.ts
+++ b/dashboard/src/services/api.ts
@@ -166,6 +166,13 @@ function withDashboardSource(options?: RequestInit): RequestInit {
};
}
+function normalizeInstance(instance: Instance): Instance {
+ return {
+ ...instance,
+ mode: instance.mode ?? (instance.headless ? "headless" : "headed"),
+ };
+}
+
// Profiles — endpoint is /profiles (no /api prefix)
export async function fetchProfiles(): Promise<Profile[]> {
return request<Profile[]>("/profiles");
@@ -212,18 +219,20 @@ export async function updateProfile(
// Instances — endpoint is /instances (no /api prefix)
export async function fetchInstances(): Promise<Instance[]> {
- return request<Instance[]>("/instances");
+ return (await request<Instance[]>("/instances")).map(normalizeInstance);
}
export async function launchInstance(
data: LaunchInstanceRequest,
): Promise<Instance> {
// Use the canonical start endpoint to avoid legacy launch alias validation edge cases.
- return request<Instance>("/instances/start", {
- method: "POST",
- headers: { "Content-Type": "application/json" },
- body: JSON.stringify(data),
- });
+ return normalizeInstance(
+ await request<Instance>("/instances/start", {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify(data),
+ }),
+ );
}
export async function stopInstance(id: string): Promise<void> {
diff --git a/dashboard/src/types/index.ts b/dashboard/src/types/index.ts
index 652fd027..7607883e 100644
--- a/dashboard/src/types/index.ts
+++ b/dashboard/src/types/index.ts
@@ -428,7 +428,10 @@ export function normalizeMonitoringSnapshot(
): MonitoringSnapshot {
return {
timestamp: input.timestamp ?? Date.now(),
- instances: input.instances ?? [],
+ instances: (input.instances ?? []).map((instance) => ({
+ ...instance,
+ mode: instance.mode ?? (instance.headless ? "headless" : "headed"),
+ })),
tabs: input.tabs ?? [],
metrics: input.metrics ?? [],
serverMetrics: {
diff --git a/docs/core-concepts.md b/docs/core-concepts.md
index 2bf39e2c..9357a284 100644
--- a/docs/core-concepts.md
+++ b/docs/core-concepts.md
@@ -139,6 +139,7 @@ pinchtab instance start --profile prof_278be873 --mode headed
"profileId": "prof_278be873",
"profileName": "work",
"port": "9868",
+ "mode": "headed",
"headless": false,
"status": "starting"
}
diff --git a/docs/dashboard.md b/docs/dashboard.md
index 3445d199..9adb4c29 100644
--- a/docs/dashboard.md
+++ b/docs/dashboard.md
@@ -106,6 +106,7 @@ pinchtab instance start --profile prof_278be873 --mode headed
"profileId": "prof_278be873",
"profileName": "work",
"port": "9868",
+ "mode": "headed",
"headless": false,
"status": "starting"
}
diff --git a/docs/endpoints.md b/docs/endpoints.md
index e4317747..5c724be7 100644
--- a/docs/endpoints.md
+++ b/docs/endpoints.md
@@ -491,6 +491,7 @@ Notes:
- `/instances/start` and `/instances/launch` use `mode`, not `headless`
- `/instances/launch` is a compatibility alias over `/instances/start`
+- instance responses include both `mode` and `headless`
- instance start surfaces accept `securityPolicy.allowedDomains` for additive instance-scoped IDPI/domain allowlist overrides
- create profiles explicitly with `POST /profiles`; `name` is no longer supported on `/instances/launch`
- `/profiles/{id}/start` uses `headless`
diff --git a/docs/get-started.md b/docs/get-started.md
index da370b89..900b3d8c 100644
--- a/docs/get-started.md
+++ b/docs/get-started.md
@@ -112,6 +112,7 @@ pinchtab instance start
"profileId": "prof_278be873",
"profileName": "instance-1741400000000000000",
"port": "9868",
+ "mode": "headless",
"headless": true,
"status": "starting"
}
diff --git a/docs/guides/attach-chrome.md b/docs/guides/attach-chrome.md
index 6d8603cc..a7d49b31 100644
--- a/docs/guides/attach-chrome.md
+++ b/docs/guides/attach-chrome.md
@@ -130,6 +130,7 @@ curl -X POST http://localhost:9867/instances/attach \
"profileId": "prof_278be873",
"profileName": "shared-chrome",
"port": "",
+ "mode": "headed",
"headless": false,
"status": "running",
"attached": true,
diff --git a/docs/guides/multi-instance.md b/docs/guides/multi-instance.md
index 4f4f3e5b..f94bbc9e 100644
--- a/docs/guides/multi-instance.md
+++ b/docs/guides/multi-instance.md
@@ -33,6 +33,7 @@ pinchtab instance start --mode headed --port 9999
"profileId": "prof_278be873",
"profileName": "instance-1741410000000",
"port": "9999",
+ "mode": "headed",
"headless": false,
"status": "starting"
}
@@ -101,6 +102,7 @@ Useful fields:
- `id`: stable instance identifier
- `profileId` and `profileName`: the profile backing that instance
- `port`: the instance's HTTP port
+- `mode`: explicit `"headless"` or `"headed"` string for request/response symmetry
- `headless`: whether Chrome was launched headless
- `status`: usually `starting`, `running`, `stopping`, or `stopped`
diff --git a/docs/guides/remote-bridge-orchestrator.md b/docs/guides/remote-bridge-orchestrator.md
index 7282c907..ac8dd38f 100644
--- a/docs/guides/remote-bridge-orchestrator.md
+++ b/docs/guides/remote-bridge-orchestrator.md
@@ -175,6 +175,7 @@ Response shape:
"profileName": "bridge-eu-west-1",
"port": "",
"url": "http://10.0.12.24:9868",
+ "mode": "headed",
"headless": false,
"status": "running",
"attached": true,
diff --git a/docs/headless-vs-headed.md b/docs/headless-vs-headed.md
index f6962330..d56ca396 100644
--- a/docs/headless-vs-headed.md
+++ b/docs/headless-vs-headed.md
@@ -25,6 +25,7 @@ pinchtab instance start
"profileId": "prof_278be873",
"profileName": "instance-1741400000000000000",
"port": "9868",
+ "mode": "headless",
"headless": true,
"status": "starting"
}
@@ -60,6 +61,7 @@ pinchtab instance start --mode headed
"profileId": "prof_278be873",
"profileName": "instance-1741400000000000001",
"port": "9869",
+ "mode": "headed",
"headless": false,
"status": "starting"
}
@@ -135,6 +137,7 @@ pinchtab instance start --profile prof_278be873 --mode headed
"profileId": "prof_278be873",
"profileName": "dev",
"port": "9868",
+ "mode": "headed",
"headless": false,
"status": "starting"
}
diff --git a/docs/pinchtab.md b/docs/pinchtab.md
index 36bcb75a..65dd446f 100644
--- a/docs/pinchtab.md
+++ b/docs/pinchtab.md
@@ -52,6 +52,7 @@ pinchtab instance start
"profileId": "prof_278be873",
"profileName": "instance-1741400000000000000",
"port": "9868",
+ "mode": "headless",
"headless": true,
"status": "starting"
}
diff --git a/docs/reference/instances.md b/docs/reference/instances.md
index 8727ae9d..59996a05 100644
--- a/docs/reference/instances.md
+++ b/docs/reference/instances.md
@@ -29,6 +29,7 @@ Response shape:
"profileId": "prof_278be873",
"profileName": "instance-1741410000000",
"port": "9999",
+ "mode": "headed",
"headless": false,
"status": "running",
"securityPolicy": {
@@ -38,7 +39,7 @@ Response shape:
]
```
-`GET /instances` returns a bare JSON array, not an envelope like `{"instances":[...]}`.
+`GET /instances` returns a bare JSON array, not an envelope like `{"instances":[...]}`. Each instance response includes both `mode` (`"headless"` or `"headed"`) and the legacy-compatible `headless` boolean.
## Start An Instance
@@ -107,6 +108,11 @@ Common status values:
- `stopped`
- `error`
+Instance responses include:
+
+- `mode`: `"headless"` or `"headed"`
+- `headless`: boolean kept for compatibility
+
## Get Instance Logs
```bash
diff --git a/docs/reference/profiles.md b/docs/reference/profiles.md
index c73742e5..3419612b 100644
--- a/docs/reference/profiles.md
+++ b/docs/reference/profiles.md
@@ -136,6 +136,7 @@ curl -X POST http://localhost:9867/profiles/prof_278be873/start \
"profileId": "prof_278be873",
"profileName": "work",
"port": "9868",
+ "mode": "headless",
"headless": true,
"status": "starting"
}
@@ -153,7 +154,7 @@ curl -X POST http://localhost:9867/profiles/prof_278be873/stop
}
```
-For these orchestrator routes, the path can be a profile ID or profile name.
+For these orchestrator routes, the path can be a profile ID or profile name. The returned instance object now includes both `mode` and `headless`.
## Check Whether A Profile Has A Running Instance
diff --git a/docs/showcase.md b/docs/showcase.md
index 65616f0a..b6a039bd 100644
--- a/docs/showcase.md
+++ b/docs/showcase.md
@@ -24,6 +24,7 @@ pinchtab instance start
"profileId": "prof_278be873",
"profileName": "instance-1741400000000000000",
"port": "9868",
+ "mode": "headless",
"headless": true,
"status": "starting"
}
diff --git a/internal/api/types/types.go b/internal/api/types/types.go
index ae2b45c5..45e94c40 100644
--- a/internal/api/types/types.go
+++ b/internal/api/types/types.go
@@ -38,6 +38,7 @@ type Instance struct {
ProfileName string `json:"profileName"`
Port string `json:"port"` // Note: string not int
URL string `json:"url,omitempty"`
+ Mode string `json:"mode"`
Headless bool `json:"headless"`
Status string `json:"status"` // starting/running/stopping/stopped/error
StartTime time.Time `json:"startTime"`
diff --git a/internal/bridge/api.go b/internal/bridge/api.go
index 94210f1b..5c0a1fe3 100644
--- a/internal/bridge/api.go
+++ b/internal/bridge/api.go
@@ -2,6 +2,7 @@ package bridge
import (
"context"
+ "encoding/json"
"errors"
"net/http"
"time"
@@ -141,12 +142,29 @@ type SecurityPolicy struct {
AllowedDomains []string `json:"allowedDomains,omitempty"`
}
+func ModeFromHeadless(headless bool) string {
+ if headless {
+ return "headless"
+ }
+ return "headed"
+}
+
+func normalizeInstanceMode(mode string, headless bool) string {
+ switch mode {
+ case "headless", "headed":
+ return mode
+ default:
+ return ModeFromHeadless(headless)
+ }
+}
+
type Instance struct {
ID string `json:"id"` // Hash-based ID: inst_XXXXXXXX
ProfileID string `json:"profileId"` // Hash-based profile ID: prof_XXXXXXXX
ProfileName string `json:"profileName"` // Human-readable profile name (for display only)
Port string `json:"port"` // Internal: instance port
URL string `json:"url,omitempty"` // Canonical base URL for bridge-backed instances
+ Mode string `json:"mode"` // API mode: "headless" or "headed"
Headless bool `json:"headless"` // Mode: headless vs headed
Status string `json:"status"` // Status: starting/running/stopping/stopped/error
StartTime time.Time `json:"startTime"` // When instance was created
@@ -157,6 +175,13 @@ type Instance struct {
SecurityPolicy *SecurityPolicy `json:"securityPolicy,omitempty"`
}
+func (i Instance) MarshalJSON() ([]byte, error) {
+ type alias Instance
+ copy := alias(i)
+ copy.Mode = normalizeInstanceMode(copy.Mode, copy.Headless)
+ return json.Marshal(copy)
+}
+
type InstanceTab struct {
ID string `json:"id"` // Runtime tab ID (raw CDP target ID on this branch)
InstanceID string `json:"instanceId"` // Hash-based instance ID: inst_XXXXXXXX
diff --git a/internal/bridge/api_test.go b/internal/bridge/api_test.go
new file mode 100644
index 00000000..e324a8a5
--- /dev/null
+++ b/internal/bridge/api_test.go
@@ -0,0 +1,42 @@
+package bridge
+
+import (
+ "encoding/json"
+ "testing"
+)
+
+func TestInstanceMarshalJSONDerivesModeFromHeadless(t *testing.T) {
+ data, err := json.Marshal(Instance{Headless: true})
+ if err != nil {
+ t.Fatalf("Marshal() error = %v", err)
+ }
+
+ var decoded map[string]any
+ if err := json.Unmarshal(data, &decoded); err != nil {
+ t.Fatalf("Unmarshal() error = %v", err)
+ }
+ if got := decoded["mode"]; got != "headless" {
+ t.Fatalf("mode = %v, want headless", got)
+ }
+ if got := decoded["headless"]; got != true {
+ t.Fatalf("headless = %v, want true", got)
+ }
+}
+
+func TestInstanceMarshalJSONPreservesExplicitMode(t *testing.T) {
+ data, err := json.Marshal(Instance{Mode: "headed", Headless: false})
+ if err != nil {
+ t.Fatalf("Marshal() error = %v", err)
+ }
+
+ var decoded map[string]any
+ if err := json.Unmarshal(data, &decoded); err != nil {
+ t.Fatalf("Unmarshal() error = %v", err)
+ }
+ if got := decoded["mode"]; got != "headed" {
+ t.Fatalf("mode = %v, want headed", got)
+ }
+ if got := decoded["headless"]; got != false {
+ t.Fatalf("headless = %v, want false", got)
+ }
+}
diff --git a/internal/orchestrator/handlers_instances_test.go b/internal/orchestrator/handlers_instances_test.go
index c08b69f9..900f63fe 100644
--- a/internal/orchestrator/handlers_instances_test.go
+++ b/internal/orchestrator/handlers_instances_test.go
@@ -63,6 +63,9 @@ func TestHandleLaunchByNameAliasesStartSemantics(t *testing.T) {
if inst.ProfileName != "work" {
t.Fatalf("ProfileName = %q, want %q", inst.ProfileName, "work")
}
+ if inst.Mode != "headed" {
+ t.Fatalf("Mode = %q, want %q", inst.Mode, "headed")
+ }
if inst.Headless {
t.Fatal("Headless = true, want false for mode=headed")
}
@@ -128,6 +131,9 @@ func TestHandleStartInstance_AppliesSecurityPolicyOverride(t *testing.T) {
if err := json.NewDecoder(w.Body).Decode(&inst); err != nil {
t.Fatalf("decode response: %v", err)
}
+ if inst.Mode != "headed" {
+ t.Fatalf("Mode = %q, want %q", inst.Mode, "headed")
+ }
if inst.SecurityPolicy == nil {
t.Fatal("expected securityPolicy on instance response")
}
diff --git a/internal/orchestrator/orchestrator.go b/internal/orchestrator/orchestrator.go
index 2954d739..f61020a6 100644
--- a/internal/orchestrator/orchestrator.go
+++ b/internal/orchestrator/orchestrator.go
@@ -373,6 +373,7 @@ func (o *Orchestrator) LaunchWithOptions(name, port string, headless bool, opts
ProfileName: name,
Port: port,
URL: o.childInstanceBaseURL(port),
+ Mode: bridge.ModeFromHeadless(headless),
Headless: headless,
Status: "starting",
StartTime: time.Now(),
@@ -577,6 +578,7 @@ func (o *Orchestrator) Attach(name, cdpURL string) (*bridge.Instance, error) {
AttachType: "cdp",
CdpURL: cdpURL,
URL: cdpURL,
+ Mode: bridge.ModeFromHeadless(false),
}, "")
if err != nil {
return nil, err
@@ -602,6 +604,7 @@ func (o *Orchestrator) AttachBridge(name, baseURL, token string) (*bridge.Instan
Attached: true,
AttachType: "bridge",
URL: normalizedBaseURL,
+ Mode: bridge.ModeFromHeadless(false),
}, token)
if err != nil {
return nil, false, err
diff --git a/internal/orchestrator/orchestrator_test.go b/internal/orchestrator/orchestrator_test.go
index 88a89445..2196dc60 100644
--- a/internal/orchestrator/orchestrator_test.go
+++ b/internal/orchestrator/orchestrator_test.go
@@ -49,6 +49,9 @@ func TestOrchestrator_Launch_Lifecycle(t *testing.T) {
if err != nil {
t.Fatalf("First launch failed: %v", err)
}
+ if inst.Mode != "headless" {
+ t.Fatalf("Mode = %q, want %q", inst.Mode, "headless")
+ }
if inst.Status != "starting" {
t.Errorf("expected status starting, got %s", inst.Status)
}
diff --git a/tests/e2e/scenarios/infra/orchestrator-extended.sh b/tests/e2e/scenarios/infra/orchestrator-extended.sh
index 1021053a..2b88af17 100644
--- a/tests/e2e/scenarios/infra/orchestrator-extended.sh
+++ b/tests/e2e/scenarios/infra/orchestrator-extended.sh
@@ -81,6 +81,8 @@ start_test "orchestrator: launch new instance"
pt_post /instances/start '{"mode":"headless"}'
assert_ok "launch instance"
+assert_json_eq "$RESULT" '.mode' 'headless' "launch response includes mode"
+assert_json_eq "$RESULT" '.headless' 'true' "launch response keeps headless boolean"
INST_ID=$(echo "$RESULT" | jq -r '.id')
assert_json_exists "$RESULT" '.id' "has instance id"
@@ -100,6 +102,8 @@ start_test "orchestrator: get instance by id"
pt_get "/instances/${INST_ID}"
assert_ok "get instance"
assert_json_eq "$RESULT" '.id' "$INST_ID"
+assert_json_eq "$RESULT" '.mode' 'headless' "instance response includes mode"
+assert_json_eq "$RESULT" '.headless' 'true' "instance response keeps headless boolean"
end_test