blaxel-ai
diff --git a/‎sandbox-api/docs/LIFECYCLE.md‎
Lines changed: 82 additions & 0 deletions b/‎sandbox-api/docs/LIFECYCLE.md‎
Lines changed: 82 additions & 0 deletions
diff --git a/‎sandbox-api/docs/docs.go‎
Lines changed: 11 additions & 0 deletions b/‎sandbox-api/docs/docs.go‎
Lines changed: 11 additions & 0 deletions
diff --git a/‎sandbox-api/docs/openapi.yml‎
Lines changed: 9 additions & 0 deletions b/‎sandbox-api/docs/openapi.yml‎
Lines changed: 9 additions & 0 deletions
diff --git a/‎sandbox-api/main.go‎
Lines changed: 8 additions & 0 deletions b/‎sandbox-api/main.go‎
Lines changed: 8 additions & 0 deletions
diff --git a/‎sandbox-api/src/handler/process.go‎
Lines changed: 30 additions & 5 deletions b/‎sandbox-api/src/handler/process.go‎
Lines changed: 30 additions & 5 deletions
@@ -0,0 +1,82 @@
+# Process KeepAlive
+
+This document describes the process `keepAlive` feature that controls the sandbox's auto-hibernation behavior.
+
+## Overview
+
+When launching a process with `keepAlive: true`, the sandbox will stay awake (auto-hibernation disabled) until the process completes or times out.
+
+## How It Works
+
+The sandbox uses a **counter-based scale-to-zero** system:
+
+| Counter | Effect |
+|---------|--------|
+| > 0 | Auto-hibernation disabled (sandbox stays awake) |
+| = 0 | Auto-hibernation enabled (sandbox can sleep) |
+
+When a `keepAlive` process starts, the counter is incremented. When it ends, the counter is decremented.
+
+## API Usage
+
+**POST /process**
+
+```json
+{
+  "command": "npm run dev",
+  "workingDir": "/app",
+  "keepAlive": true,
+  "timeout": 600
+}
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `keepAlive` | boolean | `false` | When true, disables auto-hibernation while the process runs |
+| `timeout` | integer | `600` | Timeout in seconds. Set to `0` for infinite (no timeout) |
+
+## Timeout Behavior
+
+- **timeout > 0**: Process will be automatically killed after the specified seconds
+- **timeout = 0**: Process runs indefinitely (infinite timeout)
+- **timeout not specified with keepAlive=true**: Defaults to 600 seconds (10 minutes)
+
+## Logging
+
+All keepAlive events are logged:
+
+```
+[KeepAlive] Started process 12345 (name: my-app, command: npm run dev) with timeout 600s
+[KeepAlive] Stopped process 12345 (name: my-app, status: completed, exit_code: 0)
+```
+
+Scale operations:
+
+```
+[Scale] Disabled scale-to-zero (wrote '+', counter now: 1) - sandbox staying AWAKE
+[Scale] Enabled scale-to-zero (wrote '-', counter now: 0) - sandbox can AUTO-HIBERNATE
+```
+
+## Crash Recovery
+
+On startup, the sandbox-api resets the scale-to-zero counter to 0, ensuring the sandbox doesn't get stuck awake if the API crashed while keepAlive processes were running.
+
+## Examples
+
+### Run a dev server that keeps sandbox awake
+
+```bash
+curl -X POST http://localhost:8080/process \
+  -H "Content-Type: application/json" \
+  -d '{"command": "npm run dev", "workingDir": "/app", "keepAlive": true}'
+```
+
+### Run a process with infinite timeout
+
+```bash
+curl -X POST http://localhost:8080/process \
+  -H "Content-Type: application/json" \
+  -d '{"command": "python server.py", "keepAlive": true, "timeout": 0}'
+```
@@ -2185,6 +2185,11 @@ const docTemplate = `{
                         "{\"PORT\"": " \"3000\"}"
                     }
                 },
