Investigate a Junior desktop app with local execution

This is an investigation with no code change yet, and the data-retention and execution-safety questions need Legal/Security input before any build. Start with the sandbox seam in packages/junior/src/chat/sandbox/sandbox.ts and chat/agent/sandbox.ts, then read api/acp/README.md. Done means a written decision on the data requirement and the hosted-agent versus full-runtime options.

Investigation only. No implementation yet.

Idea: a Junior desktop app in an Electron shell. Sandbox tools (bash, readFile, editFile, grep, findFiles, listDir, writeFile) run on the user's machine instead of in a Vercel Sandbox. Junior still stores the Conversation. Target use: legal and contracting work on local documents (contracts, redlines, PDFs, DOCX) that people do not want to upload first.

Findings are based on main at 7f2443a.

What already exists

• One seam for execution. All sandbox tools go through SandboxAccess / SandboxTools / SandboxWorkspace (packages/junior/src/chat/sandbox/sandbox.ts, sandbox/workspace.ts). createAgentSandbox() in chat/agent/sandbox.ts is the only caller of createSandbox(). @vercel/sandbox is imported only inside chat/sandbox/ (session, snapshot, egress policy). A local execution target can replace this seam without changes in the agent loop.
• The runtime runs outside Vercel. junior chat (chat/local/runner.ts) drives the shared runtime directly with the local-cli actor. It still uses a Vercel Sandbox for tools.
• A client protocol exists. /api/acp exposes Junior as a remote ACP v1 agent (#1525). ACP sessions map to private Conversations and use the normal mailbox, worker, and event store. api/acp/README.md says: "Client paths do not select the Junior sandbox" and "filesystem callbacks and terminal callbacks are not supported". ACP already defines those client methods (fs/read_text_file, fs/write_text_file, terminal/*, session/request_permission). They are the standard way for an agent to run tools on the client machine.
• A chat UI exists. The dashboard has conversation detail, mailbox, and web input (chat/conversations/web-input.ts, #1200). An Electron window can load it.
• A pause/resume pattern exists. awaiting_auth parks a Turn and resumes it after the OAuth callback (chat/agent/resume.ts, local/runner.ts). A Turn that waits for a local tool result needs the same behavior.

Architecture options

A. Hosted agent, local tools (recommended to spike). The agent loop, model calls, plugins, credentials, and storage stay on the server. The Conversation stores a local execution target instead of a SandboxRef. A sandbox tool call becomes a durable pending request. The desktop app receives it, runs it inside a folder that the user granted, and returns the result. The Run continues.

• Pros: model keys, plugin secrets, and OAuth stay host-side. Slack, dashboard, and desktop share one Conversation. Most runtime code does not change.
• Cons: Junior needs a new durable primitive for "tool call waiting for a client". Today a sandbox tool call is a synchronous call inside an execution slice. The app must be online during the Turn, or the Turn parks until it reconnects. ACP v1 cannot replay an in-flight client request after an SSE reconnect, and Vercel functions stop after 300 s. So the pending request must live in SQL/Redis, not only in the stream.
• Transport: ACP client callbacks (this also lets Zed and other ACP clients use local files) or a small Junior-specific poll/stream API. Build the durable pending-call primitive first. The transport is a second decision.

B. Full runtime in the desktop app. Embed the local/runner.ts path in the Electron main process and sync events to the server.

• Cons: the runtime needs Postgres (pg/Neon), a state adapter, AI Gateway auth, plugin secrets, and the plugin catalog. Model keys and provider credentials would have to live on user machines, or go through a new proxy. Syncing two event stores is a new consistency problem. Not recommended.

C. Electron client that uploads files to the Vercel Sandbox. Smallest change. But it does not meet the goal: documents leave the machine and live in the Sandbox filesystem.

Key risks and open questions

• "Local" does not mean the data stays local. In every option, document content goes to the model provider. It is also stored as tool_result agent history items in junior_conversation_events, because replay needs it. Private content is kept 14 days and public content 90 days (conversations/retention.ts). A public Brief stays after the transcript expires. For legal or contracting work we need: private-only Conversations for local targets, a check of the model provider data terms (zero data retention), and maybe a shorter retention for local-target Conversations. If the requirement is "document text is never stored by Junior", option A does not work as is. The agent history would need client-side or encrypted storage, and that breaks the shared Slack and dashboard transcript. Confirm the requirement with Legal/Security before we build.
• Execution safety. policies/security.md says: "Run user-influenced commands in an isolated sandbox." Local execution runs model-chosen commands on a personal machine. Minimum controls: a folder grant per Conversation, OS-level sandboxing for bash (macOS Seatbelt, Linux bubblewrap/Landlock, Windows is less mature), no network or allowlisted network for local commands, and approval prompts. Guardian action review (tool-support/action-review.ts) can stay host-side. ACP session/request_permission can show the local prompt.
• Credentials. Sandbox egress injects credentials through the Vercel network policy and verifies the Vercel Sandbox OIDC token (sandbox/egress/). A desktop target has neither. First version: local commands get no credentialed egress, and provider work stays in host-side plugin tools. A later version could use a device credential bound to user + Conversation.
• Toolchain. Vercel Sandbox snapshots install the declared runtime dependencies and sync skills (skill-sync.ts, runtime-dependencies.ts). User machines do not have these. Legal documents are mostly DOCX/PDF, and readFile reads text. The app must bundle converters (for example pandoc and a PDF text extractor), or the server must convert files. Skills that expect a Linux sandbox (Docker, Workspaces, repo clones) must be hidden for local targets.
• Workspace concept. Workspaces are snapshot recipes for repositories. A local target is a user-picked folder. Do not reuse the Workspace term for it. Add a term to TERMINOLOGY.md.
• Desktop app work. Electron hardening (contextIsolation, no nodeIntegration in the renderer that loads the remote dashboard, a narrow IPC surface). Code signing and notarization for macOS and Windows. Auto-update. IT/MDM distribution. Sign-in can reuse the ACP browser/device-code flow (api/acp/auth.ts).
• Product scope. Is this for Sentry-internal teams (Legal, contracting) only, or is it a Junior product feature? Which OS first (macOS only would remove most sandboxing and signing work)? Can a Conversation have both a Vercel Sandbox and a local target, or only one?

Suggested next steps

1. Confirm the data requirement with Legal/Security: is it "files are not uploaded" or "content is never stored"? This decides between option A and a much larger design.
2. Spike option A with the CLI before Electron: add a local execution target behind SandboxAccess, with readFile/listDir/grep only, read-only, one granted folder, and the app online during the Turn.
3. Then design the durable pending tool call (park/resume like awaiting_auth) and choose ACP callbacks or a custom transport.
4. Add bash/writeFile/editFile only after the OS sandboxing and approval design is reviewed.

Related: #1525 (remote ACP), #1200 (dashboard conversations), #530 (ACP delegation).

via daniel.

--

View Junior Session [Sentry]