From 3347b403e7a9c3c0b4442211b410c637b32f584f Mon Sep 17 00:00:00 2001 From: Theo Browne Date: Sat, 3 Oct 2026 14:52:07 -0700 Subject: [PATCH] feat: threads can run in Docker sandboxes with their own ports and services A new "New sandbox" workspace choice creates a worktree plus one Docker container for it. The thread's agent (Claude or Codex), terminals, and setup script run inside, so parallel threads can each run an app on the same port with their own database. Worktree files stay on the host through same-path mounts, and a stdio relay over docker exec forwards container ports to host loopback and T3's MCP port into the container. Co-Authored-By: Claude Opus 5.5 (1M context) --- .../features/threads/NewTaskDraftScreen.tsx | 88 +- .../features/threads/git/GitOverviewSheet.tsx | 2 + .../threads/git/ThreadSandboxCard.tsx | 132 +++ .../new-task-context-presentation.test.ts | 45 + .../threads/new-task-context-presentation.ts | 25 +- .../threads/new-task-flow-provider.tsx | 42 +- .../features/threads/worktree-setup-card.tsx | 4 +- .../src/lib/projectThreadStartTurn.test.ts | 31 + apps/mobile/src/lib/projectThreadStartTurn.ts | 3 + apps/mobile/src/state/thread-outbox-model.ts | 3 + apps/mobile/src/state/use-composer-drafts.ts | 6 +- .../src/state/use-thread-outbox-drain.ts | 2 + apps/server/src/auth/RpcAuthorization.ts | 3 + apps/server/src/git/GitWorkflowService.ts | 17 + apps/server/src/mcp/toolkits/project/tools.ts | 2 +- .../Adapters/ClaudeAdapterV2.ts | 50 +- .../Adapters/CodexAdapterV2.ts | 72 +- .../src/orchestration-v2/IdAllocator.ts | 16 +- .../src/orchestration-v2/Orchestrator.ts | 180 ++- .../ProviderSessionManager.ts | 105 +- .../orchestration-v2/ThreadLaunchService.ts | 41 +- apps/server/src/preview/PortScanner.ts | 40 +- apps/server/src/processRunner.ts | 7 +- .../src/project/ProjectSetupScriptRunner.ts | 7 +- .../server/src/sandbox/SandboxService.test.ts | 42 + apps/server/src/sandbox/SandboxService.ts | 1040 +++++++++++++++++ apps/server/src/sandbox/SandboxTunnel.test.ts | 125 ++ apps/server/src/sandbox/SandboxTunnel.ts | 517 ++++++++ apps/server/src/sandbox/sandboxClaudeSpawn.ts | 39 + apps/server/src/sandbox/sandboxDocker.test.ts | 82 ++ apps/server/src/sandbox/sandboxDocker.ts | 247 ++++ apps/server/src/server.ts | 2 + apps/server/src/terminal/Manager.ts | 70 +- apps/server/src/ws.ts | 38 + .../components/BranchToolbar.logic.test.ts | 27 + .../web/src/components/BranchToolbar.logic.ts | 31 +- apps/web/src/components/BranchToolbar.tsx | 35 +- .../BranchToolbarBranchSelector.tsx | 8 +- .../BranchToolbarEnvModeSelector.tsx | 39 +- apps/web/src/components/ChatView.logic.ts | 2 +- apps/web/src/components/ChatView.tsx | 29 +- apps/web/src/components/GitActionsControl.tsx | 4 +- .../chat/ThreadDetailsPanel.test.tsx | 5 + .../components/chat/ThreadDetailsPanel.tsx | 14 + .../components/chat/ThreadSandboxControl.tsx | 161 +++ .../src/components/chat/WorktreeSetupCard.tsx | 26 +- apps/web/src/composerDraftStore.ts | 6 +- apps/web/src/lib/chatThreadActions.ts | 2 +- docs/README.md | 2 + docs/internals/sandboxes.md | 63 + docs/user/sandboxes.md | 45 + .../client-runtime/src/operations/commands.ts | 3 + packages/client-runtime/src/rpc/client.ts | 1 + packages/client-runtime/src/state/vcs.ts | 25 + packages/contracts/src/index.ts | 1 + packages/contracts/src/orchestrationV2.ts | 2 + packages/contracts/src/rpc.ts | 26 + packages/contracts/src/sandbox.ts | 56 + packages/contracts/src/server.ts | 5 + packages/contracts/src/worktreeSetup.ts | 4 + 60 files changed, 3586 insertions(+), 161 deletions(-) create mode 100644 apps/mobile/src/features/threads/git/ThreadSandboxCard.tsx create mode 100644 apps/server/src/sandbox/SandboxService.test.ts create mode 100644 apps/server/src/sandbox/SandboxService.ts create mode 100644 apps/server/src/sandbox/SandboxTunnel.test.ts create mode 100644 apps/server/src/sandbox/SandboxTunnel.ts create mode 100644 apps/server/src/sandbox/sandboxClaudeSpawn.ts create mode 100644 apps/server/src/sandbox/sandboxDocker.test.ts create mode 100644 apps/server/src/sandbox/sandboxDocker.ts create mode 100644 apps/web/src/components/chat/ThreadSandboxControl.tsx create mode 100644 docs/internals/sandboxes.md create mode 100644 docs/user/sandboxes.md create mode 100644 packages/contracts/src/sandbox.ts diff --git a/apps/mobile/src/features/threads/NewTaskDraftScreen.tsx b/apps/mobile/src/features/threads/NewTaskDraftScreen.tsx index 1ee4e9bc4e852..5ba8abf06c068 100644 --- a/apps/mobile/src/features/threads/NewTaskDraftScreen.tsx +++ b/apps/mobile/src/features/threads/NewTaskDraftScreen.tsx @@ -50,6 +50,7 @@ import { ComposerToolbarRow, } from "../../components/ComposerToolbar"; import { AndroidScreenHeader } from "../../components/AndroidScreenHeader"; +import { ControlPillMenu } from "../../components/ControlPill"; import { MaterialScreenContent } from "../../components/MaterialScreenContent"; import { ComposerAttachmentButton } from "../../components/ComposerAttachmentButton"; import { ComposerAttachmentStrip } from "../../components/ComposerAttachmentStrip"; @@ -122,6 +123,7 @@ import { resolveDraftProjectSelection } from "./new-task-project-selection"; import { resolveNewTaskBranchLabel, resolveNewTaskWorkspaceLabel, + type NewTaskWorkspaceChoice, } from "./new-task-context-presentation"; import { useIncomingShare } from "../sharing/IncomingShareProvider"; import { selectIncomingShareAttachmentsForServer } from "../sharing/incoming-share-model"; @@ -129,9 +131,20 @@ import { appAtomRegistry } from "../../state/atom-registry"; import { serverEnvironment } from "../../state/server"; import { fileRoutePathSegments } from "../files/filePath"; +const WORKSPACE_CHOICES = [ + { id: "local", title: "Current checkout" }, + { id: "worktree", title: "New worktree" }, + { id: "sandbox", title: "New sandbox", subtitle: "New worktree in a Docker container" }, +] as const satisfies ReadonlyArray<{ + readonly id: NewTaskWorkspaceChoice; + readonly title: string; + readonly subtitle?: string; +}>; + function NewTaskWorkspaceIcon(props: { readonly workspaceMode: "local" | "worktree"; readonly worktreePath: string | null; + readonly sandbox: boolean; readonly size: number; }) { if (props.workspaceMode === "local" && props.worktreePath === null) { @@ -164,7 +177,7 @@ function NewTaskWorkspaceIcon(props: { } > { @@ -1549,24 +1565,62 @@ export function NewTaskDraftScreen(props: { ); + const workspaceControlDisabled = isComposerInteractionLocked || voiceInput.isBusy; + // Two workspaces toggle on tap. A server that offers sandboxes adds a third, + // so the control opens a menu instead. + const offersWorkspaceMenu = flow.canUseSandbox && !workspaceControlDisabled; + const workspaceControl = ( + ( + + )} + label={workspaceLabel} + maxWidth={flow.workspaceMode === "local" ? 220 : 148} + onPress={ + offersWorkspaceMenu + ? undefined + : () => flow.setWorkspaceChoice(flow.workspaceMode === "local" ? "worktree" : "local") + } + showChevron={offersWorkspaceMenu} + /> + ); + const workspaceControls = ( - ( - - )} - label={workspaceLabel} - maxWidth={flow.workspaceMode === "local" ? 220 : 148} - onPress={() => flow.setWorkspaceMode(flow.workspaceMode === "local" ? "worktree" : "local")} - showChevron={false} - /> + {offersWorkspaceMenu ? ( + ({ + ...choice, + ...(choice.id === "local" && flow.workspaceMode === "local" + ? { title: workspaceLabel } + : {}), + state: choice.id === workspaceChoice ? ("on" as const) : ("off" as const), + }))} + onPressAction={({ nativeEvent }) => { + const choice = WORKSPACE_CHOICES.find( + (candidate) => candidate.id === nativeEvent.event, + ); + if (choice) flow.setWorkspaceChoice(choice.id); + }} + > + {workspaceControl} + + ) : ( + workspaceControl + )} : null} + ); diff --git a/apps/mobile/src/features/threads/git/ThreadSandboxCard.tsx b/apps/mobile/src/features/threads/git/ThreadSandboxCard.tsx new file mode 100644 index 0000000000000..b772d91cebd1f --- /dev/null +++ b/apps/mobile/src/features/threads/git/ThreadSandboxCard.tsx @@ -0,0 +1,132 @@ +import { + isAtomCommandInterrupted, + squashAtomCommandFailure, +} from "@t3tools/client-runtime/state/runtime"; +import { findSandboxForWorktree } from "@t3tools/client-runtime/state/vcs"; +import type { EnvironmentId, SandboxStatus } from "@t3tools/contracts"; +import { useState } from "react"; +import { Alert, Platform, View } from "react-native"; + +import { AppText as Text } from "../../../components/AppText"; +import { showConfirmDialog } from "../../../components/ConfirmDialogHost"; +import { cn } from "../../../lib/cn"; +import { useEnvironmentServerConfig } from "../../../state/entities"; +import { useEnvironmentQuery } from "../../../state/query"; +import { useAtomCommand } from "../../../state/use-atom-command"; +import { vcsEnvironment } from "../../../state/vcs"; +import { SheetListRow } from "./gitSheetComponents"; + +const STATUS_LABEL: Record = { + starting: "Starting", + running: "Running", + stopped: "Stopped", + error: "Error", +}; + +function confirmRemove(onConfirm: () => void) { + const title = "Remove sandbox?"; + const message = "Later work in this worktree then runs on the host."; + if (Platform.OS === "ios") { + Alert.alert(title, message, [ + { text: "Cancel", style: "cancel" }, + { text: "Remove", style: "destructive", onPress: onConfirm }, + ]); + return; + } + showConfirmDialog({ title, message, confirmText: "Remove", destructive: true, onConfirm }); +} + +/** + * Status, forwarded ports, and stop/remove actions for a thread whose worktree + * runs in a Docker sandbox. Renders nothing for other threads, and only + * subscribes to the sandbox list when the server can run sandboxes. + */ +export function ThreadSandboxCard(props: { + readonly environmentId: EnvironmentId; + readonly worktreePath: string | null; +}) { + const serverConfig = useEnvironmentServerConfig(props.environmentId); + const sandboxes = useEnvironmentQuery( + serverConfig?.sandboxes === true && props.worktreePath !== null + ? vcsEnvironment.sandboxes({ environmentId: props.environmentId, input: {} }) + : null, + ); + const sandbox = findSandboxForWorktree(sandboxes.data?.sandboxes, props.worktreePath); + const stopSandbox = useAtomCommand(vcsEnvironment.stopSandbox, { reportFailure: false }); + const removeSandbox = useAtomCommand(vcsEnvironment.removeSandbox, { reportFailure: false }); + const [busy, setBusy] = useState(false); + + if (!sandbox) return null; + const canStop = sandbox.status === "running" || sandbox.status === "starting"; + const { worktreePath } = sandbox; + const run = async (failureTitle: string, command: typeof stopSandbox) => { + setBusy(true); + try { + const result = await command({ environmentId: props.environmentId, input: { worktreePath } }); + if (result._tag === "Success" || isAtomCommandInterrupted(result)) return; + const cause = squashAtomCommandFailure(result); + Alert.alert(failureTitle, cause instanceof Error ? cause.message : undefined); + } finally { + setBusy(false); + } + }; + + return ( + + + + Sandbox + + + {STATUS_LABEL[sandbox.status]} · {sandbox.containerName} + + {sandbox.status === "error" && sandbox.error ? ( + + {sandbox.error} + + ) : null} + {sandbox.ports.map((port) => ( + + :{port.containerPort} → 127.0.0.1:{port.hostPort} + + ))} + + + {canStop ? ( + <> + {Platform.OS !== "android" ? : null} + void run("Could not stop sandbox", stopSandbox)} + /> + + ) : null} + {Platform.OS !== "android" ? ( + + ) : null} + confirmRemove(() => void run("Could not remove sandbox", removeSandbox))} + /> + + + ); +} diff --git a/apps/mobile/src/features/threads/new-task-context-presentation.test.ts b/apps/mobile/src/features/threads/new-task-context-presentation.test.ts index f48ba92396e90..64ad720db1b41 100644 --- a/apps/mobile/src/features/threads/new-task-context-presentation.test.ts +++ b/apps/mobile/src/features/threads/new-task-context-presentation.test.ts @@ -5,8 +5,53 @@ import { resolveNewTaskBranchWorktreePath, resolveNewTaskBranchLabel, resolveNewTaskLocalWorkspaceSelection, + resolveNewTaskSandbox, + resolveNewTaskWorkspaceLabel, } from "./new-task-context-presentation"; +describe("resolveNewTaskSandbox", () => { + it("keeps a sandbox choice only for new worktrees", () => { + const serverConfig = { sandboxes: true }; + expect( + resolveNewTaskSandbox({ workspaceMode: "worktree", draftSandbox: true, serverConfig }), + ).toBe(true); + expect( + resolveNewTaskSandbox({ workspaceMode: "local", draftSandbox: true, serverConfig }), + ).toBe(false); + }); + + it("drops the choice on a server without sandboxes", () => { + expect( + resolveNewTaskSandbox({ workspaceMode: "worktree", draftSandbox: true, serverConfig: {} }), + ).toBe(false); + }); + + it("keeps the choice while the server config is unknown", () => { + expect( + resolveNewTaskSandbox({ workspaceMode: "worktree", draftSandbox: true, serverConfig: null }), + ).toBe(true); + }); +}); + +describe("resolveNewTaskWorkspaceLabel", () => { + it("names a sandboxed worktree", () => { + expect( + resolveNewTaskWorkspaceLabel({ + workspaceMode: "worktree", + worktreePath: null, + sandbox: true, + }), + ).toBe("New sandbox"); + expect( + resolveNewTaskWorkspaceLabel({ + workspaceMode: "worktree", + worktreePath: null, + sandbox: false, + }), + ).toBe("New worktree"); + }); +}); + describe("resolveNewTaskLocalWorkspaceSelection", () => { it("waits for refs instead of carrying a worktree base into Current checkout", () => { expect( diff --git a/apps/mobile/src/features/threads/new-task-context-presentation.ts b/apps/mobile/src/features/threads/new-task-context-presentation.ts index 87c9b2595f4f2..1a0146c9fc908 100644 --- a/apps/mobile/src/features/threads/new-task-context-presentation.ts +++ b/apps/mobile/src/features/threads/new-task-context-presentation.ts @@ -2,12 +2,33 @@ import { sanitizeNewRefName } from "@t3tools/shared/git"; type WorkspaceMode = "local" | "worktree"; +/** The workspace picker's options. A sandbox is a new worktree that runs in Docker. */ +export type NewTaskWorkspaceChoice = "local" | "worktree" | "sandbox"; + +/** + * Whether a new task starts in a sandbox. The draft keeps the user's choice; + * a server that does not offer sandboxes drops it, and an unknown config + * (offline or still loading) keeps it so editing a queued task cannot lose it. + */ +export function resolveNewTaskSandbox(input: { + readonly workspaceMode: WorkspaceMode; + readonly draftSandbox: boolean | undefined; + readonly serverConfig: { readonly sandboxes?: boolean } | null; +}): boolean { + return ( + input.workspaceMode === "worktree" && + input.draftSandbox === true && + (input.serverConfig === null || input.serverConfig.sandboxes === true) + ); +} + export function resolveNewTaskWorkspaceLabel(input: { readonly workspaceMode: WorkspaceMode; readonly worktreePath: string | null; -}): "Current checkout" | "Current worktree" | "New worktree" { + readonly sandbox: boolean; +}): "Current checkout" | "Current worktree" | "New worktree" | "New sandbox" { if (input.workspaceMode === "worktree") { - return "New worktree"; + return input.sandbox ? "New sandbox" : "New worktree"; } return input.worktreePath ? "Current worktree" : "Current checkout"; } diff --git a/apps/mobile/src/features/threads/new-task-flow-provider.tsx b/apps/mobile/src/features/threads/new-task-flow-provider.tsx index 18c023b45ee11..eed54123694b8 100644 --- a/apps/mobile/src/features/threads/new-task-flow-provider.tsx +++ b/apps/mobile/src/features/threads/new-task-flow-provider.tsx @@ -108,6 +108,8 @@ import { filterNewTaskBranches, resolveNewTaskBranchWorktreePath, resolveNewTaskLocalWorkspaceSelection, + resolveNewTaskSandbox, + type NewTaskWorkspaceChoice, } from "./new-task-context-presentation"; import { resolveEnvironmentProjectMatch } from "./new-task-project-selection"; import { resolveProjectThreadCreationBranch } from "./projectThreadCreationValidation"; @@ -158,8 +160,12 @@ type NewTaskFlowContextValue = { readonly selectedProjectKey: string | null; readonly selectedModelKey: string | null; readonly workspaceMode: WorkspaceMode; + /** Worktree mode only: the new worktree runs in a Docker sandbox. */ + readonly sandbox: boolean; /** False for threads without a project: their folder has no branch or worktree. */ readonly canChooseWorkspace: boolean; + /** True when the selected server can create sandboxes. */ + readonly canUseSandbox: boolean; readonly selectedBranchName: string | null; readonly selectedWorktreePath: string | null; readonly startFromOrigin: boolean; @@ -205,7 +211,7 @@ type NewTaskFlowContextValue = { key: string | null, options?: ReadonlyArray, ) => void; - readonly setWorkspaceMode: (mode: WorkspaceMode) => void; + readonly setWorkspaceChoice: (choice: NewTaskWorkspaceChoice) => void; readonly selectBranch: (branch: VcsRef) => void; readonly setStartFromOrigin: (value: boolean) => void; readonly beginEditingPendingTask: (messageId: string) => boolean; @@ -511,6 +517,12 @@ export function NewTaskFlowProvider(props: React.PropsWithChildren) { const workspaceMode = canChooseWorkspace ? (selectedProjectDraft.workspaceSelection?.mode ?? defaultWorkspaceMode) : "local"; + const sandbox = resolveNewTaskSandbox({ + workspaceMode, + draftSandbox: selectedProjectDraft.workspaceSelection?.sandbox, + serverConfig: selectedEnvironmentServerConfig, + }); + const canUseSandbox = canChooseWorkspace && selectedEnvironmentServerConfig?.sandboxes === true; const selectedBranchName = selectedProjectDraft.workspaceSelection?.branch ?? null; const selectedWorktreePath = selectedProjectDraft.workspaceSelection?.worktreePath ?? null; // Keep the user's explicit choice separate from the resolved display value: @@ -796,14 +808,15 @@ export function NewTaskFlowProvider(props: React.PropsWithChildren) { [projects, selectedProject, carryDraftContentTo], ); - const setWorkspaceMode = useCallback( - (mode: WorkspaceMode) => { + const setWorkspaceChoice = useCallback( + (choice: NewTaskWorkspaceChoice) => { if (!selectedProjectDraftKey) { return; } if (!selectedProject) { return; } + const mode: WorkspaceMode = choice === "local" ? "local" : "worktree"; const localSelection = resolveNewTaskLocalWorkspaceSelection({ branches: availableBranches, projectCwd: selectedProject.workspaceRoot, @@ -819,6 +832,7 @@ export function NewTaskFlowProvider(props: React.PropsWithChildren) { branch: mode === "local" ? localSelection.branch : selectedBranchName, worktreePath: mode === "local" ? localSelection.worktreePath : selectedWorktreePath, ...(draftStartFromOrigin !== undefined ? { startFromOrigin: draftStartFromOrigin } : {}), + ...(choice === "sandbox" ? { sandbox: true } : {}), }, }); }, @@ -882,10 +896,11 @@ export function NewTaskFlowProvider(props: React.PropsWithChildren) { branchWorktreePath: branch.worktreePath, }), ...(draftStartFromOrigin !== undefined ? { startFromOrigin: draftStartFromOrigin } : {}), + ...(sandbox ? { sandbox: true } : {}), }, }); }, - [draftStartFromOrigin, selectedProject, selectedProjectDraftKey, workspaceMode], + [draftStartFromOrigin, sandbox, selectedProject, selectedProjectDraftKey, workspaceMode], ); const setStartFromOrigin = useCallback( @@ -899,10 +914,11 @@ export function NewTaskFlowProvider(props: React.PropsWithChildren) { branch: selectedBranchName, worktreePath: selectedWorktreePath, startFromOrigin: value, + ...(sandbox ? { sandbox: true } : {}), }, }); }, - [selectedBranchName, selectedProjectDraftKey, selectedWorktreePath, workspaceMode], + [sandbox, selectedBranchName, selectedProjectDraftKey, selectedWorktreePath, workspaceMode], ); const refreshBranches = branchState.refresh; @@ -989,6 +1005,7 @@ export function NewTaskFlowProvider(props: React.PropsWithChildren) { branch: message.creation.branch, worktreePath: message.creation.worktreePath, startFromOrigin: message.creation.startFromOrigin ?? false, + ...(message.creation.sandbox ? { sandbox: true } : {}), }, }); } @@ -1080,6 +1097,13 @@ export function NewTaskFlowProvider(props: React.PropsWithChildren) { ...((workspaceSelection?.startFromOrigin ?? startFromOrigin) ? { startFromOrigin: true } : {}), + ...(resolveNewTaskSandbox({ + workspaceMode: mode, + draftSandbox: workspaceSelection?.sandbox, + serverConfig: selectedEnvironmentServerConfig, + }) + ? { sandbox: true } + : {}), }, createdAt: metadata.createdAt, }; @@ -1209,7 +1233,9 @@ export function NewTaskFlowProvider(props: React.PropsWithChildren) { selectedProjectKey, selectedModelKey, workspaceMode, + sandbox, canChooseWorkspace, + canUseSandbox, selectedBranchName, selectedWorktreePath, startFromOrigin, @@ -1243,7 +1269,7 @@ export function NewTaskFlowProvider(props: React.PropsWithChildren) { openDraft, selectEnvironment, setSelectedModelKey, - setWorkspaceMode, + setWorkspaceChoice, selectBranch, setStartFromOrigin, beginEditingPendingTask, @@ -1313,11 +1339,13 @@ export function NewTaskFlowProvider(props: React.PropsWithChildren) { setRuntimeMode, setSelectedModelKey, setStartFromOrigin, - setWorkspaceMode, + setWorkspaceChoice, startFromOrigin, submitting, workspaceMode, + sandbox, canChooseWorkspace, + canUseSandbox, appendAttachments, clearAttachments, removeAttachment, diff --git a/apps/mobile/src/features/threads/worktree-setup-card.tsx b/apps/mobile/src/features/threads/worktree-setup-card.tsx index 86b71992710f8..9e5f1446fd8c3 100644 --- a/apps/mobile/src/features/threads/worktree-setup-card.tsx +++ b/apps/mobile/src/features/threads/worktree-setup-card.tsx @@ -220,13 +220,13 @@ function SetupDetailsSheet({ paddingBottom: Math.max(20, insets.bottom), }} > - {/* Agent startup is the header handoff, not a fifth setup step. */} + {/* Agent startup is the header handoff, not another setup step. */} {snapshot.stages .filter((stage) => stage.id !== "agent") .map((stage) => ( - {stage.id === "setup-script" && + {(stage.id === "setup-script" || stage.id === "sandbox") && (stage.status === "running" || stage.status === "failed" || stage.tail.length > 0) ? ( ) : null} diff --git a/apps/mobile/src/lib/projectThreadStartTurn.test.ts b/apps/mobile/src/lib/projectThreadStartTurn.test.ts index f67a4649facef..b24fd5ecba077 100644 --- a/apps/mobile/src/lib/projectThreadStartTurn.test.ts +++ b/apps/mobile/src/lib/projectThreadStartTurn.test.ts @@ -135,3 +135,34 @@ describe("new thread on an existing branch", () => { }, ); }); + +describe("new thread in a sandbox", () => { + it("asks the server to prepare the new worktree in a sandbox", () => { + const input = buildProjectThreadStartTurnInput({ + projectId: ProjectId.make("project"), + projectCwd: "/workspace", + threadId: "sandbox-thread", + commandId: "command", + messageId: "message", + createdAt: "2026-10-03T00:00:00Z", + text: "Run the services", + uploadedAttachments: [], + modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5.6-sol" }, + runtimeMode: "full-access", + interactionMode: "default", + workspaceMode: "worktree", + branch: "main", + worktreePath: null, + startFromOrigin: false, + sandbox: true, + worktreeBranchName: "t3code/abc123", + }); + + expect(input.bootstrap.prepareWorktree).toEqual({ + projectCwd: "/workspace", + baseBranch: "main", + branch: "t3code/abc123", + sandbox: true, + }); + }); +}); diff --git a/apps/mobile/src/lib/projectThreadStartTurn.ts b/apps/mobile/src/lib/projectThreadStartTurn.ts index fa1cc704219a6..c3ab7a9c3fdd3 100644 --- a/apps/mobile/src/lib/projectThreadStartTurn.ts +++ b/apps/mobile/src/lib/projectThreadStartTurn.ts @@ -32,6 +32,8 @@ export interface ProjectThreadStartTurnSpec { readonly branch: string | null; readonly worktreePath: string | null; readonly startFromOrigin: boolean; + /** Worktree mode only: run the new worktree in a Docker sandbox. */ + readonly sandbox?: boolean; /** Generated temp branch for worktree mode; unused for local mode. */ readonly worktreeBranchName: string; } @@ -77,6 +79,7 @@ export function buildProjectThreadStartTurnInput(spec: ProjectThreadStartTurnSpe baseBranch: spec.branch!, branch: spec.worktreeBranchName, ...(spec.startFromOrigin ? { startFromOrigin: true } : {}), + ...(spec.sandbox ? { sandbox: true } : {}), }, runSetupScript: true, } diff --git a/apps/mobile/src/state/thread-outbox-model.ts b/apps/mobile/src/state/thread-outbox-model.ts index 57a788cf5188f..c046d88b53fa4 100644 --- a/apps/mobile/src/state/thread-outbox-model.ts +++ b/apps/mobile/src/state/thread-outbox-model.ts @@ -43,6 +43,7 @@ const QueuedThreadCreationSchema = Schema.Struct({ branch: Schema.NullOr(Schema.String), worktreePath: Schema.NullOr(Schema.String), startFromOrigin: Schema.optional(Schema.Boolean), + sandbox: Schema.optional(Schema.Boolean), }); export const QueuedThreadMessageSchema = Schema.Struct({ @@ -75,6 +76,8 @@ export interface QueuedThreadCreation { readonly branch: string | null; readonly worktreePath: string | null; readonly startFromOrigin?: boolean; + /** Worktree mode only: run the new worktree in a Docker sandbox. */ + readonly sandbox?: boolean; } export interface QueuedThreadMessage { diff --git a/apps/mobile/src/state/use-composer-drafts.ts b/apps/mobile/src/state/use-composer-drafts.ts index 780485c0718f6..70a4a47f3db37 100644 --- a/apps/mobile/src/state/use-composer-drafts.ts +++ b/apps/mobile/src/state/use-composer-drafts.ts @@ -359,6 +359,8 @@ export interface ComposerDraftWorkspaceSelection { readonly branch: string | null; readonly worktreePath: string | null; readonly startFromOrigin?: boolean; + /** Worktree mode only: run the new worktree in a Docker sandbox. */ + readonly sandbox?: boolean; } export type ComposerDraftSettingsUpdate = Pick< @@ -371,6 +373,7 @@ const ComposerDraftWorkspaceSelectionSchema = Schema.Struct({ branch: Schema.NullOr(Schema.String), worktreePath: Schema.NullOr(Schema.String), startFromOrigin: Schema.optional(Schema.Boolean), + sandbox: Schema.optional(Schema.Boolean), }); const ComposerDraftProjectSchema = Schema.Struct({ @@ -1196,7 +1199,8 @@ export async function removeDeliveredCloudQueuedMessage( editor.workspaceSelection.branch !== message.creation?.branch || editor.workspaceSelection.worktreePath !== message.creation?.worktreePath || (editor.workspaceSelection.startFromOrigin ?? false) !== - (message.creation?.startFromOrigin ?? false)))) + (message.creation?.startFromOrigin ?? false) || + (editor.workspaceSelection.sandbox ?? false) !== (message.creation?.sandbox ?? false)))) ) continue; const drafts = { ...saved.drafts }; diff --git a/apps/mobile/src/state/use-thread-outbox-drain.ts b/apps/mobile/src/state/use-thread-outbox-drain.ts index 454980d404a5a..0237913b4573c 100644 --- a/apps/mobile/src/state/use-thread-outbox-drain.ts +++ b/apps/mobile/src/state/use-thread-outbox-drain.ts @@ -508,6 +508,7 @@ export async function restoreRejectedQueuedMessage( ...(queuedMessage.creation.startFromOrigin !== undefined ? { startFromOrigin: queuedMessage.creation.startFromOrigin } : {}), + ...(queuedMessage.creation.sandbox ? { sandbox: true } : {}), }, } : {}), @@ -1029,6 +1030,7 @@ export function useThreadOutboxDrain(): void { branch: creation.branch, worktreePath: creation.worktreePath, startFromOrigin: creation.startFromOrigin ?? false, + sandbox: creation.sandbox === true, worktreeBranchName: buildTemporaryWorktreeBranchName(randomHex), }), }); diff --git a/apps/server/src/auth/RpcAuthorization.ts b/apps/server/src/auth/RpcAuthorization.ts index 046bf8ab2186e..40a18fb7d7cef 100644 --- a/apps/server/src/auth/RpcAuthorization.ts +++ b/apps/server/src/auth/RpcAuthorization.ts @@ -151,6 +151,9 @@ export const RPC_REQUIRED_SCOPES = { [WS_METHODS.subscribeVcsStatus]: AuthOrchestrationReadScope, [WS_METHODS.subscribeWorktreeSetup]: AuthOrchestrationReadScope, [WS_METHODS.worktreeSetupCancel]: AuthOrchestrationOperateScope, + [WS_METHODS.subscribeSandboxes]: AuthOrchestrationReadScope, + [WS_METHODS.sandboxStop]: AuthOrchestrationOperateScope, + [WS_METHODS.sandboxRemove]: AuthOrchestrationOperateScope, [WS_METHODS.subscribeResourceTelemetry]: AuthOrchestrationReadScope, [WS_METHODS.vcsRefreshStatus]: AuthOrchestrationReadScope, [WS_METHODS.vcsPull]: AuthOrchestrationOperateScope, diff --git a/apps/server/src/git/GitWorkflowService.ts b/apps/server/src/git/GitWorkflowService.ts index 912e0c1f46208..8d84f402418c9 100644 --- a/apps/server/src/git/GitWorkflowService.ts +++ b/apps/server/src/git/GitWorkflowService.ts @@ -1,6 +1,7 @@ import * as Context from "effect/Context"; import * as Effect from "effect/Effect"; import * as Layer from "effect/Layer"; +import * as Option from "effect/Option"; import { GitManagerError, @@ -29,6 +30,7 @@ import { } from "@t3tools/contracts"; import * as GitManager from "./GitManager.ts"; +import * as SandboxService from "../sandbox/SandboxService.ts"; import * as GitVcsDriver from "../vcs/GitVcsDriver.ts"; import * as VcsDriverRegistry from "../vcs/VcsDriverRegistry.ts"; @@ -159,6 +161,7 @@ export const make = Effect.gen(function* () { const registry = yield* VcsDriverRegistry.VcsDriverRegistry; const git = yield* GitVcsDriver.GitVcsDriver; const gitManager = yield* GitManager.GitManager; + const sandboxes = yield* Effect.serviceOption(SandboxService.SandboxService); const ensureGit = Effect.fn("GitWorkflowService.ensureGit")(function* ( operation: string, @@ -372,6 +375,20 @@ export const make = Effect.gen(function* () { removeWorktree: (input) => ensureGitCommand("GitWorkflowService.removeWorktree", input.cwd).pipe( Effect.andThen(git.removeWorktree(input)), + // A removed worktree's sandbox has nothing left to run. A failure + // here only leaves the container behind; startup drops it later. + Effect.tap(() => + Option.isNone(sandboxes) + ? Effect.void + : sandboxes.value.remove(input.path).pipe( + Effect.catchCause((cause) => + Effect.logWarning("Failed to remove the worktree's sandbox", { + path: input.path, + cause, + }), + ), + ), + ), ), pruneWorktrees: (input) => ensureGitCommand("GitWorkflowService.pruneWorktrees", input.cwd).pipe( diff --git a/apps/server/src/mcp/toolkits/project/tools.ts b/apps/server/src/mcp/toolkits/project/tools.ts index 693a76854bb66..528e65dd813f8 100644 --- a/apps/server/src/mcp/toolkits/project/tools.ts +++ b/apps/server/src/mcp/toolkits/project/tools.ts @@ -102,7 +102,7 @@ const ProjectCloneTool = Tool.make("t3_project_clone", { const ThreadLaunchTool = Tool.make("t3_thread_launch", { ...shared, description: - 'Create an ordinary TOP-LEVEL thread with an explicit workspace binding before its agent starts. Use this when the user requests independent work, a new thread, or a PR stack in its own worktree; use delegate_task for child subagents. Set workspaceStrategy to {type:"worktree",baseRef:"parent-branch",branch:"new-branch",startFromOrigin:false} for a new worktree based on local commits, or {type:"existing_worktree",worktreePath:"/absolute/path",branch:"existing-branch"} to use an existing checkout. For upstream commits, set startFromOrigin:true. Omitted workspaceStrategy means the project root, NOT the caller\'s worktree. Omit projectId/modelSelection/modes to inherit those settings. Set scratch:true instead of projectId for a thread without a project: it runs in a fresh folder of its own, outside any repository. Put the task in message. Do not ask the agent to create its own worktree via shell: that does not update the thread binding. Each call creates a new launch with no retry key; retain threadId and use t3_thread_read/t3_thread_wait to follow preparation. After errors or lost responses, inspect t3_thread_list before retrying. Attachments must be pending uploads. Requires a full-access/default caller.', + 'Create an ordinary TOP-LEVEL thread with an explicit workspace binding before its agent starts. Use this when the user requests independent work, a new thread, or a PR stack in its own worktree; use delegate_task for child subagents. Set workspaceStrategy to {type:"worktree",baseRef:"parent-branch",branch:"new-branch",startFromOrigin:false} for a new worktree based on local commits, or {type:"existing_worktree",worktreePath:"/absolute/path",branch:"existing-branch"} to use an existing checkout. For upstream commits, set startFromOrigin:true. Add sandbox:true to a worktree strategy to run the thread\'s agent, terminals, and setup script in a Docker sandbox with its own ports and services (Claude and Codex only). Omitted workspaceStrategy means the project root, NOT the caller\'s worktree. Omit projectId/modelSelection/modes to inherit those settings. Set scratch:true instead of projectId for a thread without a project: it runs in a fresh folder of its own, outside any repository. Put the task in message. Do not ask the agent to create its own worktree via shell: that does not update the thread binding. Each call creates a new launch with no retry key; retain threadId and use t3_thread_read/t3_thread_wait to follow preparation. After errors or lost responses, inspect t3_thread_list before retrying. Attachments must be pending uploads. Requires a full-access/default caller.', parameters: Schema.Struct({ projectId: Schema.optional(ProjectId), scratch: Schema.optional( diff --git a/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts b/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts index 0aca36abe77c6..4d67452f63c37 100644 --- a/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts +++ b/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts @@ -33,7 +33,7 @@ import type { WebSearchOutput, } from "@anthropic-ai/claude-agent-sdk/sdk-tools"; import { parseCliArgs } from "@t3tools/shared/cliArgs"; -import { HostProcessEnvironment } from "@t3tools/shared/hostProcess"; +import { HostProcessEnvironment, HostProcessPlatform } from "@t3tools/shared/hostProcess"; import { applyClaudePromptEffortPrefix } from "@t3tools/shared/model"; import { CLAUDE_RESUME_COMPACTION_NEVER_ANSWER, @@ -92,6 +92,8 @@ import { planClaudeSkillDispatch } from "../../provider/Drivers/ClaudeSkillDispa import { discoverClaudeSkills } from "../../provider/Drivers/ClaudeSkills.ts"; import { compileClaudeModelSelection } from "../../claudeModelOptions.ts"; import * as ServerConfig from "../../config.ts"; +import { sandboxClaudeSpawn } from "../../sandbox/sandboxClaudeSpawn.ts"; +import * as SandboxService from "../../sandbox/SandboxService.ts"; import { expandHomePath } from "../../pathExpansion.ts"; import { claudeSignedOutMessage, @@ -801,6 +803,8 @@ export const claudeAgentSdkQueryRunnerLiveLayer: Layer.Layer< ); export function makeClaudeQueryOptions(input: { + /** Set for sandboxed worktrees: starts the CLI inside the sandbox. */ + readonly spawnClaudeCodeProcess?: ClaudeQueryOptions["spawnClaudeCodeProcess"]; readonly modelSelection: ModelSelection; readonly nativeThreadId: string; readonly resume: boolean; @@ -903,6 +907,9 @@ export function makeClaudeQueryOptions(input: { ? { pathToClaudeCodeExecutable: input.settings.binaryPath } : {}), ...(input.environment === undefined ? {} : { env: input.environment }), + ...(input.spawnClaudeCodeProcess === undefined + ? {} + : { spawnClaudeCodeProcess: input.spawnClaudeCodeProcess }), ...(input.mcpServers === undefined ? {} : { mcpServers: input.mcpServers }), systemPrompt: { type: "preset" as const, @@ -2925,6 +2932,8 @@ export interface ClaudeAdapterV2Options { readonly path: Path.Path; readonly idAllocator: IdAllocator.IdAllocatorV2Shape; readonly queryRunner: ClaudeAgentSdkQueryRunnerShape; + /** Runs turns whose cwd is in a sandboxed worktree inside its container. */ + readonly sandboxes?: SandboxService.SandboxService["Service"]; readonly scopedLimitNames?: Ref.Ref; readonly onUsageLimits?: ServerProviderShape["applyUsageLimits"]; /** Sink for wake-turn continuation requests; defaults to dropping them. */ @@ -2965,6 +2974,41 @@ export function makeClaudeAdapterV2( Effect.provideService(Path.Path, path), ); + // A sandboxed worktree runs the CLI in its container. On macOS the host + // keeps Claude's login in the Keychain, which a Linux container cannot + // read, so the sandbox needs a token or a credentials file. + const claudeSandboxSpawn = (cwd: string | null) => + Effect.gen(function* () { + if (adapterOptions.sandboxes === undefined || cwd === null) return undefined; + const target = yield* adapterOptions.sandboxes + .execTarget(cwd) + .pipe(Effect.mapError((cause) => queryRunnerError(cause, "sandbox"))); + if (Option.isNone(target)) return undefined; + const env = adapterOptions.environment; + if ( + (yield* HostProcessPlatform) === "darwin" && + !env.CLAUDE_CODE_OAUTH_TOKEN && + !env.ANTHROPIC_API_KEY && + !env.ANTHROPIC_AUTH_TOKEN && + !(yield* fileSystem + .exists( + path.join( + env.CLAUDE_CONFIG_DIR ?? path.join(env.HOME ?? "", ".claude"), + ".credentials.json", + ), + ) + .pipe(Effect.orElseSucceed(() => false))) + ) { + return yield* queryRunnerError( + new Error( + "Claude in a sandbox needs a token on macOS. Run `claude setup-token`, then add CLAUDE_CODE_OAUTH_TOKEN to the Claude provider's environment variables.", + ), + "sandbox", + ); + } + return sandboxClaudeSpawn(target.value); + }); + return ProviderAdapter.ProviderAdapterV2.of({ instanceId: adapterOptions.instanceId, driver: CLAUDE_PROVIDER, @@ -6934,7 +6978,9 @@ export function makeClaudeAdapterV2( const hasPersistedProviderTurn = turnInput.providerTurnOrdinal > 1; const shouldResume = resumeSessionAt !== undefined || openedWithResume || hasPersistedProviderTurn; + const sandbox = yield* claudeSandboxSpawn(turnInput.runtimePolicy.cwd); const queryOptions = makeClaudeQueryOptions({ + ...(sandbox === undefined ? {} : { spawnClaudeCodeProcess: sandbox }), modelSelection: turnInput.modelSelection, nativeThreadId, resume: shouldResume, @@ -7740,6 +7786,7 @@ export const createClaudeAdapterV2 = Effect.fn("ClaudeAdapterV2Driver.create")( const queryRunner = yield* ClaudeAgentSdkQueryRunner; const serverConfig = yield* ServerConfig.ServerConfig; const continuationRequests = yield* ProviderContinuationRequests.ProviderContinuationRequests; + const sandboxes = yield* Effect.serviceOption(SandboxService.SandboxService); const baseEnvironment = mergeProviderInstanceEnvironment(environment, hostEnvironment); const claudeEnvironment = yield* makeClaudeEnvironment(config, baseEnvironment); const path = yield* Path.Path; @@ -7757,6 +7804,7 @@ export const createClaudeAdapterV2 = Effect.fn("ClaudeAdapterV2Driver.create")( idAllocator, queryRunner, continuationRequests, + ...(Option.isSome(sandboxes) ? { sandboxes: sandboxes.value } : {}), ...hooks, }); }, diff --git a/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts b/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts index 19c3486f5af78..4e6ac65a1dc33 100644 --- a/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts +++ b/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts @@ -83,6 +83,7 @@ import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process"; import { resolveAttachmentPath } from "../../attachmentStore.ts"; import { getCodexServiceTierOptionValue } from "../../codexModelOptions.ts"; import { ServerConfig } from "../../config.ts"; +import * as SandboxService from "../../sandbox/SandboxService.ts"; import { expandHomePath } from "../../pathExpansion.ts"; import { buildCodexAdditionalContext, @@ -703,6 +704,12 @@ export function buildCodexTurnStartParams(input: { readonly deviceToolsAvailable?: boolean; /** ChatGPT token sharing does not accept service tiers. */ readonly omitServiceTier?: boolean; + /** + * The turn runs in a Docker sandbox. Codex's own sandbox cannot create + * namespaces inside a container, so the container is the boundary and the + * runtime mode's approval policy still applies. + */ + readonly sandboxed?: boolean; }) { return Effect.gen(function* () { const runtimeModeDefaults = codexRuntimeModeTurnDefaults(input.runtimePolicy.runtimeMode); @@ -711,9 +718,11 @@ export function buildCodexTurnStartParams(input: { ? runtimeModeDefaults.approvalPolicy : yield* decodeTurnApprovalPolicy(input.runtimePolicy.approvalPolicy); const sandboxPolicy = - input.runtimePolicy.sandboxPolicy === undefined - ? runtimeModeDefaults.sandboxPolicy - : yield* decodeTurnSandboxPolicy(input.runtimePolicy.sandboxPolicy); + input.runtimePolicy.sandboxPolicy !== undefined + ? yield* decodeTurnSandboxPolicy(input.runtimePolicy.sandboxPolicy) + : input.sandboxed === true + ? ({ type: "dangerFullAccess" } as const) + : runtimeModeDefaults.sandboxPolicy; const selectedEffort = getModelSelectionStringOptionValue( input.modelSelection, "reasoningEffort", @@ -1385,6 +1394,7 @@ export const codexAppServerClientFactoryFromSettingsLayer: Layer.Layer< Effect.gen(function* () { const spawner = yield* ChildProcessSpawner.ChildProcessSpawner; const { native: nativeEventLogger } = yield* ProviderEventLoggers; + const sandboxes = yield* Effect.serviceOption(SandboxService.SandboxService); return CodexAppServerClientFactory.of({ open: (input) => @@ -1394,13 +1404,47 @@ export const codexAppServerClientFactoryFromSettingsLayer: Layer.Layer< ...input.environment, ...(input.settings.homePath ? { CODEX_HOME: input.settings.homePath } : {}), }; - const command = yield* makeCodexAppServerSpawnCommand({ - command: input.settings.binaryPath || "codex", - args: codexAppServerArgs( - resolveCodexLaunchArgs(input.settings.launchArgs, input.environment), - ), - env: environment, - }); + const args = codexAppServerArgs( + resolveCodexLaunchArgs(input.settings.launchArgs, input.environment), + ); + const openError = (cause: unknown) => + new ProviderAdapterOpenSessionError({ + driver: CODEX_PROVIDER, + providerSessionId: input.providerSessionId, + cause, + }); + const cwd = input.runtimePolicy.cwd; + const sandbox = + Option.isNone(sandboxes) || cwd === null + ? Option.none() + : yield* sandboxes.value.execTarget(cwd).pipe(Effect.mapError(openError)); + // In a sandbox the image's own `codex` runs the app-server; the + // host binary may not even be a Linux build. + const command = Option.isSome(sandbox) + ? yield* Effect.try({ + try: () => + sandbox.value.command({ + command: "codex", + args, + cwd: cwd ?? sandbox.value.worktreePath, + env: environment, + tty: false, + }), + catch: openError, + }).pipe( + Effect.tap((plan) => Scope.addFinalizer(scope, Effect.sync(plan.release))), + Effect.map((plan) => + ChildProcess.make(plan.command, [...plan.args], { + env: plan.env, + extendEnv: false, + }), + ), + ) + : yield* makeCodexAppServerSpawnCommand({ + command: input.settings.binaryPath || "codex", + args, + env: environment, + }); const handle = yield* spawner.spawn(command).pipe( Effect.provideService(Scope.Scope, scope), Effect.mapError( @@ -1452,6 +1496,7 @@ export const createCodexAdapterV2 = ( const hostEnvironment = yield* HostProcessEnvironment; const idAllocator = yield* IdAllocatorV2; const serverConfig = yield* ServerConfig; + const sandboxes = yield* Effect.serviceOption(SandboxService.SandboxService); const homeLayout = yield* resolveCodexHomeLayout(config); yield* materializeCodexShadowHome(homeLayout).pipe( @@ -1482,6 +1527,7 @@ export const createCodexAdapterV2 = ( idAllocator, serverConfig, continuationRequests, + ...(Option.isSome(sandboxes) ? { sandboxes: sandboxes.value } : {}), ...hooks, }); }); @@ -1535,6 +1581,8 @@ export interface CodexAdapterV2Options { readonly fileSystem: FileSystem.FileSystem; readonly idAllocator: IdAllocatorV2Shape; readonly serverConfig: ServerConfig["Service"]; + /** Tells turns whether their cwd is in a sandboxed worktree. */ + readonly sandboxes?: SandboxService.SandboxService["Service"]; /** * Sink for post-settle background command completions so the orchestrator * can start a continuation run. Optional: adapters that omit it keep @@ -5546,6 +5594,10 @@ export function makeCodexAdapterV2(adapterOptions: CodexAdapterV2Options): Provi browserToolsAvailable: mcpSession?.browserToolsAvailable ?? true, deviceToolsAvailable: mcpSession?.capabilities?.has("device") ?? false, omitServiceTier: adapterOptions.resolveRuntime !== undefined, + sandboxed: + adapterOptions.sandboxes !== undefined && + turnInput.runtimePolicy.cwd !== null && + (yield* adapterOptions.sandboxes.isSandboxed(turnInput.runtimePolicy.cwd)), }); yield* Ref.update(pendingRootTurns, (current) => { const updated = new Map(current); diff --git a/apps/server/src/orchestration-v2/IdAllocator.ts b/apps/server/src/orchestration-v2/IdAllocator.ts index f619e45095c09..d19f760c9c72a 100644 --- a/apps/server/src/orchestration-v2/IdAllocator.ts +++ b/apps/server/src/orchestration-v2/IdAllocator.ts @@ -127,8 +127,13 @@ export interface IdAllocatorV2AllocateShape { } export interface IdAllocatorV2DeriveShape { + /** + * The shared session for adapters that serve many threads from one process. + * A sandboxed worktree gets its own, because its process runs in the container. + */ readonly providerSession: (input: { readonly providerInstanceId: ProviderInstanceId; + readonly sandboxWorktreePath?: string; }) => ProviderSessionId; readonly delegatedTaskNode: (input: { readonly commandId: CommandId }) => NodeId; readonly delegatedTaskThread: (input: { readonly commandId: CommandId }) => ThreadId; @@ -389,7 +394,16 @@ export const layer: Layer.Layer = Layer.succeed( derive: { providerSession: (input) => ProviderSessionId.make( - joinId("provider-session", "provider-instance", input.providerInstanceId, "shared"), + input.sandboxWorktreePath === undefined + ? joinId("provider-session", "provider-instance", input.providerInstanceId, "shared") + : joinId( + "provider-session", + "provider-instance", + input.providerInstanceId, + "shared", + "sandbox", + input.sandboxWorktreePath, + ), ), delegatedTaskNode: (input) => NodeId.make(joinId("node", "delegated-task", input.commandId)), delegatedTaskThread: (input) => diff --git a/apps/server/src/orchestration-v2/Orchestrator.ts b/apps/server/src/orchestration-v2/Orchestrator.ts index 2707fe5b83441..77c4730495d7c 100644 --- a/apps/server/src/orchestration-v2/Orchestrator.ts +++ b/apps/server/src/orchestration-v2/Orchestrator.ts @@ -103,6 +103,7 @@ import { ProviderSessionManagerV2 } from "./ProviderSessionManager.ts"; import { ProviderSwitchServiceV2 } from "./ProviderSwitchService.ts"; import { isAutomaticCompletionRun, queuedRunsInDeliveryOrder } from "./QueuedRunOrder.ts"; import { RuntimePolicyV2 } from "./RuntimePolicy.ts"; +import * as SandboxService from "../sandbox/SandboxService.ts"; import { makeSubagentChildThread, subagentResultForRun, @@ -741,6 +742,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio const providerSessions = yield* ProviderSessionManagerV2; const providerSwitchService = yield* ProviderSwitchServiceV2; const runtimePolicy = yield* RuntimePolicyV2; + const sandboxes = yield* Effect.serviceOption(SandboxService.SandboxService); const threadForkService = yield* ThreadForkServiceV2; const threadDispatch = yield* ThreadCommandExecutor; @@ -770,23 +772,53 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio ), ); + /** + * The shared session id for adapters that serve many threads from one + * process, or null for adapters with a session per thread. A shared process + * runs where it was opened, so threads in a sandbox never share one with + * the host or another sandbox. + */ + const sharedProviderSessionIdFor = (input: { + readonly adapter: ProviderAdapterV2Shape; + readonly providerInstanceId: ProviderInstanceId; + readonly worktreePath: string | null; + }) => + Effect.gen(function* () { + const capabilities = yield* input.adapter.getCapabilities(); + if (!capabilities.sessions.supportsMultipleProviderThreadsPerSession) return null; + const worktreePath = input.worktreePath; + const sandboxed = + worktreePath !== null && + Option.isSome(sandboxes) && + (yield* sandboxes.value.isSandboxed(worktreePath)); + return idAllocator.derive.providerSession({ + providerInstanceId: input.providerInstanceId, + ...(sandboxed ? { sandboxWorktreePath: worktreePath } : {}), + }); + }); + + /** + * The session a run uses. A shared session always comes from the thread's + * current worktree rather than `persisted`: a launch records one before its + * worktree and sandbox exist. For host threads that is the same id. + */ const providerSessionIdFor = (input: { readonly adapter: ProviderAdapterV2Shape; readonly providerInstanceId: ProviderInstanceId; readonly threadId: ThreadId; + readonly worktreePath: string | null; + readonly persisted: ProviderSessionId | null | undefined; }) => - input.adapter.getCapabilities().pipe( - Effect.flatMap((capabilities) => - capabilities.sessions.supportsMultipleProviderThreadsPerSession - ? Effect.succeed( - idAllocator.derive.providerSession({ + sharedProviderSessionIdFor(input).pipe( + Effect.flatMap((shared) => + shared !== null + ? Effect.succeed(shared) + : input.persisted !== null && input.persisted !== undefined + ? Effect.succeed(input.persisted) + : idAllocator.allocate.providerSession({ providerInstanceId: input.providerInstanceId, + threadId: input.threadId, }), - ) - : idAllocator.allocate.providerSession({ - providerInstanceId: input.providerInstanceId, - threadId: input.threadId, - }), ), ); @@ -1483,29 +1515,32 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio }), ), )); - const providerSessionId = - (!canResumeAcrossInstances && - queuedProviderThread.providerSessionId !== null && - !switchPlan?.releaseProviderSessionIds.includes(queuedProviderThread.providerSessionId) - ? queuedProviderThread.providerSessionId - : null) ?? - (yield* providerAdapters.get(queuedRun.providerInstanceId).pipe( - Effect.flatMap((adapter) => - providerSessionIdFor({ - adapter, - providerInstanceId: queuedRun.providerInstanceId, - threadId, + const providerSessionId = yield* providerAdapters.get(queuedRun.providerInstanceId).pipe( + Effect.flatMap((adapter) => + providerSessionIdFor({ + adapter, + providerInstanceId: queuedRun.providerInstanceId, + threadId, + worktreePath: projection.thread.worktreePath, + persisted: + !canResumeAcrossInstances && + queuedProviderThread.providerSessionId !== null && + !switchPlan?.releaseProviderSessionIds.includes( + queuedProviderThread.providerSessionId, + ) + ? queuedProviderThread.providerSessionId + : null, + }), + ), + Effect.mapError( + (cause) => + new OrchestratorDispatchError({ + commandId, + commandType: "message.dispatch", + cause, }), - ), - Effect.mapError( - (cause) => - new OrchestratorDispatchError({ - commandId, - commandType: "message.dispatch", - cause, - }), - ), - )); + ), + ); const providerThread: OrchestrationV2ProviderThread = { ...deliveryProviderThread, providerSessionId, @@ -3945,15 +3980,15 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio input.projection, input.modelSelection.instanceId, ).find((candidate) => candidate.id !== providerThread.id); - const targetProviderSessionId = - existingTargetProviderThread?.providerSessionId ?? - (yield* mapDispatchError(input.command)( - providerSessionIdFor({ - adapter: targetAdapter, - providerInstanceId: input.modelSelection.instanceId, - threadId: input.command.threadId, - }), - )); + const targetProviderSessionId = yield* mapDispatchError(input.command)( + providerSessionIdFor({ + adapter: targetAdapter, + providerInstanceId: input.modelSelection.instanceId, + threadId: input.command.threadId, + worktreePath: input.projection.thread.worktreePath, + persisted: existingTargetProviderThread?.providerSessionId, + }), + ); const targetProviderThreadBase: OrchestrationV2ProviderThread = existingTargetProviderThread === undefined ? { @@ -5024,15 +5059,15 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio }), ), ); - const providerSessionId = - activeProviderThread?.providerSessionId ?? - (yield* mapDispatchError(command)( - providerSessionIdFor({ - adapter, - providerInstanceId: modelSelection.instanceId, - threadId: command.threadId, - }), - )); + const providerSessionId = yield* mapDispatchError(command)( + providerSessionIdFor({ + adapter, + providerInstanceId: modelSelection.instanceId, + threadId: command.threadId, + worktreePath: projection.thread.worktreePath, + persisted: activeProviderThread?.providerSessionId, + }), + ); const providerThreadId = activeProviderThread?.id ?? idAllocator.derive.providerThread({ @@ -5409,15 +5444,15 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio isProviderSwitch && !canResumeAcrossInstances ? rootProviderThreadsForProvider(projection, modelSelection.instanceId)[0] : activeProviderThread; - const providerSessionId = - (canResumeAcrossInstances ? undefined : targetProviderThread?.providerSessionId) ?? - (yield* mapDispatchError(command)( - providerSessionIdFor({ - adapter, - providerInstanceId: modelSelection.instanceId, - threadId: command.threadId, - }), - )); + const providerSessionId = yield* mapDispatchError(command)( + providerSessionIdFor({ + adapter, + providerInstanceId: modelSelection.instanceId, + threadId: command.threadId, + worktreePath: projection.thread.worktreePath, + persisted: canResumeAcrossInstances ? undefined : targetProviderThread?.providerSessionId, + }), + ); const existingProviderSession = projection.providerSessions.find( (candidate) => candidate.id === providerSessionId, ); @@ -7576,6 +7611,33 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio }) .pipe(mapDispatchError(command)); const emitEvent = emit(events, command); + // The run's session was picked when the message arrived, before the + // worktree (and any sandbox) existed. Re-pick a shared one now. + const preparedAdapter = yield* providerAdapters + .get(state.run.providerInstanceId) + .pipe(mapDispatchError(command)); + const preparedSessionId = yield* sharedProviderSessionIdFor({ + adapter: preparedAdapter, + providerInstanceId: state.run.providerInstanceId, + worktreePath: projection.thread.worktreePath, + }).pipe(mapDispatchError(command)); + if ( + preparedSessionId !== null && + preparedSessionId !== state.providerThread.providerSessionId + ) { + yield* emitEvent({ + type: "provider-thread.updated", + threadId: command.threadId, + driver: state.providerThread.driver, + providerInstanceId: state.run.providerInstanceId, + occurredAt: now, + payload: { + ...state.providerThread, + providerSessionId: preparedSessionId, + updatedAt: now, + }, + }); + } yield* emitEvent({ type: "checkpoint-scope.created", threadId: command.threadId, diff --git a/apps/server/src/orchestration-v2/ProviderSessionManager.ts b/apps/server/src/orchestration-v2/ProviderSessionManager.ts index c1039c2a0207d..f0e85ccf37139 100644 --- a/apps/server/src/orchestration-v2/ProviderSessionManager.ts +++ b/apps/server/src/orchestration-v2/ProviderSessionManager.ts @@ -34,6 +34,7 @@ import * as ProjectService from "../project/ProjectService.ts"; import * as McpProviderSession from "../mcp/McpProviderSession.ts"; import * as ServerSettings from "../serverSettings.ts"; import * as McpSessionRegistry from "../mcp/McpSessionRegistry.ts"; +import * as SandboxService from "../sandbox/SandboxService.ts"; import * as EventSink from "./EventSink.ts"; import * as IdAllocator from "./IdAllocator.ts"; import { makeKeyedSerialExecutor } from "./KeyedSerialExecutor.ts"; @@ -70,6 +71,9 @@ export type ProviderSessionReleaseReason = typeof ProviderSessionReleaseReason.T * terminalizes provider-bound work and retires non-replayable effects; a later * user command or durable replay-safe operation opens a session lazily. */ +/** Provider drivers that run inside a worktree's Docker sandbox. */ +const SANDBOX_DRIVERS: ReadonlySet = new Set(["codex", "claudeAgent"]); + export class ProviderSessionOpenError extends Schema.TaggedError()( "ProviderSessionOpenError", { @@ -198,6 +202,8 @@ interface LiveSessionEntry { */ readonly mcpCredentialIdByThread: ReadonlyMap; readonly supportsMultipleProviderThreads: boolean; + /** Where the session's process runs. A sandboxed worktree's sessions die with its container. */ + readonly cwd: string | null; readonly runtime: ProviderAdapterV2SessionRuntime; readonly exposedRuntime: ProviderAdapterV2SessionRuntime; readonly eventSubscribers: Ref.Ref< @@ -308,6 +314,20 @@ export const layerWithOptions = ( Effect.gen(function* () { const registry = yield* ProviderAdapterRegistry.ProviderAdapterRegistryV2; const fileSystem = yield* FileSystem.FileSystem; + const sandboxes = yield* Effect.serviceOption(SandboxService.SandboxService); + // How often each sandboxed worktree stopped. An open that sees the count + // change holds a client whose process died with the container. + const sandboxStops = new Map(); + const isInside = (worktreePath: string, cwd: string) => + cwd === worktreePath || cwd.startsWith(`${worktreePath}/`); + const stopCount = (cwd: string | null) => { + if (cwd === null) return 0; + let count = 0; + for (const [worktreePath, stops] of sandboxStops) { + if (isInside(worktreePath, cwd)) count += stops; + } + return count; + }; const mcpSessionRegistry = yield* McpSessionRegistry.McpSessionRegistry; /** * Optional so the many focused tests that assemble this layer by hand do @@ -801,11 +821,19 @@ export const layerWithOptions = ( const removeLiveEntry = (input: { readonly providerSessionId: ProviderSessionId; readonly onlyIfIdleGeneration?: number; + /** + * Release only the session this entry holds, never a replacement that + * took its id. Compared by runtime: activity updates replace the entry. + */ + readonly onlyIfEntry?: LiveSessionEntry; }): Effect.Effect, DateTime.Utc]> => Effect.gen(function* () { const key = sessionKey(input.providerSessionId); const candidate = (yield* Ref.get(sessions)).get(key); - if (candidate === undefined) { + if ( + candidate === undefined || + (input.onlyIfEntry !== undefined && candidate.runtime !== input.onlyIfEntry.runtime) + ) { return [Option.none(), yield* DateTime.now] as const; } const removed = yield* Effect.zip( @@ -841,6 +869,7 @@ export const layerWithOptions = ( readonly detail?: string; readonly cancelIdleFiber?: boolean; readonly onlyIfIdleGeneration?: number; + readonly onlyIfEntry?: LiveSessionEntry; readonly gracefulSubscribers?: boolean; }) => Effect.acquireUseRelease( @@ -1660,6 +1689,34 @@ export const layerWithOptions = ( }); yield* Effect.addFinalizer(() => shutdown); + // A stopped or removed sandbox took its sessions' processes with it. + // Release them so the next turn opens a fresh session, restarting the + // sandbox, instead of reusing a dead client. + if (Option.isSome(sandboxes)) { + yield* sandboxes.value.stopped.pipe( + Stream.runForEach((worktreePath) => + Effect.gen(function* () { + sandboxStops.set(worktreePath, (sandboxStops.get(worktreePath) ?? 0) + 1); + const dead = [...(yield* Ref.get(sessions)).values()].filter( + (entry) => entry.cwd !== null && isInside(worktreePath, entry.cwd), + ); + yield* Effect.forEach( + dead, + (entry) => + releaseEntry({ + providerSessionId: entry.runtime.providerSessionId, + reason: "runtime_error", + detail: "The sandbox stopped.", + onlyIfEntry: entry, + }).pipe(Effect.ignore), + { discard: true }, + ); + }), + ), + Effect.forkScoped, + ); + } + return ProviderSessionManagerV2.of({ shutdown, open: (input) => @@ -1681,6 +1738,36 @@ export const layerWithOptions = ( } const key = sessionKey(input.providerSessionId); const existing = (yield* Ref.get(sessions)).get(key); + // Only these adapters start their CLI through the sandbox. Any + // other provider would run on the host, outside the sandbox the + // user chose, so it fails instead, also when it would reuse a + // session that is already open. + if ( + cwd !== null && + Option.isSome(sandboxes) && + (yield* sandboxes.value.isSandboxed(cwd)) + ) { + const driver = + existing?.runtime.driver ?? + (yield* registry.get(input.modelSelection.instanceId).pipe( + Effect.map((adapter) => adapter.driver), + Effect.mapError( + (cause) => + new ProviderSessionOpenError({ + instanceId: input.modelSelection.instanceId, + providerSessionId: input.providerSessionId, + cause, + }), + ), + )); + if (!SANDBOX_DRIVERS.has(driver)) { + return yield* new ProviderSessionOpenError({ + instanceId: input.modelSelection.instanceId, + providerSessionId: input.providerSessionId, + cause: `${driver} cannot run in a sandbox yet. Use Claude or Codex in this thread.`, + }); + } + } if (existing !== undefined) { if ( !existing.attachedThreadIds.has(input.threadId) && @@ -1727,6 +1814,7 @@ export const layerWithOptions = ( dropMcpCredentialReservation(input.threadId, mcpCredentialId); } }); + const stopsAtOpen = stopCount(cwd); const sessionScope = yield* Scope.make(); const runtime = yield* adapter .openSession({ @@ -1788,6 +1876,7 @@ export const layerWithOptions = ( supportsMultipleProviderThreads: runtime.providerSession.capabilities.sessions .supportsMultipleProviderThreadsPerSession, + cwd, runtime, exposedRuntime, eventSubscribers, @@ -1807,6 +1896,20 @@ export const layerWithOptions = ( // The entry now guards the credential via its recorded id, so // the pre-open reservation can be dropped. yield* dropReservation; + if (stopCount(cwd) !== stopsAtOpen) { + yield* releaseEntry({ + providerSessionId: input.providerSessionId, + reason: "runtime_error", + detail: "The sandbox stopped while the session was opening.", + onlyIfEntry: entry, + }).pipe(logReleaseFailure(input.providerSessionId)); + return yield* new ProviderSessionOpenError({ + instanceId: input.modelSelection.instanceId, + providerSessionId: input.providerSessionId, + cause: + "The sandbox stopped while the session was opening. Send the message again.", + }); + } yield* withActivityError( input.providerSessionId, writeProviderSessionEvents({ diff --git a/apps/server/src/orchestration-v2/ThreadLaunchService.ts b/apps/server/src/orchestration-v2/ThreadLaunchService.ts index faf6133769208..8c3a4a025423d 100644 --- a/apps/server/src/orchestration-v2/ThreadLaunchService.ts +++ b/apps/server/src/orchestration-v2/ThreadLaunchService.ts @@ -35,6 +35,7 @@ import * as ProjectService from "../project/ProjectService.ts"; import * as ProjectSetupScriptRunner from "../project/ProjectSetupScriptRunner.ts"; import * as ManagedProjectFolders from "../project/ManagedProjectFolders.ts"; import * as ProviderRegistry from "../provider/Services/ProviderRegistry.ts"; +import * as SandboxService from "../sandbox/SandboxService.ts"; import * as ServerSettings from "../serverSettings.ts"; import * as TextGeneration from "../textGeneration/TextGeneration.ts"; import * as CommandReceiptStore from "./CommandReceiptStore.ts"; @@ -55,6 +56,7 @@ export type ThreadLaunchWorkspaceStrategy = readonly baseRef: string; readonly branch?: string | undefined; readonly startFromOrigin?: boolean | undefined; + readonly sandbox?: boolean | undefined; }; export interface ThreadLaunchInitialMessage { @@ -104,6 +106,7 @@ export class ThreadLaunchError extends Schema.TaggedError()( "read-receipt", "generate-metadata", "provision-worktree", + "provision-sandbox", "run-setup-script", "create-thread", "update-thread", @@ -156,6 +159,7 @@ const make = Effect.gen(function* () { const ids = yield* IdAllocator.IdAllocatorV2; const threads = yield* ThreadManagement.ThreadManagementService; const managedFolders = yield* ManagedProjectFolders.ManagedProjectFolders; + const sandboxes = yield* Effect.serviceOption(SandboxService.SandboxService); const preparationScope = yield* Scope.make("sequential"); const scheduledLaunches = yield* Ref.make>(new Set()); yield* Effect.addFinalizer(() => Scope.close(preparationScope, Exit.void)); @@ -217,6 +221,7 @@ const make = Effect.gen(function* () { ); const tracked = input.workspaceStrategy.type === "worktree"; + const sandboxed = tracked && input.workspaceStrategy.sandbox === true; let createdWorktreePath: string | null = null; let setupTerminalId: string | null = null; if (tracked) { @@ -224,7 +229,9 @@ const make = Effect.gen(function* () { threadId, branch: input.workspaceStrategy.branch ?? null, baseRef: input.workspaceStrategy.baseRef, - stages: ["fetch", "checkout", "setup-script", "agent"], + stages: sandboxed + ? ["fetch", "checkout", "sandbox", "setup-script", "agent"] + : ["fetch", "checkout", "setup-script", "agent"], fiber: yield* Effect.fiber, }); } @@ -354,6 +361,25 @@ const make = Effect.gen(function* () { worktreePath = worktree.worktree.path; branch = worktree.worktree.refName; createdWorktreePath = worktreePath; + // Registered before the thread shows its worktree, so nothing opened + // there can start on the host while the sandbox is still starting. + if (sandboxed) { + if (Option.isNone(sandboxes)) { + return yield* mapError( + input, + "provision-sandbox", + threadId, + )("This server cannot run sandboxes."); + } + yield* sandboxes.value + .register({ + worktreePath, + projectRoot: project.workspaceRoot, + providers: yield* providerRegistry.getProviders, + homes: SandboxService.sandboxProviderHomes(yield* serverSettings.getSettings), + }) + .pipe(Effect.mapError(mapError(input, "provision-sandbox", threadId))); + } yield* setupTracker.update(threadId, (snapshot) => ({ ...snapshot, worktreePath, branch })); yield* setupTracker.stageStatus(threadId, "checkout", "done"); } @@ -410,6 +436,19 @@ const make = Effect.gen(function* () { ); } + // The sandbox starts before the setup script so the script installs + // dependencies and services inside it. + if (sandboxed && worktreePath !== null && Option.isSome(sandboxes)) { + yield* setupTracker.stageStatus(threadId, "sandbox", "running"); + yield* sandboxes.value + .start({ + worktreePath, + onOutput: (line) => setupTracker.appendTail(threadId, "sandbox", line), + }) + .pipe(Effect.mapError(mapError(input, "provision-sandbox", threadId))); + yield* setupTracker.stageStatus(threadId, "sandbox", "done"); + } + const cwd = worktreePath ?? project.workspaceRoot; if (runId !== null) { yield* threads diff --git a/apps/server/src/preview/PortScanner.ts b/apps/server/src/preview/PortScanner.ts index 9eee1a3e215ee..0523b20210991 100644 --- a/apps/server/src/preview/PortScanner.ts +++ b/apps/server/src/preview/PortScanner.ts @@ -39,6 +39,7 @@ import * as Semaphore from "effect/Semaphore"; import { FetchHttpClient, HttpClient } from "effect/unstable/http"; import * as ProcessRunner from "../processRunner.ts"; +import * as SandboxService from "../sandbox/SandboxService.ts"; export class PortDiscovery extends Context.Service< PortDiscovery, @@ -295,6 +296,7 @@ export const make = Effect.gen(function* PortDiscoveryMake() { const processRunner = yield* ProcessRunner.ProcessRunner; const hostPlatform = yield* HostProcessPlatform; const httpClient = (yield* HttpClient.HttpClient).pipe(HttpClient.withScope); + const sandboxes = yield* Effect.serviceOption(SandboxService.SandboxService); const stateRef = yield* Ref.make({ listeners: new Map(), terminalProcesses: new Map(), @@ -390,10 +392,46 @@ export const make = Effect.gen(function* PortDiscoveryMake() { return groups; }; - const probeWebServers = Effect.fn("PortDiscovery.probeWebServers")(function* ( + /** + * Sandbox apps listen inside their container; the server forwards each port + * to a host loopback port. Those listeners belong to the server process, so + * they are labeled with the container port, and added when no listener + * probe (lsof) found them. + */ + const withSandboxPorts = ( servers: ReadonlyArray, + ): ReadonlyArray => { + if (Option.isNone(sandboxes)) return servers; + const forwarded = new Map( + sandboxes.value.forwardedPorts().map((port) => [port.hostPort, port] as const), + ); + if (forwarded.size === 0) return servers; + const label = (containerPort: number) => `sandbox :${containerPort}`; + const labeled = servers.map((server) => { + const port = forwarded.get(server.port); + return port === undefined ? server : { ...server, processName: label(port.containerPort) }; + }); + const found = new Set(labeled.map((server) => server.port)); + return [ + ...labeled, + ...[...forwarded.values()] + .filter((port) => !found.has(port.hostPort)) + .map((port) => ({ + host: "127.0.0.1", + port: port.hostPort, + url: `http://127.0.0.1:${port.hostPort}`, + processName: label(port.containerPort), + pid: null, + terminal: null, + })), + ]; + }; + + const probeWebServers = Effect.fn("PortDiscovery.probeWebServers")(function* ( + listeners: ReadonlyArray, configuredUrls: ReadonlyArray, ) { + const servers = withSandboxPorts(listeners); const nowMillis = yield* Clock.currentTimeMillis; const cached = yield* Ref.get(webProbeCacheRef); const groups = makeWebProbeGroups(servers, configuredUrls); diff --git a/apps/server/src/processRunner.ts b/apps/server/src/processRunner.ts index 049125de3fbfd..c1e1c52c67f72 100644 --- a/apps/server/src/processRunner.ts +++ b/apps/server/src/processRunner.ts @@ -27,6 +27,8 @@ export interface ProcessRunInput { readonly stdin?: string | undefined; /** Receives every stdout chunk, including bytes beyond the buffered output limit. */ readonly onStdoutChunk?: ((chunk: Uint8Array) => void) | undefined; + /** Receives every stderr chunk, including bytes beyond the buffered output limit. */ + readonly onStderrChunk?: ((chunk: Uint8Array) => void) | undefined; readonly maxOutputBytes?: number | undefined; readonly outputMode?: "error" | "truncate" | undefined; readonly truncatedMarker?: string | undefined; @@ -335,6 +337,7 @@ const runProcessCore = Effect.fn("processRunner.runProcessCore")(function* ( const stdin = input.stdin; const onStdoutChunk = input.onStdoutChunk; + const onStderrChunk = input.onStderrChunk; const writeStdin = stdin === undefined ? Effect.void @@ -373,7 +376,9 @@ const runProcessCore = Effect.fn("processRunner.runProcessCore")(function* ( cwd: input.cwd, spawnCwd: input.spawnCwd, streamName: "stderr", - stream: child.stderr, + stream: onStderrChunk + ? child.stderr.pipe(Stream.tap((chunk) => Effect.sync(() => onStderrChunk(chunk)))) + : child.stderr, maxOutputBytes, outputMode, truncatedMarker, diff --git a/apps/server/src/project/ProjectSetupScriptRunner.ts b/apps/server/src/project/ProjectSetupScriptRunner.ts index f97c0f4df9c0a..7f55aba694afa 100644 --- a/apps/server/src/project/ProjectSetupScriptRunner.ts +++ b/apps/server/src/project/ProjectSetupScriptRunner.ts @@ -17,6 +17,7 @@ import * as Schema from "effect/Schema"; import * as ServerSettings from "../serverSettings.ts"; import * as TerminalManager from "../terminal/Manager.ts"; +import * as SandboxService from "../sandbox/SandboxService.ts"; import * as ProjectService from "./ProjectService.ts"; export interface ProjectSetupScriptRunnerResultNoScript { @@ -205,6 +206,7 @@ export const make = Effect.gen(function* () { yield* HostProcessPlatform, yield* HostProcessEnvironment, ); + const sandboxes = yield* Effect.serviceOption(SandboxService.SandboxService); /** * Watches the setup terminal for the completion sentinel. Terminal output is @@ -372,7 +374,10 @@ export const make = Effect.gen(function* () { observe && completionToken ? wrapCommandForCompletion( script.command, - completionShell, + // A sandbox terminal is bash in the container, whatever the host shell is. + Option.isSome(sandboxes) && (yield* sandboxes.value.isSandboxed(cwd)) + ? "posix" + : completionShell, completionSentinel(completionToken), ) : script.command; diff --git a/apps/server/src/sandbox/SandboxService.test.ts b/apps/server/src/sandbox/SandboxService.test.ts new file mode 100644 index 0000000000000..f4625acf5b760 --- /dev/null +++ b/apps/server/src/sandbox/SandboxService.test.ts @@ -0,0 +1,42 @@ +import { + DEFAULT_SERVER_SETTINGS, + ProviderDriverKind, + ProviderInstanceId, +} from "@t3tools/contracts"; +import { describe, expect, it } from "vite-plus/test"; + +import { sandboxProviderHomes } from "./SandboxService.ts"; + +describe("sandboxProviderHomes", () => { + it("collects Claude and Codex homes from providers, instances, and their env", () => { + const homes = sandboxProviderHomes({ + ...DEFAULT_SERVER_SETTINGS, + providers: { + ...DEFAULT_SERVER_SETTINGS.providers, + codex: { ...DEFAULT_SERVER_SETTINGS.providers.codex, homePath: "/homes/codex" }, + }, + providerInstances: { + [ProviderInstanceId.make("codex-work")]: { + driver: ProviderDriverKind.make("codex"), + config: { homePath: "/homes/codex-work", shadowHomePath: "/homes/codex-work-shadow" }, + }, + [ProviderInstanceId.make("claude-work")]: { + driver: ProviderDriverKind.make("claudeAgent"), + environment: [ + { name: "CLAUDE_CONFIG_DIR", value: "/homes/claude-work", sensitive: false }, + ], + }, + [ProviderInstanceId.make("other")]: { + driver: ProviderDriverKind.make("opencode"), + config: { homePath: "/homes/opencode" }, + }, + }, + }); + expect(homes).toEqual([ + "/homes/codex", + "/homes/codex-work", + "/homes/codex-work-shadow", + "/homes/claude-work", + ]); + }); +}); diff --git a/apps/server/src/sandbox/SandboxService.ts b/apps/server/src/sandbox/SandboxService.ts new file mode 100644 index 0000000000000..e996d5b89a435 --- /dev/null +++ b/apps/server/src/sandbox/SandboxService.ts @@ -0,0 +1,1040 @@ +// @effect-diagnostics nodeBuiltinImport:off - spawns the Docker CLI for long-lived relays and sync exec plans. +import * as NodeChildProcess from "node:child_process"; +import * as NodeCrypto from "node:crypto"; +import * as NodeOS from "node:os"; + +import type { + SandboxListStreamEvent, + SandboxStatus, + SandboxSummary, + ServerProvider, + ServerSettings, +} from "@t3tools/contracts"; +import { HostProcessPlatform } from "@t3tools/shared/hostProcess"; +import * as Context from "effect/Context"; +import * as Deferred from "effect/Deferred"; +import * as Effect from "effect/Effect"; +import * as FileSystem from "effect/FileSystem"; +import * as Layer from "effect/Layer"; +import * as Option from "effect/Option"; +import * as Path from "effect/Path"; +import * as PubSub from "effect/PubSub"; +import * as Queue from "effect/Queue"; +import * as Schema from "effect/Schema"; +import * as Semaphore from "effect/Semaphore"; +import * as Stream from "effect/Stream"; +import { HttpServer } from "effect/unstable/http"; +import * as NetAddress from "effect/unstable/net/NetAddress"; + +import { writeFileStringAtomically } from "../atomicWrite.ts"; +import * as ServerConfig from "../config.ts"; +import { expandHomePath } from "../pathExpansion.ts"; +import * as ProcessRunner from "../processRunner.ts"; +import { + dockerExecArgs, + dockerRunArgs, + isMountablePath, + preferredSandboxHostPort, + SANDBOX_DOCKERFILE, + SANDBOX_LABELS, + type SandboxCliVersions, + type SandboxMount, + sandboxContainerName, + sandboxEnvNames, + sandboxImageBuildArgs, + sandboxImageTag, + sandboxOwner, +} from "./sandboxDocker.ts"; +import { SANDBOX_KILL_SOURCE, SANDBOX_RELAY_SOURCE, SandboxTunnel } from "./SandboxTunnel.ts"; + +export class SandboxError extends Schema.TaggedError()("SandboxError", { + operation: Schema.Literals(["create", "start", "exec", "stop", "remove"]), + worktreePath: Schema.String, + detail: Schema.String, + cause: Schema.optional(Schema.Defect()), +}) { + override get message(): string { + return this.detail; + } +} + +/** Runs commands inside one sandbox. Plain functions, so sync spawn callbacks can use it. */ +export interface SandboxExecTarget { + readonly worktreePath: string; + readonly containerName: string; + /** + * Docker client command that runs `command` inside the sandbox. The caller + * spawns it and calls `release` when it exits or is killed: killing the + * Docker client alone leaves the command running in the container. + * Throws `SandboxError` when the env needs a folder the sandbox cannot see. + */ + readonly command: (input: { + readonly command: string; + readonly args: ReadonlyArray; + readonly cwd: string; + readonly env: NodeJS.ProcessEnv; + readonly tty: boolean; + }) => SandboxCommand; +} + +export interface SandboxCommand { + readonly command: string; + readonly args: ReadonlyArray; + /** Env for the Docker client. It holds the values `-e NAME` copies in. */ + readonly env: NodeJS.ProcessEnv; + /** Kills the command's processes in the container. Safe to call more than once. */ + readonly release: () => void; +} + +export interface SandboxForwardedPort { + readonly worktreePath: string; + readonly containerPort: number; + readonly hostPort: number; +} + +/** + * Docker sandboxes for worktrees. A sandbox is one long-running container + * that mounts its worktree (and the repository's git dir) at the same path, + * plus the user's Claude and Codex config folders. Agents, terminals, and + * setup scripts whose cwd is inside a sandboxed worktree run in it through + * `docker exec`, so parallel threads get separate ports, services, and + * machine state while T3 keeps reading the worktree on the host. + * + * A worktree is registered as sandboxed before anything slow happens, and + * stays registered when provisioning fails, so work there fails instead of + * running on the host. The list is persisted, and containers carry labels + * that rebuild it if the file is lost. + */ +export class SandboxService extends Context.Service< + SandboxService, + { + /** Whether this host can run sandboxes at all: Linux and macOS with Docker. */ + readonly supported: boolean; + /** + * Marks a new worktree as sandboxed and saves it. Fast; call it before + * anything can run in the worktree, then `start`. `providers` supplies + * the Claude and Codex versions to install; their home folders, plus + * `homes` (see `sandboxProviderHomes`), are mounted. + */ + readonly register: (input: { + readonly worktreePath: string; + /** The project checkout, mounted read-only for setup scripts that copy or link from it. */ + readonly projectRoot: string; + readonly providers: ReadonlyArray; + readonly homes: ReadonlyArray; + }) => Effect.Effect; + /** Builds the image if needed, then creates and starts a registered sandbox. */ + readonly start: (input: { + readonly worktreePath: string; + readonly onOutput?: (line: string) => Effect.Effect; + }) => Effect.Effect; + /** The started sandbox that owns `cwd`, or none when `cwd` is not sandboxed. */ + readonly execTarget: ( + cwd: string, + ) => Effect.Effect, SandboxError>; + /** Whether `cwd` is inside a sandboxed worktree. Does not start anything. */ + readonly isSandboxed: (cwd: string) => Effect.Effect; + /** Stops the container. The next command in the worktree starts it again. */ + readonly stop: (worktreePath: string) => Effect.Effect; + /** Deletes the container. Work in the worktree runs on the host afterwards. */ + readonly remove: (worktreePath: string) => Effect.Effect; + readonly list: Effect.Effect>; + /** Emits the full list first, then after every change. */ + readonly stream: Stream.Stream; + /** Every forwarded sandbox port, for preview discovery. */ + readonly forwardedPorts: () => ReadonlyArray; + /** + * Worktrees whose container stopped, was removed, or lost its relay. The + * processes T3 ran there are gone, so sessions holding them are dead. + */ + readonly stopped: Stream.Stream; + } +>()("t3/sandbox/SandboxService") {} + +const Mount = Schema.Struct({ path: Schema.String, readOnly: Schema.Boolean }); + +const RegistryEntry = Schema.Struct({ + worktreePath: Schema.String, + containerName: Schema.String, + image: Schema.String, + versions: Schema.Struct({ claude: Schema.String, codex: Schema.String }), + mounts: Schema.Array(Mount), +}); +const RegistryFile = Schema.Struct({ + version: Schema.Literal(1), + /** Saved while an unreadable list has not been rebuilt from Docker yet. */ + unverified: Schema.optional(Schema.Boolean), + sandboxes: Schema.Array(RegistryEntry), +}); +const RegistryJson = Schema.fromJsonString(RegistryFile); +const decodeRegistry = Schema.decodeUnknownEffect(RegistryJson); +const encodeRegistry = Schema.encodeEffect(RegistryJson); +const MarkerJson = Schema.fromJsonString(RegistryEntry); +const decodeMarker = Schema.decodeUnknownEffect(MarkerJson); +const encodeMarker = Schema.encodeEffect(MarkerJson); +/** Kept in the worktree's own git admin folder, which `git worktree remove` deletes. */ +const MARKER_FILE = "t3code-sandbox.json"; + +/** The parts of `docker inspect` output used to adopt a labeled container. */ +const InspectedContainers = Schema.fromJsonString( + Schema.Array( + Schema.Struct({ + Name: Schema.String, + Config: Schema.Struct({ + Image: Schema.String, + Labels: Schema.NullOr(Schema.Record(Schema.String, Schema.String)), + }), + State: Schema.Struct({ Running: Schema.Boolean }), + Mounts: Schema.NullOr( + Schema.Array( + Schema.Struct({ Source: Schema.String, Destination: Schema.String, RW: Schema.Boolean }), + ), + ), + }), + ), +); +const decodeInspected = Schema.decodeUnknownEffect(InspectedContainers); + +interface SandboxRecord { + readonly worktreePath: string; + readonly containerName: string; + readonly versions: SandboxCliVersions; + readonly mounts: ReadonlyArray; + /** Empty until the first image build finishes. */ + image: string; + status: SandboxStatus; + error: string | null; + tunnel: SandboxTunnel | null; + /** Commands left running by an earlier server process were killed. */ + reaped: boolean; + readonly lock: Semaphore.Semaphore; +} + +const DOCKER = "docker"; +const SUPPORTED_PLATFORMS: ReadonlySet = new Set(["linux", "darwin"]); +const SANDBOX_DRIVERS = { claude: "claudeAgent", codex: "codex" } as const; + +const containsPath = (root: string, candidate: string, separator: string) => + candidate === root || candidate.startsWith(root.endsWith(separator) ? root : root + separator); + +/** The version T3 runs for a driver: its default instance first, then any enabled one. */ +const providerVersion = (providers: ReadonlyArray, driver: string) => + ( + providers.find((provider) => provider.instanceId === driver && provider.version) ?? + providers.find((provider) => provider.driver === driver && provider.enabled && provider.version) + )?.version ?? "latest"; + +/** + * Claude and Codex home folders configured in settings: the built-in + * providers, provider instances, and their CLAUDE_CONFIG_DIR or CODEX_HOME. + * Sandboxes mount them so any of those providers can run inside. + */ +export const sandboxProviderHomes = (settings: ServerSettings): ReadonlyArray => { + const homes: Array = []; + const add = (value: unknown) => { + if (typeof value === "string" && value.trim().length > 0) { + homes.push(expandHomePath(value.trim())); + } + }; + add(settings.providers.codex.homePath); + add(settings.providers.codex.shadowHomePath); + add(settings.providers.claudeAgent.homePath); + for (const instance of Object.values(settings.providerInstances)) { + if (!Object.values(SANDBOX_DRIVERS).some((driver) => driver === instance.driver)) continue; + const config = instance.config; + if (typeof config === "object" && config !== null) { + if ("homePath" in config) add(config.homePath); + if ("shadowHomePath" in config) add(config.shadowHomePath); + } + for (const variable of instance.environment ?? []) { + if (variable.name === "CODEX_HOME" || variable.name === "CLAUDE_CONFIG_DIR") { + add(variable.value); + } + } + } + return homes; +}; + +const make = Effect.gen(function* () { + const platform = yield* HostProcessPlatform; + const fileSystem = yield* FileSystem.FileSystem; + const path = yield* Path.Path; + const processRunner = yield* ProcessRunner.ProcessRunner; + const serverConfig = yield* ServerConfig.ServerConfig; + const httpServer = yield* HttpServer.HttpServer; + const supported = SUPPORTED_PLATFORMS.has(platform); + const hostEnv = { ...process.env }; + const home = NodeOS.homedir(); + const registryPath = path.join(serverConfig.stateDir, "sandboxes.json"); + const owner = sandboxOwner(serverConfig.stateDir); + const records = new Map(); + const changes = yield* PubSub.unbounded(); + const stoppedWorktrees = yield* PubSub.unbounded(); + const registryLock = yield* Semaphore.make(1); + // Lookups wait until labeled containers missing from the saved list are adopted. + const ready = yield* Deferred.make(); + // Set while an unreadable list has not been rebuilt from Docker yet. Then + // no T3 worktree can be shown to be unsandboxed, so lookups there fail. + let unverified = false; + + // Agents reach T3's MCP endpoint on the server's own loopback address. The + // relay listens on that address and port inside the container and connects + // back. A wildcard bind is announced as 127.0.0.1; other addresses are + // reachable from the container without help. + const mcpReverse = (() => { + if (!NetAddress.isInetAddress(httpServer.address)) return null; + const host = NetAddress.isUnspecified(httpServer.address.address) + ? "127.0.0.1" + : NetAddress.formatIp(httpServer.address.address); + if (!host.startsWith("127.") && host !== "::1") return null; + return { host, port: httpServer.address.port }; + })(); + + const summarize = (record: SandboxRecord): SandboxSummary => ({ + worktreePath: record.worktreePath, + containerName: record.containerName, + image: record.image || "building", + status: record.status, + ports: record.tunnel?.ports ?? [], + error: record.error, + }); + const publish = () => PubSub.publishUnsafe(changes, undefined); + const setStatus = (record: SandboxRecord, status: SandboxStatus, error: string | null = null) => { + record.status = status; + record.error = error; + publish(); + }; + + const fail = + (operation: SandboxError["operation"], worktreePath: string, detail: string) => + (cause?: unknown) => + new SandboxError({ + operation, + worktreePath, + detail, + ...(cause === undefined ? {} : { cause }), + }); + + /** Runs a short Docker CLI command and returns trimmed stdout, failing on a non-zero exit. */ + const docker = ( + operation: SandboxError["operation"], + worktreePath: string, + args: ReadonlyArray, + options: { readonly stdin?: string; readonly onLine?: (line: string) => void } = {}, + ) => { + let partial = ""; + const onChunk = + options.onLine === undefined + ? undefined + : (chunk: Uint8Array) => { + const lines = (partial + Buffer.from(chunk).toString("utf8")).split("\n"); + partial = lines.pop() ?? ""; + for (const line of lines) if (line.trim().length > 0) options.onLine!(line); + }; + return processRunner + .run({ + command: DOCKER, + args, + env: hostEnv, + maxOutputBytes: 4 * 1024 * 1024, + outputMode: "truncate", + ...(options.stdin === undefined ? {} : { stdin: options.stdin }), + ...(onChunk === undefined ? {} : { onStdoutChunk: onChunk, onStderrChunk: onChunk }), + }) + .pipe( + Effect.mapError( + fail( + operation, + worktreePath, + "Docker is not installed or not on PATH. Install Docker to use sandboxes.", + ), + ), + Effect.flatMap((result) => + result.code === 0 + ? Effect.succeed(result.stdout.trim()) + : Effect.fail( + fail( + operation, + worktreePath, + `docker ${args[0]} failed: ${(result.stderr.trim() || result.stdout.trim()).slice(-400)}`, + )(), + ), + ), + ); + }; + + /** Saves the list. Writes are serialized so an older snapshot never lands last. */ + const persist = registryLock.withPermits(1)( + Effect.gen(function* () { + const contents = yield* encodeRegistry({ + version: 1, + ...(unverified ? { unverified: true } : {}), + sandboxes: [...records.values()].map((record) => ({ + worktreePath: record.worktreePath, + containerName: record.containerName, + image: record.image, + versions: record.versions, + mounts: record.mounts, + })), + }); + yield* writeFileStringAtomically({ filePath: registryPath, contents }); + }).pipe( + Effect.provideService(FileSystem.FileSystem, fileSystem), + Effect.provideService(Path.Path, path), + Effect.mapError(fail("create", registryPath, "Could not save the sandbox list.")), + ), + ); + const persistOrLog = persist.pipe( + Effect.catchCause((cause) => Effect.logError("Failed to save the sandbox list", { cause })), + ); + + const ensureImage = Effect.fn("SandboxService.ensureImage")(function* ( + record: SandboxRecord, + onOutput: (line: string) => void, + ) { + const input = { + uid: process.getuid?.() ?? 1000, + gid: process.getgid?.() ?? 1000, + home, + versions: record.versions, + }; + const tag = sandboxImageTag(input); + const exists = yield* docker("start", record.worktreePath, ["image", "inspect", tag]).pipe( + Effect.as(true), + Effect.orElseSucceed(() => false), + ); + if (!exists) { + onOutput(`Building sandbox image ${tag}`); + yield* docker("start", record.worktreePath, sandboxImageBuildArgs(input, tag), { + stdin: SANDBOX_DOCKERFILE, + onLine: onOutput, + }); + } + return tag; + }); + + /** Folders mounted at their own path. Only folders that exist are mounted. */ + const mountsFor = Effect.fn("SandboxService.mountsFor")(function* ( + worktreePath: string, + gitCommonDir: string, + projectRoot: string, + providers: ReadonlyArray, + homes: ReadonlyArray, + ) { + const providerHomes = providers + .filter((provider) => Object.values(SANDBOX_DRIVERS).some((d) => d === provider.driver)) + .flatMap((provider) => + provider.runtimePaths === undefined + ? [] + : [provider.runtimePaths.homePath, provider.runtimePaths.shadowHomePath ?? ""], + ) + .filter((home) => home.length > 0); + const candidates: ReadonlyArray = [ + { path: worktreePath, readOnly: false }, + { path: gitCommonDir, readOnly: false }, + { path: hostEnv.CLAUDE_CONFIG_DIR ?? path.join(home, ".claude"), readOnly: false }, + { path: hostEnv.CODEX_HOME ?? path.join(home, ".codex"), readOnly: false }, + ...[...providerHomes, ...homes].map((providerHome) => ({ + path: providerHome, + readOnly: false, + })), + { path: path.join(home, ".gitconfig"), readOnly: true }, + // Claude reads pasted images from T3's attachment folder. + { path: serverConfig.attachmentsDir, readOnly: true }, + // Setup scripts copy or link files such as .env from the checkout. A + // checkout that holds the home folder would hide the sandbox's own home. + ...(containsPath(projectRoot, home, path.sep) ? [] : [{ path: projectRoot, readOnly: true }]), + ]; + const mounts: Array = []; + for (const mount of candidates) { + if (!isMountablePath(mount.path)) continue; + // A writable mount already covers anything inside it; a read-only one + // covers only read-only paths, so the worktree and git dir stay writable. + const covered = mounts.some( + (existing) => + containsPath(existing.path, mount.path, path.sep) && + (!existing.readOnly || mount.readOnly), + ); + if (covered) continue; + if (yield* fileSystem.exists(mount.path).pipe(Effect.orElseSucceed(() => false))) { + mounts.push(mount); + } + } + return mounts; + }); + + const runContainer = Effect.fn("SandboxService.runContainer")(function* (record: SandboxRecord) { + yield* docker("start", record.worktreePath, ["rm", "--force", record.containerName]).pipe( + Effect.ignore, + ); + yield* docker( + "start", + record.worktreePath, + dockerRunArgs({ + owner, + containerName: record.containerName, + image: record.image, + worktreePath: record.worktreePath, + versions: record.versions, + mounts: record.mounts, + ipv6Loopback: mcpReverse?.host === "::1", + }), + ); + // Claude rewrites ~/.claude.json by renaming over it, which fails on a + // bind-mounted file. The sandbox gets its own copy; credentials stay + // shared through the mounted ~/.claude folder. + const claudeJson = path.join(home, ".claude.json"); + if (yield* fileSystem.exists(claudeJson).pipe(Effect.orElseSucceed(() => false))) { + yield* docker("start", record.worktreePath, [ + "cp", + "--archive", + claudeJson, + `${record.containerName}:${claudeJson}`, + ]).pipe(Effect.ignore); + } + }); + + const spawnDocker = (args: ReadonlyArray) => + NodeChildProcess.spawn(DOCKER, [...args], { env: hostEnv, stdio: ["pipe", "pipe", "pipe"] }); + + const startTunnel = (record: SandboxRecord) => { + const tunnel: SandboxTunnel = new SandboxTunnel({ + spawnRelay: () => + spawnDocker(["exec", "-i", record.containerName, "node", "-e", SANDBOX_RELAY_SOURCE]), + reversePorts: + mcpReverse === null + ? [] + : [{ host: mcpReverse.host, containerPort: mcpReverse.port, hostPort: mcpReverse.port }], + preferredHostPort: (containerPort) => + preferredSandboxHostPort(record.containerName, containerPort), + onPortsChanged: publish, + onExit: (detail) => { + if (record.tunnel !== tunnel) return; + record.tunnel = null; + // The relay only exits by itself when the container or Docker went away. + if (detail !== "closed") { + setStatus(record, "stopped"); + PubSub.publishUnsafe(stoppedWorktrees, record.worktreePath); + } else { + publish(); + } + }, + }); + record.tunnel = tunnel; + }; + + const release = (containerName: string, target: string) => { + const child = NodeChildProcess.spawn( + DOCKER, + ["exec", containerName, "node", "-e", SANDBOX_KILL_SOURCE, target], + { env: hostEnv, stdio: "ignore" }, + ); + child.on("error", () => {}); + child.unref(); + }; + + /** + * Builds the image and creates the container when either is missing, starts + * a stopped container, and starts the relay. Callers hold the record lock. + */ + const startUnlocked = (record: SandboxRecord, onOutput: (line: string) => void = () => {}) => + Effect.gen(function* () { + // A lookup can hold a record that Remove deleted while it waited for the lock. + if (records.get(record.worktreePath) !== record) return false; + if (record.status === "running" && record.tunnel?.alive === true) return true; + setStatus(record, "starting"); + const state = yield* docker("start", record.worktreePath, [ + "inspect", + "--format", + "{{.State.Running}}", + record.containerName, + ]).pipe(Effect.orElseSucceed(() => "missing")); + if (state === "missing") { + yield* docker("start", record.worktreePath, [ + "version", + "--format", + "{{.Server.Version}}", + ]).pipe( + Effect.mapError((error) => + fail( + "start", + record.worktreePath, + `Docker is not running. Start Docker and try again. (${error.detail})`, + )(error), + ), + ); + record.image = yield* ensureImage(record, onOutput); + yield* persistOrLog; + onOutput(`Starting container ${record.containerName}`); + yield* runContainer(record); + } else if (state !== "true") { + yield* docker("start", record.worktreePath, ["start", record.containerName]); + } + if (!record.reaped) { + // Commands an earlier server process started outlive it in the + // container; stop them like the host stops orphaned terminals. + yield* docker("start", record.worktreePath, [ + "exec", + record.containerName, + "node", + "-e", + SANDBOX_KILL_SOURCE, + "--all", + ]).pipe(Effect.ignore); + record.reaped = true; + } + if (record.tunnel?.alive !== true) startTunnel(record); + setStatus(record, "running"); + return true; + }).pipe( + Effect.tapError((error) => Effect.sync(() => setStatus(record, "error", error.detail))), + ); + + const ensureRunning = (record: SandboxRecord) => + record.lock.withPermits(1)(startUnlocked(record)); + + const recordFor = (cwd: string) => { + for (const record of records.values()) { + if (containsPath(record.worktreePath, cwd, path.sep)) return record; + } + return undefined; + }; + + /** True when `cwd` might be sandboxed but the list is unverified. Retries the rebuild once. */ + const unknownSandbox = (cwd: string) => + Effect.gen(function* () { + if (!unverified || !containsPath(serverConfig.worktreesDir, cwd, path.sep)) return false; + yield* reconcileOnce; + return unverified && recordFor(cwd) === undefined; + }); + + const makeExecTarget = (record: SandboxRecord): SandboxExecTarget => ({ + worktreePath: record.worktreePath, + containerName: record.containerName, + command: (input) => { + for (const name of ["CODEX_HOME", "CLAUDE_CONFIG_DIR"]) { + const value = input.env[name]; + if (value === undefined || value === hostEnv[name]) continue; + if (!record.mounts.some((mount) => containsPath(mount.path, value, path.sep))) { + throw fail( + "exec", + record.worktreePath, + `This provider uses ${name}=${value}, which this sandbox does not mount. Start a new sandbox after changing a provider's home folder.`, + )(); + } + } + const execId = NodeCrypto.randomUUID(); + let released = false; + return { + command: DOCKER, + args: dockerExecArgs({ + containerName: record.containerName, + execId, + cwd: input.cwd, + envNames: sandboxEnvNames(input.env, hostEnv), + tty: input.tty, + command: input.command, + args: input.args, + }), + env: { ...hostEnv, ...input.env }, + release: () => { + if (released) return; + released = true; + release(record.containerName, execId); + }, + }; + }, + }); + + /** + * The marker file for a worktree: `/t3code-sandbox.json`, + * found through the `.git` file a linked worktree has at its root. + */ + const markerPath = (worktreePath: string) => + fileSystem.readFileString(path.join(worktreePath, ".git")).pipe( + Effect.map((text) => /^gitdir:\s*(.+)$/m.exec(text)?.[1]?.trim()), + Effect.map((gitDir) => + gitDir === undefined + ? undefined + : path.join(path.resolve(worktreePath, gitDir), MARKER_FILE), + ), + Effect.orElseSucceed(() => undefined), + ); + + /** + * Rebuilds a sandbox from the marker in its worktree when the saved list + * lost it, so a lost list never lets sandboxed work start on the host. + */ + const recordFromMarker = (cwd: string) => + Effect.gen(function* () { + // Every ancestor is checked, so a submodule or nested repository inside + // a sandboxed worktree still finds the worktree's marker. + let dir = cwd; + while (true) { + const marker = yield* markerPath(dir); + const entry = + marker === undefined + ? undefined + : yield* fileSystem.readFileString(marker).pipe( + Effect.flatMap(decodeMarker), + Effect.orElseSucceed(() => undefined), + ); + if (entry !== undefined && entry.worktreePath === dir) { + const existing = records.get(entry.worktreePath); + if (existing !== undefined) return existing; + addLoadedRecord(entry); + publish(); + yield* persistOrLog; + return records.get(entry.worktreePath); + } + const parent = path.dirname(dir); + if (parent === dir) return undefined; + dir = parent; + } + }); + + /** The sandbox owning `cwd`, from memory or its worktree's marker. */ + const lookup = (cwd: string) => + Effect.suspend(() => { + const record = recordFor(cwd); + return record === undefined ? recordFromMarker(cwd) : Effect.succeed(record); + }); + + const register: SandboxService["Service"]["register"] = Effect.fn("SandboxService.register")( + function* (input) { + yield* Deferred.await(ready); + if (!supported) { + return yield* fail( + "create", + input.worktreePath, + "Sandboxes run on Linux and macOS hosts.", + )(); + } + if (!isMountablePath(input.worktreePath)) { + return yield* fail( + "create", + input.worktreePath, + "Sandboxes cannot mount a path that contains a comma.", + )(); + } + const gitCommonDir = yield* processRunner + .run({ + command: "git", + args: ["rev-parse", "--path-format=absolute", "--git-common-dir"], + cwd: input.worktreePath, + env: hostEnv, + }) + .pipe( + Effect.flatMap((result) => + result.code === 0 && result.stdout.trim().length > 0 + ? Effect.succeed(result.stdout.trim()) + : Effect.fail(result.stderr), + ), + Effect.mapError( + fail("create", input.worktreePath, "Could not find the worktree's git folder."), + ), + ); + records.get(input.worktreePath)?.tunnel?.close(); + const record: SandboxRecord = { + worktreePath: input.worktreePath, + containerName: sandboxContainerName(input.worktreePath), + versions: { + claude: providerVersion(input.providers, SANDBOX_DRIVERS.claude), + codex: providerVersion(input.providers, SANDBOX_DRIVERS.codex), + }, + mounts: yield* mountsFor( + input.worktreePath, + gitCommonDir, + input.projectRoot, + input.providers, + input.homes, + ), + image: "", + status: "starting", + error: null, + tunnel: null, + reaped: true, + lock: Semaphore.makeUnsafe(1), + }; + // Saved before the slow start, so terminals opened during the build wait + // for the sandbox instead of starting on the host. A failed start leaves + // the record in place for the next attempt. + records.set(record.worktreePath, record); + publish(); + const marker = yield* markerPath(record.worktreePath); + yield* persist.pipe( + Effect.andThen( + marker === undefined + ? fail("create", record.worktreePath, "The worktree has no git admin folder.")() + : encodeMarker(record).pipe( + Effect.flatMap((contents) => + writeFileStringAtomically({ filePath: marker, contents }), + ), + Effect.provideService(FileSystem.FileSystem, fileSystem), + Effect.provideService(Path.Path, path), + Effect.mapError( + fail("create", record.worktreePath, "Could not mark the worktree as sandboxed."), + ), + ), + ), + Effect.tapError(() => + Effect.sync(() => { + records.delete(record.worktreePath); + publish(); + }).pipe(Effect.andThen(persistOrLog)), + ), + ); + }, + ); + + const start: SandboxService["Service"]["start"] = Effect.fn("SandboxService.start")( + function* (input) { + const record = records.get(input.worktreePath); + if (record === undefined) { + return yield* fail("start", input.worktreePath, "This worktree has no sandbox.")(); + } + const onOutput = (line: string) => { + if (input.onOutput) Effect.runFork(input.onOutput(line)); + }; + yield* record.lock.withPermits(1)(startUnlocked(record, onOutput)); + return summarize(record); + }, + ); + + const execTarget: SandboxService["Service"]["execTarget"] = (cwd) => + Effect.gen(function* () { + yield* Deferred.await(ready); + if (yield* unknownSandbox(cwd)) { + return yield* fail( + "start", + cwd, + "T3 could not read its sandbox list and Docker is not reachable, so it cannot tell whether this worktree runs in a sandbox. Start Docker and try again.", + )(); + } + const record = yield* lookup(cwd); + if (record === undefined) return Option.none(); + return (yield* ensureRunning(record)) ? Option.some(makeExecTarget(record)) : Option.none(); + }); + + const stop: SandboxService["Service"]["stop"] = (worktreePath) => + Effect.gen(function* () { + const record = records.get(worktreePath); + if (record === undefined) return; + yield* record.lock.withPermits(1)( + Effect.gen(function* () { + record.tunnel?.close(); + record.tunnel = null; + yield* docker("stop", worktreePath, ["stop", "--time", "3", record.containerName]); + // The container's processes are gone, so nothing is left to reap. + record.reaped = true; + setStatus(record, "stopped"); + PubSub.publishUnsafe(stoppedWorktrees, worktreePath); + }), + ); + }); + + const remove: SandboxService["Service"]["remove"] = (worktreePath) => + Effect.gen(function* () { + const record = records.get(worktreePath); + if (record === undefined) return; + yield* record.lock.withPermits(1)( + Effect.gen(function* () { + record.tunnel?.close(); + record.tunnel = null; + // A failed first start can leave no container to delete. + yield* docker("remove", worktreePath, ["rm", "--force", record.containerName]).pipe( + Effect.catchIf( + (error) => /no such container/i.test(error.detail), + () => Effect.succeed(""), + ), + ); + records.delete(worktreePath); + publish(); + PubSub.publishUnsafe(stoppedWorktrees, worktreePath); + yield* persistOrLog; + const marker = yield* markerPath(worktreePath); + if (marker !== undefined) yield* fileSystem.remove(marker).pipe(Effect.ignore); + }), + ); + }); + + const list = Effect.sync(() => [...records.values()].map(summarize)); + + /** One-slot sliding mailbox: a slow client only ever holds the newest list. */ + const stream: SandboxService["Service"]["stream"] = Stream.callback( + (mailbox) => + Effect.gen(function* () { + const subscription = yield* PubSub.subscribe(changes); + Queue.offerUnsafe(mailbox, { sandboxes: yield* list }); + yield* Stream.fromSubscription(subscription).pipe( + Stream.runForEach(() => + Effect.map(list, (sandboxes) => Queue.offerUnsafe(mailbox, { sandboxes })), + ), + Effect.forkScoped, + ); + }), + { bufferSize: 1, strategy: "sliding" }, + ); + + const forwardedPorts: SandboxService["Service"]["forwardedPorts"] = () => + [...records.values()].flatMap((record) => + (record.tunnel?.ports ?? []).map((port) => ({ worktreePath: record.worktreePath, ...port })), + ); + + const worktreeExists = (worktreePath: string) => + fileSystem.exists(worktreePath).pipe(Effect.orElseSucceed(() => false)); + + const addLoadedRecord = (entry: { + readonly worktreePath: string; + readonly containerName: string; + readonly image: string; + readonly versions: SandboxCliVersions; + readonly mounts: ReadonlyArray; + }) => + records.set(entry.worktreePath, { + ...entry, + status: "stopped", + error: null, + tunnel: null, + reaped: false, + lock: Semaphore.makeUnsafe(1), + }); + + // Load the saved list. A missing file means no sandboxes yet; an unreadable + // one is logged, and the labeled containers below rebuild what they can. + const saved = yield* fileSystem.readFileString(registryPath).pipe( + Effect.flatMap(decodeRegistry), + Effect.map((registry) => { + if (registry.unverified === true) unverified = true; + return registry.sandboxes; + }), + Effect.catchCause((cause) => + fileSystem.exists(registryPath).pipe( + Effect.orElseSucceed(() => true), + Effect.flatMap((exists) => + exists + ? Effect.logError("Could not read the sandbox list", { registryPath, cause }).pipe( + Effect.tap(() => + Effect.sync(() => { + unverified = true; + }), + ), + ) + : Effect.void, + ), + Effect.as([]), + ), + ), + ); + for (const entry of saved) addLoadedRecord(entry); + + /** + * Adopts labeled containers the saved list does not know, drops sandboxes + * whose worktree is gone, and reconnects containers that are still running + * so their ports show up after a restart. + */ + const reconcile = Effect.gen(function* () { + const names = yield* docker("start", registryPath, [ + "ps", + "--all", + "--filter", + `label=${SANDBOX_LABELS.owner}=${owner}`, + "--format", + "{{.Names}}", + ]); + const containers = + names.length === 0 + ? [] + : yield* docker("start", registryPath, ["inspect", ...names.split("\n")]).pipe( + Effect.flatMap(decodeInspected), + ); + let changed = false; + for (const container of containers) { + const labels = container.Config.Labels ?? {}; + const worktreePath = labels[SANDBOX_LABELS.worktree]; + if (worktreePath === undefined || records.has(worktreePath)) continue; + addLoadedRecord({ + worktreePath, + containerName: container.Name.replace(/^\//, ""), + image: container.Config.Image, + versions: { + claude: labels[SANDBOX_LABELS.claude] ?? "latest", + codex: labels[SANDBOX_LABELS.codex] ?? "latest", + }, + mounts: (container.Mounts ?? []) + .filter((mount) => mount.Source === mount.Destination) + .map((mount) => ({ path: mount.Source, readOnly: !mount.RW })), + }); + changed = true; + } + for (const record of [...records.values()]) { + if (yield* worktreeExists(record.worktreePath)) continue; + records.delete(record.worktreePath); + changed = true; + yield* docker("remove", record.worktreePath, ["rm", "--force", record.containerName]).pipe( + Effect.ignore, + ); + } + if (unverified) changed = true; + unverified = false; + if (changed) { + publish(); + yield* persistOrLog; + } + const running = new Set( + containers.filter((container) => container.State.Running).map((c) => c.Name.slice(1)), + ); + return [...records.values()].filter((record) => running.has(record.containerName)); + }); + + const reconcileOnce = reconcile.pipe( + Effect.timeout("15 seconds"), + Effect.catchCause((cause) => + Effect.logWarning("Could not check sandbox containers", { cause }).pipe(Effect.as([])), + ), + ); + + yield* reconcile.pipe( + Effect.timeout("15 seconds"), + Effect.catchCause((cause) => + Effect.logWarning("Could not check sandbox containers", { cause }).pipe(Effect.as([])), + ), + Effect.tap(() => Deferred.succeed(ready, undefined)), + Effect.flatMap((running) => + Effect.forEach(running, (record) => ensureRunning(record).pipe(Effect.ignore), { + discard: true, + }), + ), + Effect.ensuring(Deferred.succeed(ready, undefined)), + Effect.forkScoped, + ); + yield* Effect.addFinalizer(() => + Effect.sync(() => { + for (const record of records.values()) record.tunnel?.close(); + }), + ); + + return SandboxService.of({ + supported, + register, + start, + execTarget, + isSandboxed: (cwd) => + Deferred.await(ready).pipe( + Effect.andThen(unknownSandbox(cwd)), + Effect.flatMap((unknown) => + unknown + ? Effect.succeed(true) + : lookup(cwd).pipe(Effect.map((record) => record !== undefined)), + ), + ), + stop, + remove, + list, + stream, + forwardedPorts, + stopped: Stream.fromPubSub(stoppedWorktrees), + }); +}); + +export const layer = Layer.effect(SandboxService, make); diff --git a/apps/server/src/sandbox/SandboxTunnel.test.ts b/apps/server/src/sandbox/SandboxTunnel.test.ts new file mode 100644 index 0000000000000..6c88d1f090f65 --- /dev/null +++ b/apps/server/src/sandbox/SandboxTunnel.test.ts @@ -0,0 +1,125 @@ +// @effect-diagnostics nodeBuiltinImport:off - drives the real relay script over sockets and pipes. +import * as NodeChildProcess from "node:child_process"; +import * as NodeFS from "node:fs"; +import * as NodeNet from "node:net"; +import * as NodeOS from "node:os"; +import * as NodePath from "node:path"; + +import type { SandboxPort } from "@t3tools/contracts"; +import { afterEach, describe, expect, it } from "vite-plus/test"; + +import { SANDBOX_RELAY_SOURCE, SandboxTunnel } from "./SandboxTunnel.ts"; + +// The relay normally runs in the container's network namespace. Here it runs +// on the host against a fake /proc, so forwarded and reverse ports must differ. +const cleanups: Array<() => void> = []; +afterEach(() => { + for (const cleanup of cleanups.splice(0).toReversed()) cleanup(); +}); + +const listenEcho = (prefix: string) => + new Promise((resolve) => { + const server = NodeNet.createServer((socket) => + socket.on("data", (chunk) => socket.write(`${prefix}${chunk.toString("utf8")}`)), + ); + cleanups.push(() => server.close()); + server.listen(0, "127.0.0.1", () => resolve(server)); + }); + +const portOf = (server: NodeNet.Server) => { + const address = server.address(); + if (address === null || typeof address !== "object") throw new Error("no address"); + return address.port; +}; + +const freePort = async () => { + const server = NodeNet.createServer(); + await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve)); + const port = portOf(server); + await new Promise((resolve) => server.close(() => resolve())); + return port; +}; + +const fakeProcRoot = (listeningPorts: ReadonlyArray) => { + const root = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-relay-proc-")); + cleanups.push(() => NodeFS.rmSync(root, { recursive: true, force: true })); + NodeFS.mkdirSync(NodePath.join(root, "net")); + const rows = listeningPorts.map( + (port, index) => + ` ${index}: 0100007F:${port.toString(16).toUpperCase().padStart(4, "0")} 00000000:0000 0A 00000000:00000000 00:00000000 00000000 1000 0 1 1 0 100 0 0 10 0`, + ); + NodeFS.writeFileSync( + NodePath.join(root, "net", "tcp"), + [" sl local_address rem_address st", ...rows].join("\n"), + ); + return root; +}; + +const roundTrip = (port: number, message: string) => + new Promise((resolve, reject) => { + const socket = NodeNet.connect({ host: "127.0.0.1", port }, () => socket.write(message)); + socket.once("data", (chunk) => { + socket.destroy(); + resolve(chunk.toString("utf8")); + }); + socket.once("error", reject); + }); + +describe("SandboxTunnel", () => { + it("forwards listening container ports to host loopback and reverse ports back", async () => { + const app = await listenEcho("app:"); + const mcp = await listenEcho("mcp:"); + const reverseContainerPort = await freePort(); + const procRoot = fakeProcRoot([portOf(app)]); + + let resolvePorts: (ports: ReadonlyArray) => void = () => {}; + const portsReady = new Promise>((resolve) => { + resolvePorts = resolve; + }); + const exits: Array = []; + const tunnel = new SandboxTunnel({ + spawnRelay: () => + NodeChildProcess.spawn(process.execPath, ["-e", SANDBOX_RELAY_SOURCE, procRoot], { + stdio: ["pipe", "pipe", "pipe"], + }), + reversePorts: [ + { host: "127.0.0.1", containerPort: reverseContainerPort, hostPort: portOf(mcp) }, + ], + preferredHostPort: () => 0, + onPortsChanged: (ports) => { + if (ports.length > 0) resolvePorts(ports); + }, + onExit: (detail) => exits.push(detail), + }); + cleanups.push(() => tunnel.close()); + + const [forwarded] = await portsReady; + expect(forwarded?.containerPort).toBe(portOf(app)); + expect(forwarded?.hostPort).not.toBe(portOf(app)); + expect(await roundTrip(forwarded!.hostPort, "hello")).toBe("app:hello"); + expect(await roundTrip(reverseContainerPort, "tools")).toBe("mcp:tools"); + + tunnel.close(); + expect(tunnel.alive).toBe(false); + expect(exits).toEqual(["closed"]); + }); + + it("reports the relay exiting on its own", async () => { + let resolveExit: (detail: string) => void = () => {}; + const exited = new Promise((resolve) => { + resolveExit = resolve; + }); + const tunnel = new SandboxTunnel({ + spawnRelay: () => + NodeChildProcess.spawn(process.execPath, ["-e", "process.exit(3)"], { + stdio: ["pipe", "pipe", "pipe"], + }), + reversePorts: [], + preferredHostPort: () => 0, + onPortsChanged: () => {}, + onExit: resolveExit, + }); + expect(await exited).toContain("relay exited (3)"); + expect(tunnel.alive).toBe(false); + }); +}); diff --git a/apps/server/src/sandbox/SandboxTunnel.ts b/apps/server/src/sandbox/SandboxTunnel.ts new file mode 100644 index 0000000000000..f5f676725e526 --- /dev/null +++ b/apps/server/src/sandbox/SandboxTunnel.ts @@ -0,0 +1,517 @@ +// @effect-diagnostics nodeBuiltinImport:off - the tunnel is plain sockets and pipes. +import type * as NodeChildProcess from "node:child_process"; +import * as NodeNet from "node:net"; + +import type { SandboxPort } from "@t3tools/contracts"; + +/** + * Network bridge between the server host and one sandbox container. + * + * A relay script runs inside the container under `docker exec -i` and talks + * to the host over its stdin and stdout with small frames. One relay carries + * every connection in both directions: + * + * - Ports apps open inside the container get a listener on the host's + * loopback, so previews reach them. The relay reports listening ports by + * reading `/proc/net/tcp`, so any port works without publishing it up front. + * - Reverse ports listen on the container's loopback and connect back to the + * same port on the host's loopback. Agents use this to reach T3's MCP + * endpoint at the same `127.0.0.1` URL they would use outside a sandbox. + * + * Only the Docker CLI is involved, so the same code works with Docker Engine + * on Linux and Docker Desktop on macOS, where container IPs are not routable. + * + * Frame: type (u8), connection id (u32), payload length (u32), payload. + * Host-opened connections use even ids and relay-opened ones odd ids. + */ +const FRAME = { + connect: 1, + accepted: 2, + data: 3, + end: 4, + close: 5, + ports: 6, + listen: 7, + error: 8, +} as const; + +const HEADER_BYTES = 9; + +/** + * Runs inside the container with `node -e [proc-root]`. Exits when + * the host closes its stdin. Tests pass a fake proc root. + */ +export const SANDBOX_RELAY_SOURCE = String.raw`"use strict"; +const net = require("net"); +const fs = require("fs"); +const T = { CONNECT: 1, ACCEPTED: 2, DATA: 3, END: 4, CLOSE: 5, PORTS: 6, LISTEN: 7, ERROR: 8 }; +const sockets = new Map(); +const pending = new Map(); +const relayPorts = new Set(); +let nextId = 1; +let paused = false; +let lastPorts = ""; +const procRoot = process.argv[1] || "/proc"; +function send(type, id, payload) { + const body = payload || Buffer.alloc(0); + const header = Buffer.allocUnsafe(9); + header.writeUInt8(type, 0); + header.writeUInt32BE(id, 1); + header.writeUInt32BE(body.length, 5); + if (!process.stdout.write(Buffer.concat([header, body])) && !paused) { + paused = true; + for (const socket of sockets.values()) socket.pause(); + process.stdout.once("drain", () => { + paused = false; + for (const socket of sockets.values()) socket.resume(); + }); + } +} +function port16(port) { + const buffer = Buffer.allocUnsafe(2); + buffer.writeUInt16BE(port, 0); + return buffer; +} +function attach(id, socket) { + sockets.set(id, socket); + if (paused) socket.pause(); + socket.on("data", (chunk) => send(T.DATA, id, chunk)); + socket.on("end", () => send(T.END, id)); + socket.on("error", () => {}); + socket.on("close", () => { + if (sockets.delete(id)) send(T.CLOSE, id); + }); +} +function writeTo(socket, chunk) { + if (socket.write(chunk)) return; + process.stdin.pause(); + const resume = () => { + socket.off("drain", resume); + socket.off("close", resume); + process.stdin.resume(); + }; + socket.on("drain", resume); + socket.on("close", resume); +} +function connectLocal(id, port) { + const entry = { chunks: [], ended: false, closed: false }; + pending.set(id, entry); + const attempt = (hosts) => { + const socket = net.connect({ host: hosts[0], port }); + const onError = () => { + if (entry.closed) return; + if (hosts.length > 1) return attempt(hosts.slice(1)); + pending.delete(id); + send(T.CLOSE, id); + }; + socket.once("error", onError); + socket.once("connect", () => { + socket.off("error", onError); + pending.delete(id); + if (entry.closed) return socket.destroy(); + for (const chunk of entry.chunks) socket.write(chunk); + if (entry.ended) socket.end(); + attach(id, socket); + }); + }; + attempt(["127.0.0.1", "::1"]); +} +function listen(port, host) { + relayPorts.add(port); + const server = net.createServer((socket) => { + const id = nextId; + nextId += 2; + send(T.ACCEPTED, id, port16(port)); + attach(id, socket); + }); + server.on("error", (error) => + send(T.ERROR, 0, Buffer.from("listen " + port + ": " + error.message)), + ); + server.listen(port, host); +} +function scanPorts() { + const ports = new Set(); + for (const file of [procRoot + "/net/tcp", procRoot + "/net/tcp6"]) { + let text = ""; + try { + text = fs.readFileSync(file, "utf8"); + } catch { + continue; + } + for (const line of text.split("\n").slice(1)) { + const columns = line.trim().split(/\s+/); + if (columns.length < 4 || columns[3] !== "0A") continue; + const port = parseInt(columns[1].split(":")[1], 16); + if (port > 0 && !relayPorts.has(port)) ports.add(port); + } + } + const list = [...ports].sort((a, b) => a - b); + const key = list.join(","); + if (key === lastPorts) return; + lastPorts = key; + send(T.PORTS, 0, Buffer.from(JSON.stringify(list))); +} +function handle(type, id, payload) { + if (type === T.CONNECT) return connectLocal(id, payload.readUInt16BE(0)); + if (type === T.LISTEN) return listen(payload.readUInt16BE(0), payload.toString("utf8", 2)); + const socket = sockets.get(id); + const entry = pending.get(id); + if (type === T.DATA) { + if (socket) writeTo(socket, payload); + else if (entry) entry.chunks.push(Buffer.from(payload)); + } else if (type === T.END) { + if (socket) socket.end(); + else if (entry) entry.ended = true; + } else if (type === T.CLOSE) { + if (socket) { + sockets.delete(id); + socket.destroy(); + } else if (entry) { + entry.closed = true; + pending.delete(id); + } + } +} +let buffer = Buffer.alloc(0); +process.stdin.on("data", (chunk) => { + buffer = buffer.length === 0 ? chunk : Buffer.concat([buffer, chunk]); + while (buffer.length >= 9) { + const length = buffer.readUInt32BE(5); + if (buffer.length < 9 + length) break; + const type = buffer.readUInt8(0); + const id = buffer.readUInt32BE(1); + const payload = buffer.subarray(9, 9 + length); + buffer = buffer.subarray(9 + length); + handle(type, id, payload); + } +}); +process.stdin.on("end", () => process.exit(0)); +setInterval(scanPorts, 1500); +scanPorts(); +`; + +/** + * Runs inside the container with `node -e `. Kills every + * process in the session of a command started through the sandbox exec + * launcher, or of every recorded command with `--all`. Killing a `docker exec` + * client leaves its process running in the container, so this is how commands + * stop. Each exec leads its own session, and children keep that session even + * after their parent exits, so none escape. A record whose leader is alive + * with a different start time belongs to a reused PID and is skipped. + */ +export const SANDBOX_KILL_SOURCE = String.raw`"use strict"; +const fs = require("fs"); +const dir = "/tmp/.t3-exec"; +const target = process.argv[1]; +let ids = [target]; +if (target === "--all") { + try { + ids = fs.readdirSync(dir); + } catch { + ids = []; + } +} +const stat = (pid) => { + try { + const text = fs.readFileSync("/proc/" + pid + "/stat", "utf8"); + const fields = text.slice(text.lastIndexOf(")") + 2).split(" "); + return { session: Number(fields[3]), start: fields[19] }; + } catch { + return null; + } +}; +const sessions = new Set(); +for (const id of ids) { + try { + const [pid, start] = fs.readFileSync(dir + "/" + id, "utf8").trim().split(" "); + fs.unlinkSync(dir + "/" + id); + const leader = stat(pid); + if (Number(pid) > 1 && (leader === null || leader.start === start)) sessions.add(Number(pid)); + } catch {} +} +const pids = []; +for (const entry of fs.readdirSync("/proc")) { + if (!/^\d+$/.test(entry) || Number(entry) === process.pid) continue; + const info = stat(entry); + if (info !== null && sessions.has(info.session)) pids.push(Number(entry)); +} +const signal = (name) => + pids.filter((pid) => { + try { + process.kill(pid, name); + return true; + } catch { + return false; + } + }).length; +if (signal("SIGTERM") > 0) setTimeout(() => signal("SIGKILL"), 2000); +`; + +/** + * Wraps a command so the container records its PID and start time under the + * exec id before running it. `SANDBOX_KILL_SOURCE` uses that record to stop + * it later. The launcher is `sh`, whose stat line has no spaces before field 22. + */ +export const sandboxExecLauncherArgs = ( + execId: string, + command: string, + args: ReadonlyArray, +): ReadonlyArray => [ + "/bin/sh", + "-c", + 'mkdir -p /tmp/.t3-exec && echo "$$ $(cut -d" " -f22 /proc/$$/stat)" > "/tmp/.t3-exec/$0" && exec "$@"', + execId, + command, + ...args, +]; + +export interface SandboxTunnelOptions { + /** Starts the relay: `docker exec -i node -e SANDBOX_RELAY_SOURCE`. */ + readonly spawnRelay: () => NodeChildProcess.ChildProcessWithoutNullStreams; + /** + * Loopback addresses that listen inside the container and connect back to + * the same address on the host, normally on the same port. + */ + readonly reversePorts: ReadonlyArray<{ + readonly host: string; + readonly containerPort: number; + readonly hostPort: number; + }>; + /** Host port to try first for a container port, so URLs stay stable across restarts. */ + readonly preferredHostPort: (containerPort: number) => number; + readonly onPortsChanged: (ports: ReadonlyArray) => void; + readonly onExit: (detail: string) => void; +} + +interface Forwarder { + readonly server: NodeNet.Server; + hostPort: number | null; +} + +interface PendingHostConnection { + readonly chunks: Array; + ended: boolean; + closed: boolean; +} + +/** Host side of the relay. Call `close` to stop it; `onExit` fires once either way. */ +export class SandboxTunnel { + private readonly relay: NodeChildProcess.ChildProcessWithoutNullStreams; + private readonly sockets = new Map(); + private readonly pendingHost = new Map(); + private readonly forwarders = new Map(); + private nextId = 2; + private paused = false; + private exited = false; + private buffer: Buffer = Buffer.alloc(0); + private stderrTail = ""; + private readonly options: SandboxTunnelOptions; + + constructor(options: SandboxTunnelOptions) { + this.options = options; + this.relay = options.spawnRelay(); + this.relay.stdout.on("data", (chunk: Buffer) => this.receive(chunk)); + this.relay.stderr.on("data", (chunk: Buffer) => { + this.stderrTail = (this.stderrTail + chunk.toString("utf8")).slice(-500); + }); + this.relay.stdin.on("error", () => {}); + this.relay.on("error", (error) => this.shutdown(`relay failed to start: ${error.message}`)); + this.relay.on("exit", (code, signal) => + this.shutdown( + `relay exited (${signal ?? code ?? "unknown"})${this.stderrTail ? `: ${this.stderrTail.trim()}` : ""}`, + ), + ); + for (const { host, containerPort } of options.reversePorts) { + this.send(FRAME.listen, 0, Buffer.concat([port16(containerPort), Buffer.from(host)])); + } + } + + /** Forwarded ports that currently have a host listener. */ + get ports(): ReadonlyArray { + const ports: Array = []; + for (const [containerPort, forwarder] of this.forwarders) { + if (forwarder.hostPort !== null) ports.push({ containerPort, hostPort: forwarder.hostPort }); + } + return ports.toSorted((left, right) => left.containerPort - right.containerPort); + } + + get alive(): boolean { + return !this.exited; + } + + close(): void { + this.relay.stdin.end(); + this.relay.kill("SIGTERM"); + this.shutdown("closed"); + } + + private shutdown(detail: string): void { + if (this.exited) return; + this.exited = true; + for (const socket of this.sockets.values()) socket.destroy(); + this.sockets.clear(); + this.pendingHost.clear(); + for (const forwarder of this.forwarders.values()) forwarder.server.close(); + this.forwarders.clear(); + this.options.onExit(detail); + } + + private send(type: number, id: number, payload: Buffer = Buffer.alloc(0)): void { + if (this.exited) return; + const header = Buffer.allocUnsafe(HEADER_BYTES); + header.writeUInt8(type, 0); + header.writeUInt32BE(id, 1); + header.writeUInt32BE(payload.length, 5); + if (!this.relay.stdin.write(Buffer.concat([header, payload])) && !this.paused) { + this.paused = true; + for (const socket of this.sockets.values()) socket.pause(); + this.relay.stdin.once("drain", () => { + this.paused = false; + for (const socket of this.sockets.values()) socket.resume(); + }); + } + } + + private receive(chunk: Buffer): void { + this.buffer = this.buffer.length === 0 ? chunk : Buffer.concat([this.buffer, chunk]); + while (this.buffer.length >= HEADER_BYTES) { + const length = this.buffer.readUInt32BE(5); + if (this.buffer.length < HEADER_BYTES + length) return; + const type = this.buffer.readUInt8(0); + const id = this.buffer.readUInt32BE(1); + const payload = Buffer.from(this.buffer.subarray(HEADER_BYTES, HEADER_BYTES + length)); + this.buffer = this.buffer.subarray(HEADER_BYTES + length); + this.handle(type, id, payload); + } + } + + private handle(type: number, id: number, payload: Buffer): void { + switch (type) { + case FRAME.ports: + this.syncForwarders(parsePorts(payload)); + return; + case FRAME.accepted: + this.connectHost(id, payload.readUInt16BE(0)); + return; + case FRAME.error: + // Reverse listeners only fail when the port is taken inside the + // container; the agent then cannot reach MCP, which it reports itself. + return; + } + const socket = this.sockets.get(id); + const pending = this.pendingHost.get(id); + if (type === FRAME.data) { + if (socket) this.writeTo(socket, payload); + else pending?.chunks.push(payload); + } else if (type === FRAME.end) { + if (socket) socket.end(); + else if (pending) pending.ended = true; + } else if (type === FRAME.close) { + if (socket) { + this.sockets.delete(id); + socket.destroy(); + } else if (pending) { + pending.closed = true; + this.pendingHost.delete(id); + } + } + } + + private writeTo(socket: NodeNet.Socket, chunk: Buffer): void { + if (socket.write(chunk)) return; + this.relay.stdout.pause(); + const resume = () => { + socket.off("drain", resume); + socket.off("close", resume); + this.relay.stdout.resume(); + }; + socket.on("drain", resume); + socket.on("close", resume); + } + + private attach(id: number, socket: NodeNet.Socket): void { + this.sockets.set(id, socket); + if (this.paused) socket.pause(); + socket.on("data", (chunk: Buffer) => this.send(FRAME.data, id, chunk)); + socket.on("end", () => this.send(FRAME.end, id)); + socket.on("error", () => {}); + socket.on("close", () => { + if (this.sockets.delete(id)) this.send(FRAME.close, id); + }); + } + + /** A connection opened inside the container on a reverse port. */ + private connectHost(id: number, containerPort: number): void { + const target = this.options.reversePorts.find((entry) => entry.containerPort === containerPort); + if (target === undefined) return this.send(FRAME.close, id); + const pending: PendingHostConnection = { chunks: [], ended: false, closed: false }; + this.pendingHost.set(id, pending); + const socket = NodeNet.connect({ host: target.host, port: target.hostPort }); + socket.once("error", () => { + if (this.pendingHost.delete(id)) this.send(FRAME.close, id); + }); + socket.once("connect", () => { + this.pendingHost.delete(id); + if (pending.closed || this.exited) return void socket.destroy(); + for (const chunk of pending.chunks) socket.write(chunk); + if (pending.ended) socket.end(); + this.attach(id, socket); + }); + } + + private syncForwarders(containerPorts: ReadonlyArray): void { + const wanted = new Set(containerPorts); + let changed = false; + for (const [containerPort, forwarder] of this.forwarders) { + if (wanted.has(containerPort)) continue; + forwarder.server.close(); + this.forwarders.delete(containerPort); + changed = true; + } + for (const containerPort of wanted) { + if (this.forwarders.has(containerPort)) continue; + this.openForwarder(containerPort); + } + if (changed) this.options.onPortsChanged(this.ports); + } + + private openForwarder(containerPort: number): void { + const server = NodeNet.createServer((socket) => { + const id = this.nextId; + this.nextId += 2; + this.send(FRAME.connect, id, port16(containerPort)); + this.attach(id, socket); + }); + const forwarder: Forwarder = { server, hostPort: null }; + this.forwarders.set(containerPort, forwarder); + const listen = (port: number) => server.listen(port, "127.0.0.1"); + server.on("listening", () => { + const address = server.address(); + if (this.forwarders.get(containerPort) !== forwarder || typeof address !== "object") return; + forwarder.hostPort = address?.port ?? null; + this.options.onPortsChanged(this.ports); + }); + server.on("error", (error: NodeJS.ErrnoException) => { + // The stable port is taken: fall back to any free port once. + if (error.code === "EADDRINUSE" && forwarder.hostPort === null) listen(0); + }); + listen(this.options.preferredHostPort(containerPort)); + } +} + +function port16(port: number): Buffer { + const buffer = Buffer.allocUnsafe(2); + buffer.writeUInt16BE(port, 0); + return buffer; +} + +function parsePorts(payload: Buffer): ReadonlyArray { + try { + const parsed: unknown = JSON.parse(payload.toString("utf8")); + return Array.isArray(parsed) + ? parsed.filter((port): port is number => Number.isInteger(port) && port > 0 && port < 65536) + : []; + } catch { + return []; + } +} diff --git a/apps/server/src/sandbox/sandboxClaudeSpawn.ts b/apps/server/src/sandbox/sandboxClaudeSpawn.ts new file mode 100644 index 0000000000000..17fc03ea36bfe --- /dev/null +++ b/apps/server/src/sandbox/sandboxClaudeSpawn.ts @@ -0,0 +1,39 @@ +// @effect-diagnostics nodeBuiltinImport:off - the Claude SDK spawn hook must return a Node child process. +import * as NodeChildProcess from "node:child_process"; +import * as NodePath from "node:path"; + +import type { SpawnedProcess, SpawnOptions } from "@anthropic-ai/claude-agent-sdk"; + +import type { SandboxExecTarget } from "./SandboxService.ts"; + +const SCRIPT_RUNTIMES = new Set(["node", "bun", "deno"]); + +/** + * `spawnClaudeCodeProcess` for a sandboxed worktree. The SDK passes the + * host's Claude executable, which may be a macOS binary; the image's own + * `claude` (pinned to the host version) runs instead with the same arguments. + */ +export const sandboxClaudeSpawn = + (target: SandboxExecTarget) => + (options: SpawnOptions): SpawnedProcess => { + const runtime = NodePath.basename(options.command).replace(/\.exe$/, ""); + const args = + SCRIPT_RUNTIMES.has(runtime) && /\.(c|m)?js$/.test(options.args[0] ?? "") + ? options.args.slice(1) + : options.args; + const command = target.command({ + command: "claude", + args, + cwd: options.cwd ?? target.worktreePath, + env: options.env, + tty: false, + }); + const child = NodeChildProcess.spawn(command.command, [...command.args], { + env: command.env, + stdio: ["pipe", "pipe", "pipe"], + signal: options.signal, + }); + child.once("exit", command.release); + child.once("error", command.release); + return child; + }; diff --git a/apps/server/src/sandbox/sandboxDocker.test.ts b/apps/server/src/sandbox/sandboxDocker.test.ts new file mode 100644 index 0000000000000..a578406e6050c --- /dev/null +++ b/apps/server/src/sandbox/sandboxDocker.test.ts @@ -0,0 +1,82 @@ +import { describe, expect, it } from "vite-plus/test"; + +import { + dockerExecArgs, + preferredSandboxHostPort, + sandboxContainerName, + sandboxEnvNames, +} from "./sandboxDocker.ts"; + +describe("sandboxEnvNames", () => { + const hostEnv = { + PATH: "/usr/local/bin:/usr/bin", + HOME: "/Users/theo", + XDG_RUNTIME_DIR: "/run/user/501", + EDITOR: "vim", + ANTHROPIC_API_KEY: "sk-host", + LANG: "en_US.UTF-8", + }; + + it("passes overrides and inherited credentials but not host plumbing", () => { + const names = sandboxEnvNames( + { + ...hostEnv, + PATH: "/managed/bin:/usr/local/bin:/usr/bin", + CLAUDE_CODE_ENTRYPOINT: "sdk-ts", + T3_THREAD: "thread-1", + }, + hostEnv, + ); + expect(names).toEqual(["ANTHROPIC_API_KEY", "CLAUDE_CODE_ENTRYPOINT", "LANG", "T3_THREAD"]); + }); + + it("skips unset values", () => { + expect(sandboxEnvNames({ OPENAI_API_KEY: undefined }, {})).toEqual([]); + }); +}); + +describe("dockerExecArgs", () => { + it("names env vars without their values and records the command's pid", () => { + const args = dockerExecArgs({ + containerName: "t3code-sandbox-x", + execId: "exec-1", + cwd: "/work/tree", + envNames: ["ANTHROPIC_API_KEY"], + tty: false, + command: "claude", + args: ["--output-format", "stream-json"], + }); + expect(args).toEqual([ + "exec", + "-i", + "-w", + "/work/tree", + "-e", + "ANTHROPIC_API_KEY", + "t3code-sandbox-x", + "/bin/sh", + "-c", + 'mkdir -p /tmp/.t3-exec && echo "$$ $(cut -d" " -f22 /proc/$$/stat)" > "/tmp/.t3-exec/$0" && exec "$@"', + "exec-1", + "claude", + "--output-format", + "stream-json", + ]); + }); +}); + +describe("sandbox names", () => { + it("derives a stable, Docker-safe container name per worktree", () => { + const name = sandboxContainerName("/Users/theo/.t3/worktrees/t3code/Feature Branch!"); + expect(name).toMatch(/^t3code-sandbox-feature-branch-[0-9a-f]{8}$/); + expect(sandboxContainerName("/Users/theo/.t3/worktrees/t3code/Feature Branch!")).toBe(name); + expect(sandboxContainerName("/other/Feature Branch!")).not.toBe(name); + }); + + it("keeps preferred host ports in a fixed range", () => { + const port = preferredSandboxHostPort("t3code-sandbox-x", 3000); + expect(port).toBeGreaterThanOrEqual(42000); + expect(port).toBeLessThan(50000); + expect(preferredSandboxHostPort("t3code-sandbox-x", 3000)).toBe(port); + }); +}); diff --git a/apps/server/src/sandbox/sandboxDocker.ts b/apps/server/src/sandbox/sandboxDocker.ts new file mode 100644 index 0000000000000..b5bbe4098ed96 --- /dev/null +++ b/apps/server/src/sandbox/sandboxDocker.ts @@ -0,0 +1,247 @@ +// @effect-diagnostics nodeBuiltinImport:off - hashing image and container names. +import * as NodeCrypto from "node:crypto"; +import * as NodePath from "node:path"; + +import { sandboxExecLauncherArgs } from "./SandboxTunnel.ts"; + +/** + * The sandbox image: a Debian Node image with Claude Code and Codex pinned to + * the versions T3 runs on the host, and a user whose uid, gid, and home path match the + * host. Matching ids keep files the agent writes in the worktree owned by the + * user. Matching the home path lets the provider config folders mount at the + * same paths, so session files the host reads stay where it expects them. + * The user has passwordless sudo so agents can install services like + * databases inside their own sandbox. + */ +export const SANDBOX_DOCKERFILE = `FROM node:24 +ARG SANDBOX_UID +ARG SANDBOX_GID +ARG SANDBOX_HOME +ARG CLAUDE_VERSION=latest +ARG CODEX_VERSION=latest +RUN apt-get update \\ + && apt-get install -y --no-install-recommends sudo ripgrep jq less procps lsof iproute2 \\ + && rm -rf /var/lib/apt/lists/* +RUN npm install -g "@anthropic-ai/claude-code@\${CLAUDE_VERSION}" "@openai/codex@\${CODEX_VERSION}" \\ + && npm cache clean --force +RUN userdel -r node 2>/dev/null || true \\ + && (getent group "\${SANDBOX_GID}" >/dev/null || groupadd -g "\${SANDBOX_GID}" t3) \\ + && useradd -o -u "\${SANDBOX_UID}" -g "\${SANDBOX_GID}" -d "\${SANDBOX_HOME}" -m -s /bin/bash t3 \\ + && echo "t3 ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/t3 \\ + && chmod 0440 /etc/sudoers.d/t3 +USER \${SANDBOX_UID}:\${SANDBOX_GID} +ENV HOME=\${SANDBOX_HOME} SHELL=/bin/bash \\ + GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=safe.directory GIT_CONFIG_VALUE_0=* +CMD ["sleep", "infinity"] +`; + +/** Labels on every container and image T3 creates. Containers carry enough to be adopted. */ +export const SANDBOX_LABELS = { + sandbox: "t3code.sandbox", + /** Hash of the owning server's state dir, so servers on one machine never adopt each other's. */ + owner: "t3code.sandbox.owner", + worktree: "t3code.sandbox.worktree", + claude: "t3code.sandbox.claude", + codex: "t3code.sandbox.codex", +} as const; + +/** Claude Code and Codex versions installed in the image, or "latest". */ +export interface SandboxCliVersions { + readonly claude: string; + readonly codex: string; +} + +export interface SandboxImageInput { + readonly uid: number; + readonly gid: number; + readonly home: string; + readonly versions: SandboxCliVersions; +} + +const shortHash = (value: string, length: number) => + NodeCrypto.createHash("sha256").update(value).digest("hex").slice(0, length); + +/** Images are content addressed, so a new CLI version builds a new image. */ +export const sandboxImageTag = (input: SandboxImageInput): string => + `t3code-sandbox:${shortHash( + JSON.stringify([ + SANDBOX_DOCKERFILE, + input.uid, + input.gid, + input.home, + input.versions.claude, + input.versions.codex, + ]), + 12, + )}`; + +export const sandboxImageBuildArgs = ( + input: SandboxImageInput, + tag: string, +): ReadonlyArray => [ + "build", + "--progress=plain", + "--label", + `${SANDBOX_LABELS.sandbox}=1`, + "--build-arg", + `SANDBOX_UID=${input.uid}`, + "--build-arg", + `SANDBOX_GID=${input.gid}`, + "--build-arg", + `SANDBOX_HOME=${input.home}`, + "--build-arg", + `CLAUDE_VERSION=${input.versions.claude}`, + "--build-arg", + `CODEX_VERSION=${input.versions.codex}`, + "-t", + tag, + "-", +]; + +/** Owner label value for a server state dir. */ +export const sandboxOwner = (stateDir: string): string => shortHash(stateDir, 16); + +/** Stable per worktree, readable in `docker ps`. */ +export const sandboxContainerName = (worktreePath: string): string => { + const slug = + NodePath.basename(worktreePath) + .toLowerCase() + .replace(/[^a-z0-9_.-]+/g, "-") + .slice(0, 40) + .replace(/^[^a-z0-9]+|[^a-z0-9]+$/g, "") || "worktree"; + return `t3code-sandbox-${slug}-${shortHash(worktreePath, 8)}`; +}; + +/** + * Host port to try first for a forwarded container port. Stable per + * container and port, so preview URLs survive server restarts. + */ +export const preferredSandboxHostPort = (containerName: string, containerPort: number): number => + 42000 + (Number.parseInt(shortHash(`${containerName}:${containerPort}`, 6), 16) % 8000); + +export interface SandboxMount { + readonly path: string; + readonly readOnly: boolean; +} + +/** Each mount lands at the same path inside the container. */ +export const dockerRunArgs = (input: { + readonly owner: string; + readonly containerName: string; + readonly image: string; + readonly worktreePath: string; + readonly versions: SandboxCliVersions; + readonly mounts: ReadonlyArray; + /** Docker disables IPv6 in containers by default; a server bound to ::1 needs it on loopback. */ + readonly ipv6Loopback: boolean; +}): ReadonlyArray => [ + "run", + "--detach", + "--init", + "--name", + input.containerName, + "--hostname", + "t3-sandbox", + "--label", + `${SANDBOX_LABELS.sandbox}=1`, + "--label", + `${SANDBOX_LABELS.owner}=${input.owner}`, + "--label", + `${SANDBOX_LABELS.worktree}=${input.worktreePath}`, + "--label", + `${SANDBOX_LABELS.claude}=${input.versions.claude}`, + "--label", + `${SANDBOX_LABELS.codex}=${input.versions.codex}`, + ...(input.ipv6Loopback ? ["--sysctl", "net.ipv6.conf.lo.disable_ipv6=0"] : []), + ...input.mounts.flatMap((mount) => [ + "--mount", + `type=bind,source=${mount.path},target=${mount.path}${mount.readOnly ? ",readonly" : ""}`, + ]), + input.image, +]; + +/** `--mount` is comma separated, so a comma in a path cannot be expressed. */ +export const isMountablePath = (path: string): boolean => !path.includes(","); + +const SKIPPED_NAMES = new Set([ + "PATH", + "HOME", + "USER", + "LOGNAME", + "SHELL", + "PWD", + "OLDPWD", + "SHLVL", + "_", + "TMPDIR", + "TMP", + "TEMP", + "HOSTNAME", + "DISPLAY", + "WAYLAND_DISPLAY", + "SSH_AUTH_SOCK", + "NODE_OPTIONS", + "NODE_PATH", + "APPIMAGE", + "APPDIR", + "OWD", + "ARGV0", +]); +const SKIPPED_PREFIXES = [ + "XDG_", + "DBUS_", + "LD_", + "DYLD_", + "ELECTRON_", + "VSCODE_", + "TERM_PROGRAM", + "__CF", + "npm_", + "CHROME_", +]; +/** Inherited host variables worth passing: provider credentials, proxies, locale. */ +const INHERITED_NAMES = + /^(ANTHROPIC_|CLAUDE_|OPENAI_|CODEX_|AWS_|GOOGLE_|GEMINI_|VERTEX_|AZURE_|LC_)|^(HTTPS?_PROXY|NO_PROXY|ALL_PROXY|https?_proxy|no_proxy|all_proxy|LANG|TERM|COLORTERM|TZ|GH_TOKEN|GITHUB_TOKEN)$/; + +/** + * Names of the variables a sandboxed command should receive. A command's env + * is usually the server's own env plus overrides. Host paths and session + * plumbing (PATH, HOME, XDG_*) would break inside the container, so only the + * overrides and a short list of inherited credentials and locale pass through. + */ +export const sandboxEnvNames = ( + env: NodeJS.ProcessEnv, + hostEnv: NodeJS.ProcessEnv, +): ReadonlyArray => + Object.keys(env) + .filter((name) => { + const value = env[name]; + if (value === undefined || name.includes("=")) return false; + if (SKIPPED_NAMES.has(name) || SKIPPED_PREFIXES.some((prefix) => name.startsWith(prefix))) { + return false; + } + return value !== hostEnv[name] || INHERITED_NAMES.test(name); + }) + .toSorted(); + +/** + * `docker exec` arguments for one command. Values travel in the Docker + * client's own env (`-e NAME` copies them), so secrets never appear in argv. + */ +export const dockerExecArgs = (input: { + readonly containerName: string; + readonly execId: string; + readonly cwd: string; + readonly envNames: ReadonlyArray; + readonly tty: boolean; + readonly command: string; + readonly args: ReadonlyArray; +}): ReadonlyArray => [ + "exec", + input.tty ? "-it" : "-i", + "-w", + input.cwd, + ...input.envNames.flatMap((name) => ["-e", name]), + input.containerName, + ...sandboxExecLauncherArgs(input.execId, input.command, input.args), +]; diff --git a/apps/server/src/server.ts b/apps/server/src/server.ts index 9e9d5c5e30644..af982f3eb50e1 100644 --- a/apps/server/src/server.ts +++ b/apps/server/src/server.ts @@ -70,6 +70,7 @@ import * as DeviceService from "./device/DeviceService.ts"; import { deviceHubProxyRouteLayer } from "./device/DeviceHubProxy.ts"; import * as PreviewManager from "./preview/Manager.ts"; import * as PortScanner from "./preview/PortScanner.ts"; +import * as SandboxService from "./sandbox/SandboxService.ts"; import * as ProcessRunner from "./processRunner.ts"; import * as GitManager from "./git/GitManager.ts"; import * as EnvironmentTheme from "./environmentTheme.ts"; @@ -594,6 +595,7 @@ const RuntimeCoreDependenciesLive = RuntimeCoreDependenciesBaseLive.pipe( OpenCodeRuntime.OpenCodeRuntimeLive.pipe(Layer.provide(OpenCodeServerLedger.layer)), ), Layer.provideMerge(WorkspaceLayerLive), + Layer.provideMerge(SandboxService.layer.pipe(Layer.provide(ProcessRunner.layer))), Layer.provideMerge(ProjectEnrichmentService.layer), Layer.provideMerge(Layer.mergeAll(NativeAppIconResolver.layer, ProjectFaviconResolverLayerLive)), Layer.provideMerge(RepositoryIdentityResolverLayerLive), diff --git a/apps/server/src/terminal/Manager.ts b/apps/server/src/terminal/Manager.ts index 6122c8606f0b0..be1a786a6930b 100644 --- a/apps/server/src/terminal/Manager.ts +++ b/apps/server/src/terminal/Manager.ts @@ -77,6 +77,7 @@ import * as ProcessRunner from "../processRunner.ts"; import * as PortScanner from "../preview/PortScanner.ts"; import * as NativeTelemetryClient from "../resourceTelemetry/NativeTelemetryClient.ts"; import * as PtyAdapter from "./PtyAdapter.ts"; +import * as SandboxService from "../sandbox/SandboxService.ts"; export { TerminalCwdError, @@ -1375,6 +1376,8 @@ interface TerminalManagerOptions { readonly threadId: string; readonly terminalId: string; }) => Effect.Effect; + /** Terminals whose cwd is in a sandboxed worktree open a shell in its container. */ + sandboxes?: SandboxService.SandboxService["Service"]; resolveProviderInstanceEnvironment?: ( providerInstanceId: string, env: Record | undefined, @@ -1432,6 +1435,7 @@ export const make = Effect.fn("TerminalManager.make")(function* () { const portDiscovery = yield* PortScanner.PortDiscovery; const nativeTelemetry = yield* NativeTelemetryClient.NativeTelemetryClient; const serverSettings = yield* ServerSettings.ServerSettingsService; + const sandboxes = yield* Effect.serviceOption(SandboxService.SandboxService); const path = yield* Path.Path; const resolveProviderInstanceEnvironment = Effect.fn( "terminal.resolveProviderInstanceEnvironment", @@ -1456,9 +1460,34 @@ export const make = Effect.fn("TerminalManager.make")(function* () { registerTerminalProcesses: portDiscovery.registerTerminalProcesses, unregisterTerminal: portDiscovery.unregisterTerminal, resolveProviderInstanceEnvironment, + ...(Option.isSome(sandboxes) ? { sandboxes: sandboxes.value } : {}), }); }); +/** + * Killing the `docker exec` client leaves the sandbox shell and its children + * running, so a sandbox terminal also stops its process tree in the container. + */ +function releaseSandboxOnExit( + process: PtyAdapter.PtyProcess, + release: () => void, +): PtyAdapter.PtyProcess { + process.onExit(release); + return { + get pid() { + return process.pid; + }, + write: (data) => process.write(data), + resize: (cols, rows) => process.resize(cols, rows), + kill: (signal) => { + process.kill(signal); + release(); + }, + onData: (callback) => process.onData(callback), + onExit: (callback) => process.onExit(callback), + }; +} + export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(function* ( options: TerminalManagerOptions, ) { @@ -2217,6 +2246,45 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func return yield* trySpawn(shellCandidates, spawnEnv, session, index + 1, spawnError); }); + /** + * Spawns the session's shell. In a sandboxed worktree the shell is bash + * inside the container, reached through `docker exec -it`. + */ + const spawnShell = Effect.fn("terminal.spawnShell")(function* ( + shellCandidates: ReadonlyArray, + spawnEnv: NodeJS.ProcessEnv, + session: TerminalSessionState, + ) { + const sandbox = + options.sandboxes === undefined + ? Option.none() + : yield* options.sandboxes + .execTarget(session.cwd) + .pipe( + Effect.mapError( + (cause) => new PtyAdapter.PtySpawnError({ adapter: "sandbox", cause }), + ), + ); + if (Option.isNone(sandbox)) return yield* trySpawn(shellCandidates, spawnEnv, session); + const command = yield* Effect.try({ + try: () => + sandbox.value.command({ + command: "/bin/bash", + args: ["-l"], + cwd: session.cwd, + env: spawnEnv, + tty: true, + }), + catch: (cause) => new PtyAdapter.PtySpawnError({ adapter: "sandbox", cause }), + }); + const spawned = yield* trySpawn( + [{ shell: command.command, args: [...command.args] }], + command.env, + session, + ).pipe(Effect.tapError(() => Effect.sync(command.release))); + return { ...spawned, process: releaseSandboxOnExit(spawned.process, command.release) }; + }); + const startSession = Effect.fn("terminal.startSession")(function* ( session: TerminalSessionState, input: TerminalStartInput, @@ -2290,7 +2358,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func } } } - const spawnResult = yield* trySpawn(shellCandidates, terminalEnv, session); + const spawnResult = yield* spawnShell(shellCandidates, terminalEnv, session); ptyProcess = spawnResult.process; startedShell = spawnResult.shellLabel; diff --git a/apps/server/src/ws.ts b/apps/server/src/ws.ts index 783377666f147..b7ee5b51abb8f 100644 --- a/apps/server/src/ws.ts +++ b/apps/server/src/ws.ts @@ -97,6 +97,7 @@ import { type TerminalMetadataStreamEvent, type PullRequestRef, WS_METHODS, + SandboxRequestError, WsRpcGroup, } from "@t3tools/contracts"; import { resolveServerBackgroundActivitySettings } from "@t3tools/shared/backgroundActivitySettings"; @@ -203,6 +204,7 @@ import * as ProjectSetupScriptRunner from "./project/ProjectSetupScriptRunner.ts import * as ProjectCloneTracker from "./project/ProjectCloneTracker.ts"; import * as RepositoryIdentityResolver from "./project/RepositoryIdentityResolver.ts"; import * as WorktreeSetupTracker from "./project/WorktreeSetupTracker.ts"; +import * as SandboxService from "./sandbox/SandboxService.ts"; import * as ServerEnvironment from "./environment/ServerEnvironment.ts"; import * as RemoteOpenTargets from "./environment/RemoteOpenTargets.ts"; import * as BackgroundPolicy from "./background/BackgroundPolicy.ts"; @@ -1236,6 +1238,7 @@ const makeWsRpcLayer = ( const usageLimitSources = yield* UsageLimitSources.UsageLimitSources; const projectSetupScriptRunner = yield* ProjectSetupScriptRunner.ProjectSetupScriptRunner; const worktreeSetupTracker = yield* WorktreeSetupTracker.WorktreeSetupTracker; + const sandboxes = yield* SandboxService.SandboxService; const projectCloneTracker = yield* ProjectCloneTracker.ProjectCloneTracker; const repositoryIdentityResolver = yield* RepositoryIdentityResolver.RepositoryIdentityResolver; @@ -1747,6 +1750,7 @@ const makeWsRpcLayer = ( shellResumeCompletionMarker: true, threadResumeCompletionMarker: true, threadSnapshotPagination: true, + ...(sandboxes.supported ? { sandboxes: true } : {}), ...Option.match(scratchWorkspaceRoot, { onNone: () => ({}), onSome: (root) => ({ scratchWorkspaceRoot: root }), @@ -3299,6 +3303,40 @@ const makeWsRpcLayer = ( .pipe(Effect.map((cancelled) => ({ cancelled }))), { "rpc.aggregate": "vcs" }, ), + [WS_METHODS.subscribeSandboxes]: () => + observeRpcStream(WS_METHODS.subscribeSandboxes, sandboxes.stream, { + "rpc.aggregate": "vcs", + }), + [WS_METHODS.sandboxStop]: (input) => + observeRpcEffect( + WS_METHODS.sandboxStop, + sandboxes.stop(input.worktreePath).pipe( + Effect.mapError( + (error) => + new SandboxRequestError({ + operation: "stop", + worktreePath: input.worktreePath, + detail: error.detail, + }), + ), + ), + { "rpc.aggregate": "vcs" }, + ), + [WS_METHODS.sandboxRemove]: (input) => + observeRpcEffect( + WS_METHODS.sandboxRemove, + sandboxes.remove(input.worktreePath).pipe( + Effect.mapError( + (error) => + new SandboxRequestError({ + operation: "remove", + worktreePath: input.worktreePath, + detail: error.detail, + }), + ), + ), + { "rpc.aggregate": "vcs" }, + ), [WS_METHODS.vcsRefreshStatus]: (input) => observeRpcEffect( WS_METHODS.vcsRefreshStatus, diff --git a/apps/web/src/components/BranchToolbar.logic.test.ts b/apps/web/src/components/BranchToolbar.logic.test.ts index 4de529a3d558a..6bbc0003f2678 100644 --- a/apps/web/src/components/BranchToolbar.logic.test.ts +++ b/apps/web/src/components/BranchToolbar.logic.test.ts @@ -15,6 +15,7 @@ import { resolveLockedWorkspaceLabel, resolveWorkspaceDisplayName, resolveLocalCheckoutBranchMismatch, + resolveSupportedEnvMode, resolvePreviousWorktreeLabel, resolvePreviousWorktreeSeed, sanitizeNewRefName, @@ -141,6 +142,31 @@ describe("resolveDraftEnvModeAfterBranchChange", () => { }), ).toBe("worktree"); }); + + it("keeps new-sandbox mode when selecting a base ref, and drops it for an existing worktree", () => { + expect( + resolveDraftEnvModeAfterBranchChange({ + nextWorktreePath: null, + currentWorktreePath: null, + effectiveEnvMode: "sandbox", + }), + ).toBe("sandbox"); + expect( + resolveDraftEnvModeAfterBranchChange({ + nextWorktreePath: "/repo/.t3/worktrees/feature-a", + currentWorktreePath: null, + effectiveEnvMode: "sandbox", + }), + ).toBe("worktree"); + }); +}); + +describe("resolveSupportedEnvMode", () => { + it("falls back to a plain worktree when the server cannot run sandboxes", () => { + expect(resolveSupportedEnvMode("sandbox", false)).toBe("worktree"); + expect(resolveSupportedEnvMode("sandbox", true)).toBe("sandbox"); + expect(resolveSupportedEnvMode("local", false)).toBe("local"); + }); }); describe("resolveBranchToolbarValue", () => { @@ -539,6 +565,7 @@ describe("resolveEnvModeLabel", () => { it("uses explicit workspace labels", () => { expect(resolveEnvModeLabel("local")).toBe("Current checkout"); expect(resolveEnvModeLabel("worktree")).toBe("New worktree"); + expect(resolveEnvModeLabel("sandbox")).toBe("New sandbox"); }); }); diff --git a/apps/web/src/components/BranchToolbar.logic.ts b/apps/web/src/components/BranchToolbar.logic.ts index cfa62ad7fe925..542d5bf1cd89a 100644 --- a/apps/web/src/components/BranchToolbar.logic.ts +++ b/apps/web/src/components/BranchToolbar.logic.ts @@ -22,9 +22,17 @@ export interface EnvironmentOption { machine: EnvironmentMachineKind; } -export const EnvMode = Schema.Literals(["local", "worktree"]); +// "worktree" and "sandbox" both start the thread in a new worktree. A sandbox +// also runs that worktree's agent, terminals, and setup script in Docker. +export const EnvMode = Schema.Literals(["local", "worktree", "sandbox"]); export type EnvMode = typeof EnvMode.Type; +// Sandboxes need server support. A draft that asked for one on a server +// without it (for example after a machine switch) gets a plain worktree. +export function resolveSupportedEnvMode(mode: EnvMode, sandboxesAvailable: boolean): EnvMode { + return mode === "sandbox" && !sandboxesAvailable ? "worktree" : mode; +} + const GENERIC_LOCAL_ENVIRONMENT_LABELS = new Set(["local", "local environment"]); function normalizeDisplayLabel(value: string | null | undefined): string | null { @@ -94,7 +102,14 @@ export function resolveContextStripLabelsCompact(input: { } export function resolveEnvModeLabel(mode: EnvMode): string { - return mode === "worktree" ? "New worktree" : "Current checkout"; + switch (mode) { + case "local": + return "Current checkout"; + case "worktree": + return "New worktree"; + case "sandbox": + return "New sandbox"; + } } export const WORKTREE_SUBMODULES_LABELS: Record = { @@ -114,7 +129,7 @@ export function resolveLockedWorkspaceLabel( effectiveEnvMode: EnvMode, ): string { if (activeWorktreePath) return "Worktree"; - return effectiveEnvMode === "worktree" ? resolveEnvModeLabel("worktree") : "Local checkout"; + return effectiveEnvMode === "local" ? "Local checkout" : resolveEnvModeLabel(effectiveEnvMode); } export function resolveWorkspaceDisplayName(path: string | null): string | null { @@ -186,7 +201,7 @@ export function resolveEffectiveEnvMode(input: { if (activeWorktreePath) { return "local"; } - return draftThreadEnvMode === "worktree" ? "worktree" : "local"; + return draftThreadEnvMode ?? "local"; } return activeWorktreePath || preparingWorktree ? "worktree" : "local"; } @@ -200,8 +215,8 @@ export function resolveDraftEnvModeAfterBranchChange(input: { if (nextWorktreePath) { return "worktree"; } - if (effectiveEnvMode === "worktree" && !currentWorktreePath) { - return "worktree"; + if (effectiveEnvMode !== "local" && !currentWorktreePath) { + return effectiveEnvMode; } return "local"; } @@ -213,7 +228,7 @@ export function resolveBranchToolbarValue(input: { currentGitBranch: string | null; }): string | null { const { envMode, activeWorktreePath, activeThreadBranch, currentGitBranch } = input; - if (envMode === "worktree" && !activeWorktreePath) { + if (envMode !== "local" && !activeWorktreePath) { return activeThreadBranch ?? currentGitBranch; } return currentGitBranch ?? activeThreadBranch; @@ -236,7 +251,7 @@ export function resolveBranchTriggerLabel(input: { if (!resolvedActiveBranch) { return "Select ref"; } - if (effectiveEnvMode === "worktree" && !activeWorktreePath) { + if (effectiveEnvMode !== "local" && !activeWorktreePath) { const baseRef = startFromOrigin && resolvedActiveBranchIsRemote === false ? `origin/${resolvedActiveBranch}` diff --git a/apps/web/src/components/BranchToolbar.tsx b/apps/web/src/components/BranchToolbar.tsx index 7e7d4a71d7d65..7a73cf465a356 100644 --- a/apps/web/src/components/BranchToolbar.tsx +++ b/apps/web/src/components/BranchToolbar.tsx @@ -2,6 +2,7 @@ import { ComposerContextLabel } from "./ComposerContextLabel"; import { scopeProjectRef, scopeThreadRef } from "@t3tools/client-runtime/environment"; import type { EnvironmentId, ThreadId } from "@t3tools/contracts"; import { + BoxIcon, ChevronDownIcon, FolderGit2Icon, FolderGitIcon, @@ -78,6 +79,8 @@ interface BranchToolbarProps { onEnvModeChange: (mode: EnvMode) => void; /** The thread's env mode as ChatView resolves it. */ envMode: EnvMode; + /** The thread's server can run new worktrees in Docker sandboxes. */ + sandboxesAvailable?: boolean; activeThreadBranchOverride?: string | null; onActiveThreadBranchOverrideChange?: (branch: string | null) => void; startFromOrigin: boolean; @@ -107,6 +110,7 @@ interface MobileRunContextSelectorProps { effectiveEnvMode: EnvMode; activeWorktreePath: string | null; onEnvModeChange: (mode: EnvMode) => void; + sandboxesAvailable: boolean; previousWorktreeLabel: string | null; previousWorktreeBranch: string | null; onUsePreviousWorktree: () => void; @@ -126,6 +130,7 @@ const MobileRunContextSelector = memo(function MobileRunContextSelector({ effectiveEnvMode, activeWorktreePath, onEnvModeChange, + sandboxesAvailable, previousWorktreeLabel, previousWorktreeBranch, onUsePreviousWorktree, @@ -136,18 +141,20 @@ const MobileRunContextSelector = memo(function MobileRunContextSelector({ [availableEnvironments, environmentId], ); const WorkspaceIcon = - effectiveEnvMode === "worktree" - ? FolderGit2Icon - : activeWorktreePath - ? FolderGitIcon - : FolderIcon; + effectiveEnvMode === "sandbox" + ? BoxIcon + : effectiveEnvMode === "worktree" + ? FolderGit2Icon + : activeWorktreePath + ? FolderGitIcon + : FolderIcon; const workspaceLabel = forceNewWorktree ? resolveEnvModeLabel("worktree") : envModeLocked ? resolveLockedWorkspaceLabel(activeWorktreePath, effectiveEnvMode) - : effectiveEnvMode === "worktree" - ? resolveEnvModeLabel("worktree") - : resolveCurrentWorkspaceLabel(activeWorktreePath); + : effectiveEnvMode === "local" + ? resolveCurrentWorkspaceLabel(activeWorktreePath) + : resolveEnvModeLabel(effectiveEnvMode); const isLocked = envLocked || envModeLocked; const workspaceIcon = ( @@ -295,6 +302,14 @@ const MobileRunContextSelector = memo(function MobileRunContextSelector({ {resolveEnvModeLabel("worktree")} + {sandboxesAvailable ? ( + + + + {resolveEnvModeLabel("sandbox")} + + + ) : null} {previousWorktreeLabel ? ( @@ -509,6 +524,7 @@ export const BranchToolbar = memo(function BranchToolbar({ draftId, onEnvModeChange, envMode, + sandboxesAvailable = false, activeThreadBranchOverride, onActiveThreadBranchOverrideChange, startFromOrigin, @@ -625,6 +641,7 @@ export const BranchToolbar = memo(function BranchToolbar({ activeWorktreePath={activeWorktreePath} workspaceRoot={activeProject.workspaceRoot} onEnvModeChange={onEnvModeChange} + sandboxesAvailable={sandboxesAvailable} /> ) : null} {panelSection !== "workspace" ? ( @@ -676,6 +693,7 @@ export const BranchToolbar = memo(function BranchToolbar({ effectiveEnvMode={effectiveEnvMode} activeWorktreePath={activeWorktreePath} onEnvModeChange={onEnvModeChange} + sandboxesAvailable={sandboxesAvailable} previousWorktreeLabel={previousWorktreeLabel} previousWorktreeBranch={previousWorktreeSeed?.branch ?? null} onUsePreviousWorktree={onUsePreviousWorktree} @@ -716,6 +734,7 @@ export const BranchToolbar = memo(function BranchToolbar({ effectiveEnvMode={effectiveEnvMode} activeWorktreePath={activeWorktreePath} onEnvModeChange={onEnvModeChange} + sandboxesAvailable={sandboxesAvailable} previousWorktreeLabel={previousWorktreeLabel} previousWorktreeBranch={previousWorktreeSeed?.branch ?? null} onUsePreviousWorktree={onUsePreviousWorktree} diff --git a/apps/web/src/components/BranchToolbarBranchSelector.tsx b/apps/web/src/components/BranchToolbarBranchSelector.tsx index 12952829566e1..9060fff189f92 100644 --- a/apps/web/src/components/BranchToolbarBranchSelector.tsx +++ b/apps/web/src/components/BranchToolbarBranchSelector.tsx @@ -52,6 +52,7 @@ import { resolveEffectiveEnvMode, sanitizeNewRefName, shouldIncludeBranchPickerItem, + type EnvMode, } from "./BranchToolbar.logic"; import { ThreadPullRequestBadgeControl, @@ -79,7 +80,7 @@ interface BranchToolbarBranchSelectorProps { threadId: ThreadId; draftId?: DraftId; envLocked: boolean; - effectiveEnvModeOverride?: "local" | "worktree"; + effectiveEnvModeOverride?: EnvMode; activeThreadBranchOverride?: string | null; onActiveThreadBranchOverrideChange?: (refName: string | null) => void; startFromOrigin: boolean; @@ -270,8 +271,7 @@ export function BranchToolbarBranchSelector({ ); const normalizedDeferredBranchQuery = deferredTrimmedBranchQuery.toLowerCase(); const prReference = parsePullRequestReference(trimmedBranchQuery); - const isSelectingWorktreeBase = - effectiveEnvMode === "worktree" && !envLocked && !activeWorktreePath; + const isSelectingWorktreeBase = effectiveEnvMode !== "local" && !envLocked && !activeWorktreePath; const checkoutPullRequestItemValue = prReference && onCheckoutPullRequestRequest ? `__checkout_pull_request__:${prReference}` : null; const canCreateBranch = !isSelectingWorktreeBase && trimmedBranchQuery.length > 0; @@ -508,7 +508,7 @@ export function BranchToolbarBranchSelector({ useEffect(() => { if ( - effectiveEnvMode !== "worktree" || + effectiveEnvMode === "local" || activeWorktreePath || activeThreadBranch || !worktreeBaseBranchCandidate diff --git a/apps/web/src/components/BranchToolbarEnvModeSelector.tsx b/apps/web/src/components/BranchToolbarEnvModeSelector.tsx index 3afa31e2acee1..5c088b6cdf706 100644 --- a/apps/web/src/components/BranchToolbarEnvModeSelector.tsx +++ b/apps/web/src/components/BranchToolbarEnvModeSelector.tsx @@ -1,6 +1,6 @@ import { ThreadDetailsSelectControl } from "./chat/ThreadDetailsControl"; import { ComposerContextLabel } from "./ComposerContextLabel"; -import { FolderGit2Icon, FolderGitIcon, FolderIcon } from "lucide-react"; +import { BoxIcon, FolderGit2Icon, FolderGitIcon, FolderIcon } from "lucide-react"; import { memo, useMemo, type MouseEvent as ReactMouseEvent } from "react"; import { writeTextToClipboard } from "../hooks/useCopyToClipboard"; import { readLocalApi } from "../localApi"; @@ -39,6 +39,8 @@ interface BranchToolbarEnvModeSelectorProps { activeWorktreePath: string | null; workspaceRoot?: string | null; onEnvModeChange: (mode: EnvMode) => void; + /** The server can run new worktrees in Docker sandboxes. */ + sandboxesAvailable?: boolean; displayMode?: "toolbar" | "panel"; previousWorktreeLabel?: string | null; previousWorktreeBranch?: string | null; @@ -52,6 +54,7 @@ export const BranchToolbarEnvModeSelector = memo(function BranchToolbarEnvModeSe activeWorktreePath, workspaceRoot = null, onEnvModeChange, + sandboxesAvailable = false, displayMode = "toolbar", previousWorktreeLabel, previousWorktreeBranch = null, @@ -63,9 +66,10 @@ export const BranchToolbarEnvModeSelector = memo(function BranchToolbarEnvModeSe const workspaceKind = activeWorktreePath ? "Worktree" : null; const lockedWorkspaceKind = forceNewWorktree ? "Worktree" : workspaceKind; const selectWorkspaceKind = - effectiveEnvMode === "worktree" && !activeWorktreePath ? "Create" : workspaceKind; + effectiveEnvMode !== "local" && !activeWorktreePath ? "Create" : workspaceKind; const composerFloatingLayerProps = useComposerMenuProps(); const showPreviousWorktree = Boolean(previousWorktreeLabel && onUsePreviousWorktree); + const NewWorkspaceIcon = effectiveEnvMode === "sandbox" ? BoxIcon : FolderGit2Icon; const envModeItems = useMemo( () => [ { @@ -73,11 +77,18 @@ export const BranchToolbarEnvModeSelector = memo(function BranchToolbarEnvModeSe label: workspaceDisplayName ?? resolveCurrentWorkspaceLabel(activeWorktreePath), }, { value: "worktree", label: resolveEnvModeLabel("worktree") }, + ...(sandboxesAvailable ? [{ value: "sandbox", label: resolveEnvModeLabel("sandbox") }] : []), ...(showPreviousWorktree && previousWorktreeLabel ? [{ value: PREVIOUS_WORKTREE_SELECT_VALUE, label: previousWorktreeLabel }] : []), ], - [activeWorktreePath, previousWorktreeLabel, showPreviousWorktree, workspaceDisplayName], + [ + activeWorktreePath, + previousWorktreeLabel, + sandboxesAvailable, + showPreviousWorktree, + workspaceDisplayName, + ], ); const handleWorkspaceContextMenu = (event: ReactMouseEvent) => { @@ -136,8 +147,8 @@ export const BranchToolbarEnvModeSelector = memo(function BranchToolbarEnvModeSe - ) : effectiveEnvMode === "worktree" ? ( - ) : ( @@ -198,8 +209,8 @@ export const BranchToolbarEnvModeSelector = memo(function BranchToolbarEnvModeSe /> } > - {effectiveEnvMode === "worktree" ? ( - ) : activeWorktreePath ? ( @@ -222,9 +233,9 @@ export const BranchToolbarEnvModeSelector = memo(function BranchToolbarEnvModeSe {workspacePath ?? - (effectiveEnvMode === "worktree" - ? resolveEnvModeLabel("worktree") - : resolveCurrentWorkspaceLabel(activeWorktreePath))} + (effectiveEnvMode === "local" + ? resolveCurrentWorkspaceLabel(activeWorktreePath) + : resolveEnvModeLabel(effectiveEnvMode))} + {sandboxesAvailable ? ( + + + + {resolveEnvModeLabel("sandbox")} + + + ) : null} {showPreviousWorktree && previousWorktreeLabel ? ( diff --git a/apps/web/src/components/ChatView.logic.ts b/apps/web/src/components/ChatView.logic.ts index 3323a8f3e0b98..c7408df2a1028 100644 --- a/apps/web/src/components/ChatView.logic.ts +++ b/apps/web/src/components/ChatView.logic.ts @@ -848,7 +848,7 @@ export function resolveBackgroundDraftWorkspaceOptions(input: { envMode: input.envMode, branch: input.branch, worktreePath: null, - startFromOrigin: input.envMode === "worktree" && input.startFromOrigin, + startFromOrigin: input.envMode !== "local" && input.startFromOrigin, }; } diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx index 92400fedd9b3b..3969fb4e000c9 100644 --- a/apps/web/src/components/ChatView.tsx +++ b/apps/web/src/components/ChatView.tsx @@ -437,7 +437,9 @@ import { NoActiveThreadState } from "./NoActiveThreadState"; import { type EnvironmentOption, resolveEffectiveEnvMode, + resolveEnvModeLabel, resolveLocalCheckoutBranchMismatch, + resolveSupportedEnvMode, shouldShowComposerContextStrip, shouldShowEnvironmentIndicator, } from "./BranchToolbar.logic"; @@ -6445,9 +6447,13 @@ export default function ChatView(props: ChatViewProps) { activeThread.worktreePath === null && !envLocked, ); - const envMode: DraftThreadEnvMode = canOverrideServerThreadEnvMode - ? (pendingServerThreadEnvMode ?? draftThread?.envMode ?? derivedEnvMode) - : derivedEnvMode; + const sandboxesAvailable = serverConfig?.sandboxes === true; + const envMode: DraftThreadEnvMode = resolveSupportedEnvMode( + canOverrideServerThreadEnvMode + ? (pendingServerThreadEnvMode ?? draftThread?.envMode ?? derivedEnvMode) + : derivedEnvMode, + sandboxesAvailable, + ); const activeThreadBranch = canOverrideServerThreadEnvMode && pendingServerThreadBranch !== undefined ? pendingServerThreadBranch @@ -8571,16 +8577,19 @@ export default function ChatView(props: ChatViewProps) { const threadIdForSend = activeThread.id; const isFirstMessage = !isServerThread || activeMessageCount === 0; const baseBranchForWorktree = - isFirstMessage && sendEnvMode === "worktree" && !activeThread.worktreePath + isFirstMessage && sendEnvMode !== "local" && !activeThread.worktreePath ? activeThreadBranch : null; - // In worktree mode, require an explicit base branch so we don't silently + // In worktree or sandbox mode, require an explicit base branch so we don't silently // fall back to local execution when branch selection is missing. const shouldCreateWorktree = - isFirstMessage && sendEnvMode === "worktree" && !activeThread.worktreePath; + isFirstMessage && sendEnvMode !== "local" && !activeThread.worktreePath; if (shouldCreateWorktree && !activeThreadBranch) { - setThreadError(threadIdForSend, "Select a base branch before sending in New worktree mode."); + setThreadError( + threadIdForSend, + `Select a base branch before sending in ${resolveEnvModeLabel(sendEnvMode)} mode.`, + ); return; } @@ -9211,6 +9220,7 @@ export default function ChatView(props: ChatViewProps) { projectCwd: activeProject.workspaceRoot, baseBranch: baseBranchForWorktree, ...(startFromOrigin ? { startFromOrigin: true } : {}), + ...(sendEnvMode === "sandbox" ? { sandbox: true } : {}), }, runSetupScript: true, } @@ -10104,7 +10114,7 @@ export default function ChatView(props: ChatViewProps) { envMode: mode, newWorktreesStartFromOrigin: activeProjectSettings.settings.newWorktreesStartFromOrigin, }), - ...(mode === "worktree" && draftThread?.worktreePath ? { worktreePath: null } : {}), + ...(mode !== "local" && draftThread?.worktreePath ? { worktreePath: null } : {}), }); } scheduleComposerFocus(); @@ -10425,6 +10435,7 @@ export default function ChatView(props: ChatViewProps) { environmentId: activeThread.environmentId, threadId: activeThread.id, ...(draftId ? { draftId } : {}), + worktreePath: activeWorktreePath, activeProjectName: activeProject?.title, activeProjectScripts: activeProject ? activeProjectScripts : undefined, preferredScriptId: activeProject @@ -10445,6 +10456,7 @@ export default function ChatView(props: ChatViewProps) { onEnvironmentChange, onEnvModeChange, envMode, + sandboxesAvailable, ...(canOverrideServerThreadEnvMode ? { activeThreadBranchOverride: activeThreadBranch, @@ -11068,6 +11080,7 @@ export default function ChatView(props: ChatViewProps) { startFromOrigin={startFromOrigin} onStartFromOriginChange={onStartFromOriginChange} envMode={envMode} + sandboxesAvailable={sandboxesAvailable} {...(canOverrideServerThreadEnvMode ? { activeThreadBranchOverride: activeThreadBranch, diff --git a/apps/web/src/components/GitActionsControl.tsx b/apps/web/src/components/GitActionsControl.tsx index e6635d8921657..6d0e985440e50 100644 --- a/apps/web/src/components/GitActionsControl.tsx +++ b/apps/web/src/components/GitActionsControl.tsx @@ -1209,8 +1209,8 @@ export default function GitActionsControl({ ); const isSelectingWorktreeBase = !activeServerThread && - activeDraftThread?.envMode === "worktree" && - activeDraftThread.worktreePath === null; + activeDraftThread?.worktreePath === null && + activeDraftThread.envMode !== "local"; useEffect(() => { if (isGitActionRunning || isSelectingWorktreeBase || activeServerThread) { diff --git a/apps/web/src/components/chat/ThreadDetailsPanel.test.tsx b/apps/web/src/components/chat/ThreadDetailsPanel.test.tsx index ec7d84aef49b3..8795c1ac93cbf 100644 --- a/apps/web/src/components/chat/ThreadDetailsPanel.test.tsx +++ b/apps/web/src/components/chat/ThreadDetailsPanel.test.tsx @@ -27,6 +27,9 @@ vi.mock("./ThreadAutomationsPanel", () => ({ vi.mock("./ThreadRelationshipsControl", () => ({ ThreadRelationshipsPanel: () => null, })); +vi.mock("./ThreadSandboxControl", () => ({ + ThreadSandboxControl: () => null, +})); vi.mock("./ThreadDetailsCard", () => ({ ThreadDetailsCard: ({ children }: { children: (density: "full") => React.ReactNode }) => children("full"), @@ -58,6 +61,7 @@ describe("ThreadDetailsPanel", () => { onPresentationChange: vi.fn(), environmentId, threadId: "thread:thread-details" as ThreadId, + worktreePath: null, activeProjectName: undefined, activeProjectScripts: [], preferredScriptId: null, @@ -71,6 +75,7 @@ describe("ThreadDetailsPanel", () => { onEnvironmentChange: vi.fn(), onEnvModeChange: vi.fn(), envMode: "local", + sandboxesAvailable: false, startFromOrigin: false, onStartFromOriginChange: vi.fn(), onComposerFocusRequest: vi.fn(), diff --git a/apps/web/src/components/chat/ThreadDetailsPanel.tsx b/apps/web/src/components/chat/ThreadDetailsPanel.tsx index 5b79f0c00f572..0126415b5c2bc 100644 --- a/apps/web/src/components/chat/ThreadDetailsPanel.tsx +++ b/apps/web/src/components/chat/ThreadDetailsPanel.tsx @@ -28,6 +28,7 @@ import { OpenInPicker } from "./OpenInPicker"; import { ThreadDetailsSection } from "./ThreadDetailsSection"; import { ThreadAutomationsPanel } from "./ThreadAutomationsPanel"; import { ThreadRelationshipsPanel } from "./ThreadRelationshipsControl"; +import { ThreadSandboxControl } from "./ThreadSandboxControl"; interface VersionMismatchIssue { readonly clientVersion: string; @@ -43,6 +44,8 @@ export interface ThreadDetailsPanelProps extends Pick< environmentId: EnvironmentId; threadId: ThreadId; draftId?: DraftId; + /** The thread's worktree, matched against the environment's sandboxes. */ + worktreePath: string | null; activeProjectName: string | undefined; activeProjectScripts: ReadonlyArray | undefined; preferredScriptId: string | null; @@ -59,6 +62,8 @@ export interface ThreadDetailsPanelProps extends Pick< onEnvModeChange: (mode: EnvMode) => void; /** The thread's env mode as ChatView resolves it. */ envMode: EnvMode; + /** The thread's server can run new worktrees in Docker sandboxes. */ + sandboxesAvailable: boolean; activeThreadBranchOverride?: string | null; onActiveThreadBranchOverrideChange?: (branch: string | null) => void; startFromOrigin: boolean; @@ -99,6 +104,7 @@ export function ThreadDetailsPanel(props: ThreadDetailsPanelProps) { startFromOrigin: props.startFromOrigin, onStartFromOriginChange: props.onStartFromOriginChange, envMode: props.envMode, + sandboxesAvailable: props.sandboxesAvailable, ...(props.activeThreadBranchOverride !== undefined ? { activeThreadBranchOverride: props.activeThreadBranchOverride } : {}), @@ -168,6 +174,14 @@ export function ThreadDetailsPanel(props: ThreadDetailsPanelProps) { ) : null} + {density !== "essential" && props.sandboxesAvailable ? ( + + ) : null} + {density !== "essential" && props.showOpenInPicker ? ( = { + starting: "Starting", + running: "Running", + stopped: "Stopped", + error: "Error", +}; + +const REMOVE_SANDBOX_CONFIRMATION = [ + "Remove the sandbox for this worktree?", + "This deletes its container, services, and machine state. The worktree files stay.", + "Later work in this worktree runs on the host.", +].join("\n"); + +/** + * Thread details row for a thread whose worktree runs in a Docker sandbox. + * Renders nothing for other threads. Mount it only for servers that can run + * sandboxes: it subscribes to the environment's sandboxes while mounted and + * the thread has a worktree. + */ +export function ThreadSandboxControl({ + environmentId, + threadId, + worktreePath, +}: { + environmentId: EnvironmentId; + threadId: ThreadId; + worktreePath: string | null; +}) { + const threadRef = useMemo( + () => scopeThreadRef(environmentId, threadId), + [environmentId, threadId], + ); + const sandboxesQuery = useEnvironmentQuery( + worktreePath !== null ? vcsEnvironment.sandboxes({ environmentId, input: {} }) : null, + ); + const sandbox = findSandboxForWorktree(sandboxesQuery.data?.sandboxes, worktreePath); + const stopSandbox = useAtomCommand(vcsEnvironment.stopSandbox, { reportFailure: false }); + const removeSandbox = useAtomCommand(vcsEnvironment.removeSandbox, { reportFailure: false }); + const openLink = useOpenLink(threadRef); + const [pending, setPending] = useState(false); + + if (!sandbox) return null; + + const runAction = async (action: "stop" | "remove") => { + if (action === "remove") { + const confirmed = await readLocalApi()?.dialogs.confirm(REMOVE_SANDBOX_CONFIRMATION, { + variant: "destructive", + }); + if (!confirmed) return; + } + setPending(true); + const command = action === "stop" ? stopSandbox : removeSandbox; + const result = await command({ + environmentId, + input: { worktreePath: sandbox.worktreePath }, + }); + setPending(false); + if (result._tag === "Success") return; + const error = squashAtomCommandFailure(result); + toastManager.add( + stackedThreadToast({ + type: "error", + title: action === "stop" ? "Could not stop sandbox" : "Could not remove sandbox", + description: error instanceof Error ? error.message : "An error occurred.", + }), + ); + }; + + const openPort = (port: SandboxPort) => { + // The forwarded port listens on the server's loopback; remote clients need + // the environment's own route to it. + const url = resolveDiscoveredServerUrl(environmentId, `http://127.0.0.1:${port.hostPort}`); + void openLink(url).catch((error: unknown) => { + toastManager.add( + stackedThreadToast({ + type: "error", + title: "Could not open port", + description: error instanceof Error ? error.message : "An error occurred.", + }), + ); + }); + }; + + return ( + + }> + + Sandbox + {sandbox.status !== "running" ? ( + + {SANDBOX_STATUS_LABELS[sandbox.status]} + + ) : null} + + + + {SANDBOX_STATUS_LABELS[sandbox.status]} + {sandbox.status === "error" && sandbox.error ? ( +

{sandbox.error}

+ ) : null} +
+ {sandbox.ports.length > 0 ? ( + + Ports + {sandbox.ports.map((port) => ( + openPort(port)}> + + :{port.containerPort} → 127.0.0.1:{port.hostPort} + + + ))} + + ) : null} + + void runAction("stop")} + > + + Stop sandbox + + void runAction("remove")}> + + Remove sandbox + +
+
+ ); +} diff --git a/apps/web/src/components/chat/WorktreeSetupCard.tsx b/apps/web/src/components/chat/WorktreeSetupCard.tsx index 0d0a0bc1b415b..ad4119f24b478 100644 --- a/apps/web/src/components/chat/WorktreeSetupCard.tsx +++ b/apps/web/src/components/chat/WorktreeSetupCard.tsx @@ -34,6 +34,21 @@ interface WorktreeSetupCardProps { onOpenTerminal: (() => void) | null; } +/** + * Stages that stream command output: the sandbox image build and the setup + * script. The tail box is part of the row's footprint while the stage runs + * (and after it failed, so the last lines explain the failure). It mounts + * with the first output line at its full fixed height, so the card grows + * once instead of with each line. A stage that ends before printing + * anything never flashes an empty box. + */ +function showsStageTail(stage: WorktreeSetupStage): boolean { + return ( + (stage.id === "sandbox" || stage.id === "setup-script") && + (stage.status === "failed" || (stage.status === "running" && stage.tail.length > 0)) + ); +} + function stageElapsedMs(stage: WorktreeSetupStage, nowMs: number): number | null { if (!stage.startedAt) return null; const start = Date.parse(stage.startedAt); @@ -361,15 +376,6 @@ export function WorktreeSetupCard({ // that slot when the agent takes over). The card only brings its own // header for a failed or cancelled setup that has no working row above it. const showHeader = !embedded && !running && snapshot.phase !== "done"; - // The tail box is part of the script row's footprint while the script runs - // (and after it failed, so the last lines explain the failure). It mounts - // with the first output line at its full fixed height, so the card grows - // once instead of with each line. A script that ends before printing - // anything never flashes an empty box. - const showTail = - setupStage !== undefined && - (setupStage.status === "failed" || - (setupStage.status === "running" && setupStage.tail.length > 0)); return (
@@ -385,7 +391,7 @@ export function WorktreeSetupCard({ nowMs={nowMs} scriptName={snapshot.setupScript?.name ?? null} /> - {stage.id === "setup-script" && showTail ? ( + {showsStageTail(stage) ? ( ) : null} diff --git a/apps/web/src/composerDraftStore.ts b/apps/web/src/composerDraftStore.ts index f3ad5f9aecf99..e61138ec4b803 100644 --- a/apps/web/src/composerDraftStore.ts +++ b/apps/web/src/composerDraftStore.ts @@ -88,7 +88,9 @@ const isPreviewAnnotationPayload = Schema.is(PreviewAnnotationPayloadSchema); export const COMPOSER_DRAFT_STORAGE_KEY = "t3code:composer-drafts:v1"; const COMPOSER_DRAFT_STORAGE_VERSION = 9; -const DraftThreadEnvModeSchema = Schema.Literals(["local", "worktree"]); +// Mirrors `EnvMode` in BranchToolbar.logic.ts. "sandbox" is a new worktree +// that runs in a Docker sandbox. +const DraftThreadEnvModeSchema = Schema.Literals(["local", "worktree", "sandbox"]); export type DraftThreadEnvMode = typeof DraftThreadEnvModeSchema.Type; export const DraftId = Schema.String.pipe(Schema.brand("DraftId")); @@ -1436,7 +1438,7 @@ function normalizeDraftThreadEnvMode( value: unknown, fallbackWorktreePath: string | null, ): DraftThreadEnvMode { - if (value === "local" || value === "worktree") { + if (value === "local" || value === "worktree" || value === "sandbox") { return value; } return fallbackWorktreePath ? "worktree" : "local"; diff --git a/apps/web/src/lib/chatThreadActions.ts b/apps/web/src/lib/chatThreadActions.ts index c14a26d03d1c0..765cd2317072e 100644 --- a/apps/web/src/lib/chatThreadActions.ts +++ b/apps/web/src/lib/chatThreadActions.ts @@ -41,7 +41,7 @@ export function resolveNewDraftStartFromOrigin(input: { envMode: DraftThreadEnvMode; newWorktreesStartFromOrigin: boolean; }): boolean { - return input.envMode === "worktree" && input.newWorktreesStartFromOrigin; + return input.envMode !== "local" && input.newWorktreesStartFromOrigin; } export function resolveNewThreadModelSelectionOverride(input: { diff --git a/docs/README.md b/docs/README.md index dd59f4417bbb4..003ddb1c78f2c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,6 +8,7 @@ - [Permission modes](./user/permission-modes.md) - [Terminal history](./user/terminal.md) - [Source control](./user/source-control.md) +- [Sandboxes](./user/sandboxes.md) - [Project settings](./user/project-settings.md) - [Appearance and themes](./user/appearance.md) - [Keyboard shortcuts](./user/keybindings.md) @@ -36,6 +37,7 @@ source alone does not explain. Most code changes do not need an internal documen - [Glossary](./internals/glossary.md) - [Connection runtime](./internals/connection-runtime.md) - [Providers](./internals/providers.md) +- [Sandboxes](./internals/sandboxes.md) - [Pull request file revisions](./internals/pull-request-file-revisions.md) - [Model classification](./internals/model-manifest.md) - [Remote environments](./internals/remote.md) diff --git a/docs/internals/sandboxes.md b/docs/internals/sandboxes.md new file mode 100644 index 0000000000000..74e2af25d2214 --- /dev/null +++ b/docs/internals/sandboxes.md @@ -0,0 +1,63 @@ +# Sandboxes + +A sandbox is one long-running Docker container per worktree. See +[`SandboxService`](../../apps/server/src/sandbox/SandboxService.ts) and the +[user guide](../user/sandboxes.md). + +## The provider CLI runs inside + +The point of a sandbox is separate ports and services, which only works if the commands an agent +runs share the container's network. Providers have no reliable hook to redirect their shell +commands, so the whole CLI runs in the container: Claude through the SDK's +`spawnClaudeCodeProcess`, Codex by wrapping the app-server command, and terminals by opening +`bash` with `docker exec -it`. The setup script runs in a terminal, so it follows. Other adapters +fail in `ProviderSessionManager` rather than run on the host unnoticed. + +A process runs where it was opened, so a shared provider session (Codex serves every thread of an +instance from one app-server) is scoped per sandbox. The Orchestrator picks the session id from the +thread's current worktree each time a run starts, because a launch records one before the +worktree and sandbox exist. When a sandbox stops or is removed, `ProviderSessionManager` releases +the sessions that ran in it, so the next turn opens a fresh one and restarts the container. + +The image installs Claude Code and Codex at the host's versions. Host binaries can be macOS +builds, so they are never mounted. + +## Same paths inside and out + +The worktree, the repository's git dir, `~/.claude`, `~/.codex`, `~/.gitconfig`, the attachments +folder, and the project checkout (read-only, for setup scripts) mount at their host paths, and the image user has the host's uid, gid, and home +path. T3 keeps reading worktree files, Claude session files, and git state on the host without any +path translation. `~/.claude.json` is copied in, not mounted, because Claude replaces it by rename, +which fails on a bind-mounted file. + +## One relay, no published ports + +Container IPs are not routable on Docker Desktop, and a server bound to `127.0.0.1` is not +reachable from a Linux bridge network. [`SandboxTunnel`](../../apps/server/src/sandbox/SandboxTunnel.ts) +avoids both: a Node relay runs under `docker exec -i` and multiplexes TCP over its stdio. It +forwards every port that starts listening in the container to a host loopback port, and listens +on T3's own port inside the container so the unchanged `127.0.0.1` MCP URL reaches the host. + +## Killing `docker exec` kills nothing + +Killing a `docker exec` client leaves its process running in the container. Every sandboxed +command starts through a launcher that records its PID, and each spawn site calls `release` when +its process exits or is killed. Each exec leads its own session, so `release` kills the whole +session, including children whose parent already exited. The first use after a server restart +kills everything an earlier server process left behind. + +## Codex's own sandbox is off + +Codex's bubblewrap sandbox cannot create namespaces in an unprivileged container. Sandboxed turns +send `dangerFullAccess` and keep the runtime mode's approval policy. + +## Fail closed + +A worktree is registered and saved as sandboxed before the image build, and stays registered when +provisioning fails, so a terminal or turn waits or fails instead of running on the host. A +sandboxed worktree whose container is missing gets a new one. Containers carry labels with their +worktree, CLI versions, and an owner hash of the server's state directory, so a lost or unreadable +list is rebuilt from the containers this server owns. Each sandboxed worktree also keeps its record +in `t3code-sandbox.json` in its git admin folder, so a lookup can rebuild the sandbox from the +worktree itself even when both the list and its container are gone. Entries for deleted worktrees +are dropped at startup. diff --git a/docs/user/sandboxes.md b/docs/user/sandboxes.md new file mode 100644 index 0000000000000..8b349826d6164 --- /dev/null +++ b/docs/user/sandboxes.md @@ -0,0 +1,45 @@ +# Sandboxes + +A sandbox is a new worktree that runs in its own Docker container. The agent, the thread's +terminals, and the project's setup script all run inside it. Each sandbox has its own ports, +services, and installed tools, so two threads can both run an app on port 3000, or use different +database data and migrations, at the same time. + +The worktree's files stay on your machine. Diffs, checkpoints, source control, and your editor +work as they do for any worktree. + +## Start a sandbox + +Choose **New sandbox** where you would choose **New worktree** for a new thread. The first sandbox +builds an image, which takes a few minutes. Later sandboxes start in seconds. Agents can also start +one with `sandbox: true` in a worktree launch. + +You need Docker on a Linux or macOS machine running T3 Code. Claude and Codex can run in a sandbox. +Other providers report an error in a sandboxed thread. + +## What is inside + +The image is Debian with Node 24, git, and the same Claude Code and Codex versions as your machine. +Your Claude and Codex settings and logins are shared with the sandbox, along with your git +identity. The agent can use `sudo` to install anything else, for example +`sudo apt-get install postgresql`. Services and data outside the worktree stay inside that sandbox. + +On macOS, Claude keeps its login in the Keychain, which a container cannot read. Run +`claude setup-token` and add the token as `CLAUDE_CODE_OAUTH_TOKEN` to the Claude provider's +environment variables. + +In a sandbox, Codex does not use its own command sandbox; the container is the boundary. +Approval prompts still follow the thread's permission mode. + +## Previews + +When an app listens on a port inside the sandbox, T3 Code forwards it to a port on your machine +and lists it in the preview panel as `sandbox :3000`. The forwarded port stays the same across +restarts when it is free. + +## Stop or remove + +A sandbox keeps running until you stop it. A stopped sandbox starts again the next time the agent +or a terminal needs it. Removing a sandbox deletes the container and everything in it outside the +worktree; later work in that worktree runs on your machine. Deleting the worktree removes its +sandbox. diff --git a/packages/client-runtime/src/operations/commands.ts b/packages/client-runtime/src/operations/commands.ts index c0cb8e67504c9..c64f1cbb402fa 100644 --- a/packages/client-runtime/src/operations/commands.ts +++ b/packages/client-runtime/src/operations/commands.ts @@ -158,6 +158,8 @@ interface StartThreadBootstrap { readonly baseBranch: string; readonly branch?: string; readonly startFromOrigin?: boolean; + /** Run the new worktree in a Docker sandbox. */ + readonly sandbox?: boolean; }; readonly runSetupScript?: boolean; } @@ -647,6 +649,7 @@ export const startThreadTurn = Effect.fn("EnvironmentCommands.startThreadTurn")( ...(prepareWorktree.startFromOrigin === undefined ? {} : { startFromOrigin: prepareWorktree.startFromOrigin }), + ...(prepareWorktree.sandbox === true ? { sandbox: true } : {}), } : bootstrap?.worktreePath ? { diff --git a/packages/client-runtime/src/rpc/client.ts b/packages/client-runtime/src/rpc/client.ts index 4ce45cf3ff1b9..f42ca6a1a6721 100644 --- a/packages/client-runtime/src/rpc/client.ts +++ b/packages/client-runtime/src/rpc/client.ts @@ -64,6 +64,7 @@ export type EnvironmentSubscriptionRpcTag = | typeof WS_METHODS.previewAutomationConnect | typeof WS_METHODS.subscribeVcsStatus | typeof WS_METHODS.subscribeWorktreeSetup + | typeof WS_METHODS.subscribeSandboxes | typeof WS_METHODS.subscribeProjectClones | typeof WS_METHODS.terminalAttach; diff --git a/packages/client-runtime/src/state/vcs.ts b/packages/client-runtime/src/state/vcs.ts index c5dee0f752804..eb4176bc00b1a 100644 --- a/packages/client-runtime/src/state/vcs.ts +++ b/packages/client-runtime/src/state/vcs.ts @@ -1,5 +1,6 @@ import { type EnvironmentId, + type SandboxSummary, type VcsListRefsInput, type VcsListRefsResult, type VcsStatusResult, @@ -327,6 +328,21 @@ export function createVcsEnvironmentAtoms( label: "environment-data:vcs:cancel-worktree-setup", tag: WS_METHODS.worktreeSetupCancel, }), + // Docker sandboxes on the environment. A thread is sandboxed when its + // worktree path matches one; `findSandboxForWorktree` does the lookup. + sandboxes: createEnvironmentRpcSubscriptionAtomFamily(runtime, { + label: "environment-data:vcs:sandboxes", + tag: WS_METHODS.subscribeSandboxes, + idleTtlMs: VCS_STATUS_IDLE_TTL_MS, + }), + stopSandbox: createEnvironmentRpcCommand(runtime, { + label: "environment-data:vcs:stop-sandbox", + tag: WS_METHODS.sandboxStop, + }), + removeSandbox: createEnvironmentRpcCommand(runtime, { + label: "environment-data:vcs:remove-sandbox", + tag: WS_METHODS.sandboxRemove, + }), removeWorktree: createEnvironmentRpcCommand(runtime, { label: "environment-data:vcs:remove-worktree", tag: WS_METHODS.vcsRemoveWorktree, @@ -358,6 +374,15 @@ export function createVcsEnvironmentAtoms( }; } +/** The sandbox that runs a thread's worktree, if any. */ +export function findSandboxForWorktree( + sandboxes: ReadonlyArray | undefined, + worktreePath: string | null | undefined, +): SandboxSummary | null { + if (!sandboxes || !worktreePath) return null; + return sandboxes.find((sandbox) => sandbox.worktreePath === worktreePath) ?? null; +} + export * from "./gitActions.ts"; export * from "./vcsAction.ts"; export * from "./vcsRef.ts"; diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.ts index 8690bb1b2390b..188e18f98b751 100644 --- a/packages/contracts/src/index.ts +++ b/packages/contracts/src/index.ts @@ -60,3 +60,4 @@ export * from "./worktreeMcp.ts"; export * from "./resourceTelemetry.ts"; export * from "./rpc.ts"; export * from "./worktreeSetup.ts"; +export * from "./sandbox.ts"; diff --git a/packages/contracts/src/orchestrationV2.ts b/packages/contracts/src/orchestrationV2.ts index 6004ab119917d..a71aa87a1f2da 100644 --- a/packages/contracts/src/orchestrationV2.ts +++ b/packages/contracts/src/orchestrationV2.ts @@ -2976,6 +2976,8 @@ export const OrchestrationV2ThreadLaunchWorkspaceStrategy = Schema.Union([ baseRef: TrimmedNonEmptyString, branch: Schema.optional(TrimmedNonEmptyString), startFromOrigin: Schema.optional(Schema.Boolean), + /** Run the new worktree's agents, terminals, and setup script in a Docker sandbox. */ + sandbox: Schema.optional(Schema.Boolean), }), ]); export type OrchestrationV2ThreadLaunchWorkspaceStrategy = diff --git a/packages/contracts/src/rpc.ts b/packages/contracts/src/rpc.ts index ed6df13a69471..e52572625356f 100644 --- a/packages/contracts/src/rpc.ts +++ b/packages/contracts/src/rpc.ts @@ -98,6 +98,7 @@ import { WorktreeSetupStreamEvent, WorktreeSetupSubscribeInput, } from "./worktreeSetup.ts"; +import { SandboxListStreamEvent, SandboxRequestError, SandboxWorktreeInput } from "./sandbox.ts"; import { GitActionProgressEvent, VcsSwitchRefInput, @@ -522,6 +523,9 @@ export const WS_METHODS = { subscribeVcsStatus: "subscribeVcsStatus", subscribeWorktreeSetup: "subscribeWorktreeSetup", worktreeSetupCancel: "worktreeSetup.cancel", + subscribeSandboxes: "subscribeSandboxes", + sandboxStop: "sandbox.stop", + sandboxRemove: "sandbox.remove", subscribeTerminalEvents: "subscribeTerminalEvents", subscribeTerminalMetadata: "subscribeTerminalMetadata", subscribePreviewEvents: "subscribePreviewEvents", @@ -1254,6 +1258,25 @@ const WsSubscribeWorktreeSetupRpc = Rpc.make(WS_METHODS.subscribeWorktreeSetup, stream: true, }); +const WsSubscribeSandboxesRpc = Rpc.make(WS_METHODS.subscribeSandboxes, { + payload: Schema.Struct({}), + success: SandboxListStreamEvent, + error: EnvironmentAuthorizationError, + stream: true, +}); + +const WsSandboxStopRpc = Rpc.make(WS_METHODS.sandboxStop, { + payload: SandboxWorktreeInput, + success: Schema.Void, + error: Schema.Union([SandboxRequestError, EnvironmentAuthorizationError]), +}); + +const WsSandboxRemoveRpc = Rpc.make(WS_METHODS.sandboxRemove, { + payload: SandboxWorktreeInput, + success: Schema.Void, + error: Schema.Union([SandboxRequestError, EnvironmentAuthorizationError]), +}); + const WsWorktreeSetupCancelRpc = Rpc.make(WS_METHODS.worktreeSetupCancel, { payload: WorktreeSetupCancelInput, success: WorktreeSetupCancelResult, @@ -1797,6 +1820,9 @@ export const WsRpcGroup = RpcGroup.make( WsSubscribeVcsStatusRpc, WsSubscribeWorktreeSetupRpc, WsWorktreeSetupCancelRpc, + WsSubscribeSandboxesRpc, + WsSandboxStopRpc, + WsSandboxRemoveRpc, WsVcsPullRpc, WsVcsRefreshStatusRpc, WsGitRunStackedActionRpc, diff --git a/packages/contracts/src/sandbox.ts b/packages/contracts/src/sandbox.ts new file mode 100644 index 0000000000000..f422d82ce2055 --- /dev/null +++ b/packages/contracts/src/sandbox.ts @@ -0,0 +1,56 @@ +import * as Schema from "effect/Schema"; + +import { TrimmedNonEmptyString } from "./baseSchemas.ts"; + +/** + * A Docker sandbox belongs to one worktree. The server runs that worktree's + * agents, terminals, and setup script inside the sandbox's container, so each + * sandbox has its own ports, services, and files outside the worktree. Clients + * match a thread to its sandbox by the thread's worktree path. + */ +export const SandboxStatus = Schema.Literals(["starting", "running", "stopped", "error"]); +export type SandboxStatus = typeof SandboxStatus.Type; + +const PortNumber = Schema.Int.check(Schema.isGreaterThan(0)).check(Schema.isLessThan(65536)); + +/** A port an app listens on inside the sandbox, forwarded to the server host's loopback. */ +export const SandboxPort = Schema.Struct({ + containerPort: PortNumber, + hostPort: PortNumber, +}); +export type SandboxPort = typeof SandboxPort.Type; + +export const SandboxSummary = Schema.Struct({ + worktreePath: TrimmedNonEmptyString, + containerName: TrimmedNonEmptyString, + image: TrimmedNonEmptyString, + status: SandboxStatus, + ports: Schema.Array(SandboxPort), + /** Human readable reason when status is error. */ + error: Schema.NullOr(Schema.String), +}); +export type SandboxSummary = typeof SandboxSummary.Type; + +/** The full sandbox list. Sent first, then after every change. */ +export const SandboxListStreamEvent = Schema.Struct({ + sandboxes: Schema.Array(SandboxSummary), +}); +export type SandboxListStreamEvent = typeof SandboxListStreamEvent.Type; + +export const SandboxWorktreeInput = Schema.Struct({ + worktreePath: TrimmedNonEmptyString, +}); +export type SandboxWorktreeInput = typeof SandboxWorktreeInput.Type; + +export class SandboxRequestError extends Schema.TaggedError()( + "SandboxRequestError", + { + operation: Schema.Literals(["stop", "remove"]), + worktreePath: Schema.String, + detail: Schema.String, + }, +) { + override get message(): string { + return `Could not ${this.operation} the sandbox for ${this.worktreePath}: ${this.detail}`; + } +} diff --git a/packages/contracts/src/server.ts b/packages/contracts/src/server.ts index e152a3dbf0726..d6de5185d9e32 100644 --- a/packages/contracts/src/server.ts +++ b/packages/contracts/src/server.ts @@ -629,6 +629,11 @@ export const ServerConfig = Schema.Struct({ shellRevealInFileManagerKind: Schema.optionalKey(FileManagerRevealKind), /** Whether thread subscriptions can emit an opt-in catch-up completion marker. */ threadResumeCompletionMarker: Schema.optionalKey(Schema.Boolean), + /** + * Whether this server can run new worktrees in Docker sandboxes (Linux and + * macOS hosts). Docker itself is checked when a sandbox starts. + */ + sandboxes: Schema.optionalKey(Schema.Boolean), /** * Whether thread detail reads accept a turn window (`turnLimit`/ * `beforeCursor`) and return `page` metadata. Clients must not send window diff --git a/packages/contracts/src/worktreeSetup.ts b/packages/contracts/src/worktreeSetup.ts index 203cfd6a4929b..8f1fb77889e1d 100644 --- a/packages/contracts/src/worktreeSetup.ts +++ b/packages/contracts/src/worktreeSetup.ts @@ -16,6 +16,7 @@ export const WorktreeSetupStageId = Schema.Literals([ "fetch", "checkout", "submodules", + "sandbox", "setup-script", "agent", ]); @@ -104,6 +105,7 @@ export const WORKTREE_SETUP_STAGE_ORDER: ReadonlyArray = [ "fetch", "checkout", "submodules", + "sandbox", "setup-script", "agent", ]; @@ -116,6 +118,8 @@ export function worktreeSetupStageLabel(id: WorktreeSetupStageId): string { return "Check out files"; case "submodules": return "Init submodules"; + case "sandbox": + return "Start sandbox"; case "setup-script": return "Run setup script"; case "agent":