Agent Sandbox Runtime#

The in-app agent sandbox is a containerized code execution environment that gives the Langfuse in-app agent isolated access to filesystem operations (read, write, edit) and shell commands (bash). It is part of the EE in-app-agent feature and underpins the agent's ability to safely perform multi-step agentic tasks without affecting the host process.

Current location (post-refactor): packages/shared/src/in-app-agent/server/sandbox/ 1

Original location (before refactor): web/src/ee/features/in-app-agent/server/sandbox/ 2

Architecture#

The sandbox is structured into three layers:

Sandbox Runtime Package#

packages/in-app-agent-sandbox-runtime/ is a standalone Node.js package that runs as a lightweight HTTP server (port 5000) inside the sandbox container/VM. It exposes a single /sandbox operation endpoint for the four tool operations, plus a health check endpoint 2.

Key files:

• src/server.ts — HTTP control server; handles path validation, read/write/edit/bash dispatch, and enforces a 10 MB request body limit 2
• src/contracts.ts — Zod schemas for operation validation 2
• Dockerfile — Alpine Node.js image running as unprivileged sandbox-server user; /workspace is writable, /workspace/tool_calls is recreated fresh before each operation 2

Provider Implementations#

The sandbox uses a SandboxProvider / SandboxSession interface to abstract two backends 2:

Provider is selected via the LANGFUSE_IN_APP_AGENT_SANDBOX_PROVIDER environment variable 2. Additional Lambda env vars: LANGFUSE_IN_APP_AGENT_SANDBOX_AWS_LAMBDA_MICROVM_IMAGE_IDENTIFIER, LANGFUSE_IN_APP_AGENT_SANDBOX_AWS_LAMBDA_MICROVM_EXECUTION_ROLE_ARN, LANGFUSE_IN_APP_AGENT_SANDBOX_AWS_LAMBDA_MICROVM_REGION.

Sandbox Service Layer#

sandbox/service.ts manages the per-conversation lifecycle 2:

• ensureSession() — creates or resumes a session by providerSessionId
• syncReadonlyFiles() — rebuilds /workspace/tool_calls/*.json from prior tool call events before each turn
• onTurnEnded() — persists the session ID back to the conversation record in the database

Process Isolation and Security#

Container/VM isolation: Each sandbox runs in a fully isolated environment — a Docker container (dev) or Lambda MicroVM (prod). Containers run unprivileged and are recreated if stale. Lambda MicroVMs support session suspend/resume and automatic auth token refresh 2.

Path escaping: All file operation paths are validated via resolveSandboxPath() in the runtime server. The function resolves relative paths to /workspace, normalizes them, and rejects any path that escapes the workspace root 2.

Request body limits: The runtime's readJsonBody enforces a 10 MB ceiling to prevent unbounded memory buffering and process crashes from oversized payloads 2.

Write-lock mechanism: Sandbox conversations are read-locked 8 hours after creation. The handler checks isInAppAgentConversationWriteLocked() before each new turn and rejects it with HTTP 412 if the lock is active. This prevents data loss from long-lived concurrent sessions 2.

Known limitations (from code review at initial PR #14712):

• The edit operation uses String.prototype.replace(), which silently replaces only the first occurrence. If oldText appears multiple times, the agent receives no ambiguity signal 2.
• Docker provider uses dynamic imports inside function bodies (lazy-loading for dev-only isolation), deviating from the team's module-level import convention 2.

Session and State Management#

Sessions are stateless at the HTTP level. The providerSessionId (and sandboxProvider enum) are persisted on the InAppAgentConversation database record so sessions can be resumed across requests without in-memory state 2.

Before each turn, prior non-sandbox tool call results are reconstructed from persisted events by getSandboxToolCallFiles() in persistence.ts and synced into /workspace/tool_calls/ as read-only JSON files. This gives the sandbox agent consistent context regardless of provider or whether the session was resumed 2.

The operation flow per turn is:

1. Handler loads prior events → calls getSandboxToolCallFiles()
2. Sandbox service calls syncReadonlyFiles() on the provider session
3. Agent invokes a sandbox tool → provider POSTs to the runtime HTTP server
4. Runtime validates path, executes the operation, returns result
5. Handler calls onTurnEnded() → persists updated providerSessionId via saveState() 2

Architectural Evolution: Standalone to packages/shared#

PR #15421 1 refactored the entire in-app-agent runtime — including sandbox infrastructure — from web/src/ee/features/in-app-agent/ into packages/shared/src/in-app-agent/ as 23 renamed files with no behavior changes.

Motivation: The background-execution RFC requires the agent executor to run in a worker. Rather than maintaining two copies of the ~6k-line agent loop during the canary window, the runtime is centralized once in shared. Web imports from there today; the worker's background processor will import the same modules 1.

Module boundary enforcement:

• @langfuse/shared/in-app-agent — client-safe contracts only (Zod schemas, constants, id helpers)
• @langfuse/shared/in-app-agent/server (+ per-module subpaths) — runtime code; never re-exported through the client entry 1
• CI's pnpm run scan:client-bundle guards this boundary automatically 1

Other changes in this refactor:

• The system prompt moved from a .txt asset to a checked-in TypeScript module, enabling compilation under plain tsc without a bundler — required for worker compatibility 1
• LANGFUSE_IN_APP_AGENT_SANDBOX_* and AWS_PROFILE env vars moved into the shared env schema 1
• Web's vitest.config.mts was updated to alias all @langfuse/shared entry points to source files (not dist), preventing vi.mock bypass and split-brain module instances in tests 1
• A pnpm alias ai-sdk-amazon-bedrock-v4 handles a version conflict between Mastra's pinned @ai-sdk/amazon-bedrock@4.0.81 and shared's ^5 1

Developer impact: Editing runtime/sandbox code now requires working in packages/shared and running tsc --watch there (already part of pnpm run dev) 1.