Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/mattpocock/sandcastle/llms.txt

Use this file to discover all available pages before exploring further.

interactive() launches an agent’s interactive terminal UI (TUI) with your terminal attached. Unlike run(), which runs the agent unattended, interactive() puts you in the session — you can watch what the agent does and approve any permission prompts in real time. When the session ends, Sandcastle collects commits and handles branch merging just as it does for run(). interactive() is the only top-level function that accepts noSandbox() as the sandbox option. With noSandbox(), the agent runs directly on your host machine without a container and without --dangerously-skip-permissions — permissions are gated by the interactive TUI instead.

​
Import

import { interactive, claudeCode } from "@ai-hero/sandcastle";
import { noSandbox } from "@ai-hero/sandcastle/sandboxes/no-sandbox";
import { docker } from "@ai-hero/sandcastle/sandboxes/docker";

​
Signature

function interactive(options: InteractiveOptions): Promise<InteractiveResult>

​
Usage with noSandbox()

import { interactive, claudeCode } from "@ai-hero/sandcastle";
import { noSandbox } from "@ai-hero/sandcastle/sandboxes/no-sandbox";

const result = await interactive({
  agent: claudeCode("claude-opus-4-7"),
  sandbox: noSandbox(),
  // prompt is optional — omit to open the TUI with no initial message
  prompt: "Explore the codebase and understand the authentication flow.",
  cwd: "/path/to/other-repo",
});

console.log(result.commits);   // commits made during the session
console.log(result.branch);    // branch the agent worked on
console.log(result.exitCode);  // exit code of the interactive process

​
Usage with a container sandbox

import { interactive, claudeCode } from "@ai-hero/sandcastle";
import { docker } from "@ai-hero/sandcastle/sandboxes/docker";

const result = await interactive({
  agent: claudeCode("claude-opus-4-7"),
  sandbox: docker(),
  branchStrategy: { type: "branch", branch: "agent/explore-42" },
  prompt: "Explore the codebase and understand the authentication flow.",
});

​
Options

​
agent
AgentProvider
required
The agent provider — for example claudeCode("claude-opus-4-7"). The provider must implement buildInteractiveArgs.
​
sandbox
AnySandboxProvider
default:"noSandbox()"
Sandbox provider. Accepts docker(), podman(), vercel(), or noSandbox(). Defaults to noSandbox() when omitted. With noSandbox(), the agent runs directly on the host without --dangerously-skip-permissions.
​
prompt
string
Inline prompt passed to the agent at session start. Optional — omit to open the TUI with no initial message. Mutually exclusive with promptFile.
​
promptFile
string
Path to a prompt file. Mutually exclusive with prompt. Resolves against process.cwd().
​
name
string
Optional display name for the session, shown in the summary output.
​
branchStrategy
BranchStrategy
Branch strategy. Defaults to { type: "head" } for bind-mount and no-sandbox providers, and { type: "merge-to-head" } for isolated providers. See BranchStrategy.
​
hooks
SandboxHooks
Lifecycle hooks. See SandboxHooks.
​
copyToWorktree
string[]
Host-relative file paths to copy into the worktree before the session starts. Not supported with branchStrategy: { type: "head" }.
​
promptArgs
PromptArgs
Key-value map for {{KEY}} placeholder substitution. Only applies when using promptFile. Passing promptArgs with an inline prompt is an error.
​
env
Record<string, string>
Additional environment variables to inject into the sandbox. Merged on top of .sandcastle/.env and provider env.
​
cwd
string
default:"process.cwd()"
Host repo directory. Relative paths resolve against process.cwd(); absolute paths pass through as-is.
​
signal
AbortSignal
An AbortSignal that cancels the session when aborted. If already aborted at entry, interactive() rejects immediately. The rejected promise surfaces signal.reason directly — no Sandcastle-specific wrapping.
​
timeouts
Timeouts
Override default timeouts for built-in lifecycle steps. See Timeouts.

​
Return value

​
commits
{ sha: string }[]
List of commits made during the interactive session.
​
branch
string
The branch name the agent worked on.
​
preservedWorktreePath
string | undefined
Host path to the preserved worktree, set when the worktree had uncommitted changes at session end. undefined when the worktree was clean.
​
exitCode
number
Exit code of the interactive agent process.

​
Notes

  • prompt is optional for interactive(). Omitting it opens the TUI with no initial message, letting you type the first prompt yourself.
  • With noSandbox(), the agent runs on the host and the standard permission UI is active — no --dangerously-skip-permissions flag is passed.
  • All three branch strategies (head, merge-to-head, branch) are supported, unlike createWorktree() which excludes head.

Build docs developers (and LLMs) love

Get started for freeTalk to us