+                "keepAlive": {
+                    "description": "Disable scale-to-zero while process runs. Default timeout is 600s (10 minutes). Set timeout to 0 for infinite.",
+                    "type": "boolean",
+                    "example": false
+                },
                 "maxRestarts": {
                     "type": "integer",
                     "example": 3
@@ -2198,6 +2203,7 @@ const docTemplate = `{
                     "example": true
                 },
                 "timeout": {
+                    "description": "Timeout in seconds. When keepAlive is true, defaults to 600s (10 minutes). Set to 0 for infinite (no auto-kill).",
                     "type": "integer",
                     "example": 30
                 },
@@ -2249,6 +2255,11 @@ const docTemplate = `{
                     "type": "integer",
                     "example": 0
                 },
+                "keepAlive": {
+                    "description": "Whether scale-to-zero is disabled for this process",
+                    "type": "boolean",
+                    "example": false
+                },
                 "logs": {
                     "type": "string",
                     "example": "logs output"
 
@@ -1772,6 +1772,10 @@ components:
           example:
             "{\"PORT\"": ' "3000"}'
           type: object
+        keepAlive:
+          description: Disable scale-to-zero while process runs. Default timeout is 600s (10 minutes). Set timeout to 0 for infinite.
+          example: false
+          type: boolean
         maxRestarts:
           example: 3
           type: integer
@@ -1782,6 +1786,7 @@ components:
           example: true
           type: boolean
         timeout:
+          description: Timeout in seconds. When keepAlive is true, defaults to 600s (10 minutes). Set to 0 for infinite (no auto-kill).
           example: 30
           type: integer
         waitForCompletion:
@@ -1811,6 +1816,10 @@ components:
         exitCode:
           example: 0
           type: integer
+        keepAlive:
+          description: Whether scale-to-zero is disabled for this process
+          example: false
+          type: boolean
         logs:
           example: logs output
           type: string
 
@@ -15,6 +15,7 @@ import (
 	"github.com/blaxel-ai/sandbox-api/docs" // swagger generated docs
 	"github.com/blaxel-ai/sandbox-api/src/api"
 	"github.com/blaxel-ai/sandbox-api/src/handler/process"
+	"github.com/blaxel-ai/sandbox-api/src/lib/blaxel"
 	"github.com/blaxel-ai/sandbox-api/src/lib/networking"
 	"github.com/blaxel-ai/sandbox-api/src/mcp"
 	"github.com/gin-gonic/gin"
@@ -45,6 +46,13 @@ func main() {
 		logrus.WithError(err).Warn("WireGuard initialization failed - the sandbox will NOT have outbound internet connectivity (no egress). Inbound connections to the sandbox will still work. You can check the tunnel status via the /network/tunnel endpoints.")
 	}
 
+	// Reset scale-to-zero counter on startup (crash recovery)
+	// If sandbox-api crashed while keepAlive processes were running,
+	// the counter would be left in a bad state - this resets it to 0
+	if err := blaxel.ScaleReset(); err != nil {
+		logrus.Warnf("Failed to reset scale-to-zero counter on startup: %v", err)
+	}
+
 	ctx, cancel := context.WithCancel(context.Background())
 	defer cancel()
 
 
@@ -52,10 +52,11 @@ type ProcessRequest struct {
 	WorkingDir        string            `json:"workingDir" example:"/home/user"`
 	Env               map[string]string `json:"env" example:"{\"PORT\": \"3000\"}"`
 	WaitForCompletion bool              `json:"waitForCompletion" example:"false"`
-	Timeout           int               `json:"timeout" example:"30"`
+	Timeout           *int              `json:"timeout,omitempty" example:"30"`
 	WaitForPorts      []int             `json:"waitForPorts" example:"3000,8080"`
 	RestartOnFailure  bool              `json:"restartOnFailure" example:"true"`
 	MaxRestarts       int               `json:"maxRestarts" example:"3"`
+	KeepAlive         bool              `json:"keepAlive" example:"false"`
 } // @name ProcessRequest
 
 // ProcessResponse is the response body for a process
@@ -74,6 +75,7 @@ type ProcessResponse struct {
 	RestartOnFailure bool    `json:"restartOnFailure" example:"true"`
 	MaxRestarts      int     `json:"maxRestarts" example:"3"`
 	RestartCount     int     `json:"restartCount" example:"2"`
+	KeepAlive        bool    `json:"keepAlive" example:"false"`
 } // @name ProcessResponse
 
 type ProcessResponseWithLogs struct {
@@ -87,8 +89,8 @@ type ProcessKillRequest struct {
 } // @name ProcessKillRequest
 
 // ExecuteProcess executes a process
-func (h *ProcessHandler) ExecuteProcess(command string, workingDir string, name string, env map[string]string, waitForCompletion bool, timeout int, waitForPorts []int, restartOnFailure bool, maxRestarts int) (ProcessResponse, error) {
-	processInfo, err := h.processManager.ExecuteProcess(command, workingDir, name, env, waitForCompletion, timeout, waitForPorts, restartOnFailure, maxRestarts)
+func (h *ProcessHandler) ExecuteProcess(command string, workingDir string, name string, env map[string]string, waitForCompletion bool, timeout int, waitForPorts []int, restartOnFailure bool, maxRestarts int, keepAlive bool) (ProcessResponse, error) {
+	processInfo, err := h.processManager.ExecuteProcess(command, workingDir, name, env, waitForCompletion, timeout, waitForPorts, restartOnFailure, maxRestarts, keepAlive)
 
 	// If processInfo is nil (process failed to start), return empty response with error
 	if processInfo == nil {
@@ -117,6 +119,7 @@ func (h *ProcessHandler) ExecuteProcess(command string, workingDir string, name
 		RestartOnFailure: processInfo.RestartOnFailure,
 		MaxRestarts:      processInfo.MaxRestarts,
 		RestartCount:     processInfo.RestartCount,
+		KeepAlive:        processInfo.KeepAlive,
 	}, err
 }
 
@@ -158,6 +161,7 @@ func (h *ProcessHandler) ListProcesses() []ProcessResponse {
 			RestartOnFailure: p.RestartOnFailure,
 			MaxRestarts:      p.MaxRestarts,
 			RestartCount:     p.RestartCount,
+			KeepAlive:        p.KeepAlive,
 		})
 	}
 	return result
@@ -202,6 +206,7 @@ func (h *ProcessHandler) GetProcess(identifier string) (ProcessResponse, error)
 		RestartOnFailure: processInfo.RestartOnFailure,
 		MaxRestarts:      processInfo.MaxRestarts,
 		RestartCount:     processInfo.RestartCount,
+		KeepAlive:        processInfo.KeepAlive,
 	}, nil
 }
 
@@ -293,8 +298,18 @@ func (h *ProcessHandler) HandleExecuteCommand(c *gin.Context) {
 		"working-dir": req.WorkingDir,
 	})
 
+	// Timeout of 0 means infinite (no auto-kill)
+	// When keepAlive is true and timeout is not specified (nil) or negative, default to 600s
+	timeout := 0
+	if req.Timeout != nil {
+		timeout = *req.Timeout
+	}
+	if req.KeepAlive && (req.Timeout == nil || timeout < 0) {
+		timeout = 600 // Default 10 minutes
+	}
+
 	// Execute the process
-	processInfo, err := h.ExecuteProcess(req.Command, req.WorkingDir, req.Name, req.Env, req.WaitForCompletion, req.Timeout, req.WaitForPorts, req.RestartOnFailure, req.MaxRestarts)
+	processInfo, err := h.ExecuteProcess(req.Command, req.WorkingDir, req.Name, req.Env, req.WaitForCompletion, timeout, req.WaitForPorts, req.RestartOnFailure, req.MaxRestarts, req.KeepAlive)
 	if err != nil {
 		h.SendError(c, http.StatusUnprocessableEntity, err)
 		return
@@ -335,6 +350,16 @@ func (h *ProcessHandler) handleExecuteCommandStream(c *gin.Context) {
 		"working-dir": req.WorkingDir,
 	})
 
+	// Timeout of 0 means infinite (no auto-kill)
+	// When keepAlive is true and timeout is not specified (nil) or negative, default to 600s
+	timeout := 0
+	if req.Timeout != nil {
+		timeout = *req.Timeout
+	}
+	if req.KeepAlive && (req.Timeout == nil || timeout < 0) {
+		timeout = 600 // Default 10 minutes
+	}
+
 	// Set headers for streaming JSON events
 	c.Writer.Header().Set("Content-Type", "application/x-ndjson")
 	c.Writer.Header().Set("Cache-Control", "no-cache")
@@ -346,7 +371,7 @@ func (h *ProcessHandler) handleExecuteCommandStream(c *gin.Context) {
 	jw := &JSONStreamWriter{gin: c}
 
 	// Execute the process without waiting for completion (we'll handle waiting ourselves)
-	processInfo, err := h.ExecuteProcess(req.Command, req.WorkingDir, req.Name, req.Env, false, req.Timeout, req.WaitForPorts, req.RestartOnFailure, req.MaxRestarts)
+	processInfo, err := h.ExecuteProcess(req.Command, req.WorkingDir, req.Name, req.Env, false, timeout, req.WaitForPorts, req.RestartOnFailure, req.MaxRestarts, req.KeepAlive)
 	if err != nil {
 		jw.WriteEvent("error", err.Error())
 		return