improved language about keepAlive timeout

[mintlify]

Mintlify

0 threads from 0 users in Mintlify

• No unresolved comments

---

Note

Documentation improvements to the Sandboxes/Processes page: clarifies keepAlive vs timeout semantics, adds a summary table for their interaction, reformats JSX components for readability, and updates code highlight syntax.

^{Written by Mendral for commit 78e8462.}

[mendral-app]

Needs attention — 1 issue in 1 file

Documentation content is a clear improvement. The only issue is a missing trailing newline at end of file, which can cause minor git/tooling annoyances.

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.

<assessment>
Documentation content is a clear improvement. The only issue is a missing trailing newline at end of file, which can cause minor git/tooling annoyances.
</assessment>

<file name="Sandboxes/Processes.mdx">
<issue location="Sandboxes/Processes.mdx:420">
File is missing a trailing newline. Most tools (including `git diff`) flag this, and POSIX defines a text file as ending with a newline. Add one to avoid noise in future diffs.
</issue>
</file>

_{Tag @mendral-app with feedback or questions. View session}

[mendral-app]

maintainability (P3): File is missing a trailing newline. Most tools (including git diff) flag this, and POSIX defines a text file as ending with a newline. Add one to avoid noise in future diffs.

Suggested change

Suggested change

	- `stopped`
	- `stopped`

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At Sandboxes/Processes.mdx, line 420:

<issue>
File is missing a trailing newline. Most tools (including `git diff`) flag this, and POSIX defines a text file as ending with a newline. Add one to avoid noise in future diffs.
</issue>

[mendral-app]

🔄 Interaction Flow — keepAlive & timeout Behavior (as clarified by this PR)

This PR is docs-only (formatting + improved language in Sandboxes/Processes.mdx), but the clarified semantics describe an important interaction flow. Here's the sequence:

sequenceDiagram
    participant Client as Client (SDK)
    participant Sandbox as Sandbox Instance
    participant Process as Background Process
    participant Monitor as Keep-Alive Monitor

    Client->>Sandbox: process.exec({ command, keepAlive, timeout })
    Sandbox->>Process: Launch (detached, stdout/stderr redirected)

    alt waitForCompletion: true
        Sandbox-->>Client: Blocks up to timeout (max 60s)
        Note right of Client: Timeout only bounds wait,<br/>does NOT kill the process
    else waitForCompletion: false (default)
        Sandbox-->>Client: Returns immediately
    end

    alt keepAlive: true
        Sandbox->>Monitor: Increment keep-alive counter
        Monitor->>Sandbox: Prevent auto-standby
        alt timeout > 0 (default: 600s)
            Monitor->>Process: Auto-kill after N seconds
        else timeout = 0
            Note over Monitor,Process: No auto-kill; runs until natural completion
        end
        Process-->>Monitor: Process exits
        Monitor->>Sandbox: Decrement counter
        Note over Monitor,Sandbox: Sandbox returns to standby<br/>when counter reaches 0
    else keepAlive not set (default)
        Note over Sandbox,Process: Process runs independently;<br/>sandbox may standby on inactivity
    end

Loading

Summary of clarified behavior

Scenario	Process auto-kill	Sandbox standby
No keepAlive	Never (runs to completion)	Normal inactivity rules apply
keepAlive: true, default timeout	After 600s	Prevented while process runs
keepAlive: true, timeout: 0	Never	Prevented while process runs
keepAlive: true, timeout: N	After N seconds	Prevented while process runs

The key clarification in this PR: timeout without keepAlive only bounds the API wait duration — it does not terminate the process.

Note

Posted by PR Sequence Diagram · Tag @mendral-app with feedback.

[mendral-app]

🧪 Testing Guide

What this PR addresses

This PR improves the documentation for Blaxel sandbox process execution, specifically clarifying the semantics of keepAlive and timeout parameters. It adds a new explanatory section on long-running processes, a summary table showing how keepAlive and timeout interact, a note clarifying that timeout does not kill non-keepAlive processes, and minor formatting/syntax fixes throughout.

Steps to verify the changes

Since this is a documentation-only change to Sandboxes/Processes.mdx, there are no code logic changes to reproduce. Instead, verify the following:

1. Preview the rendered page — Open the Mintlify preview (or build the docs locally) and navigate to the "Process execution" page (/Sandboxes/Processes).
2. Check the new "Long-running processes" section — Confirm the introductory paragraphs above "Wait for process completion" render correctly with the bullet list explaining waitForCompletion vs keepAlive.
3. Verify the new Note block — Below the waitForCompletion warning, a new <Note> should render explaining that timeout does not kill non-keepAlive processes.
4. Check the interaction table — In the "Sandbox keep-alive" section, confirm the 4-row table (keepAlive not set / true with no timeout / true with timeout: 0 / true with timeout: N) renders correctly with proper column alignment.
5. Verify code highlight syntax — The code blocks with highlight={2} (instead of the old {2}) should still highlight line 2 correctly in the rendered output.
6. Check formatting of Accordion, Tip, Warning, Note components — These were reformatted with indented content; verify they still render properly with no broken layout.

What to verify (expected behavior)

• All content renders without Mintlify/MDX build errors.
• The new table clearly communicates the difference between keepAlive + timeout configurations.
• Existing links, code examples, and component layouts are not broken by the formatting changes.
• The highlight={2} syntax works for code block line highlighting (replaces {2} shorthand).

Note

Posted by PR Testing Guide · Tag @mendral-app with feedback.

[mendral-app]

📋 Created Linear issue ENG-3457 — status: In Progress

• Assignee: None (bot-authored PR with no human reviewer requested)
• Labels: Doc, Sandbox
• Estimate: S
• PR linked: ✅ Issue will auto-close when this PR merges

Auto-created because no Linear reference was found in the PR title, description, or branch name.

Note

Posted by Linear Issue Enforcer · Tag @mendral-app with feedback.