Skip to content

Add namespace option to customize the sandcastle prefix #553

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
elkinjosetm wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add namespace option to customize the sandcastle prefix #553

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8476e4e
feat: add namespace option to customize sandcastle prefix in branch +…
elkinjosetm May 5, 2026
2a01545
feat: extend namespace to container + session names (docker/podman/da…
elkinjosetm May 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/namespace-option.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@ai-hero/sandcastle": patch
---

Add an optional `namespace` field on `RunOptions`, `CreateSandboxOptions`, and `CreateWorktreeOptions`. When set, it replaces the hardcoded `sandcastle` prefix used in the temporary branch ref (`<namespace>/<timestamp>`), worktree directory name (`<namespace>-<timestamp>`), worktree parent directory (`.<namespace>/worktrees/`), log directory (`.<namespace>/logs/`), patches directory (`.<namespace>/patches/`), and container / session names produced by the docker, podman, and daytona providers (`<namespace>-<uuid>`). Defaults to `"sandcastle"`, so existing behavior is unchanged. The `.sandcastle/.env` location is intentionally not affected. The namespace is forwarded to providers via a new optional field on `BindMountCreateOptions` and `IsolatedCreateOptions`; third-party providers can opt into reading it for their own naming.
76 changes: 44 additions & 32 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -153,6 +153,15 @@ const result = await run({
// Relative paths resolve against process.cwd(). Defaults to process.cwd().
cwd: "../other-repo",

// Prefix used for the worktree branch (`<namespace>/<timestamp>`),
// worktree directory (`<namespace>-<timestamp>`), worktree parent dir
// (`.<namespace>/worktrees/`), log dir (`.<namespace>/logs/`), and patches
// dir (`.<namespace>/patches/`). Useful for keeping branches and dirs from
// distinct workflows separate (e.g. "feature-bot" vs "triage-bot") inside
// the same repo. Defaults to `"sandcastle"`. The `.sandcastle/.env` lookup
// is unaffected.
namespace: "feature-bot",

// Branch strategy — controls how the agent's changes relate to branches.
// Defaults to { type: "head" } for bind-mount and { type: "merge-to-head" } for isolated providers.
branchStrategy: { type: "branch", branch: "agent/fix-42" },
Expand Down Expand Up @@ -295,14 +304,15 @@ if (closeResult.preservedWorktreePath) {

#### `CreateSandboxOptions`

| Option | Type | Default | Description |
| ---------------- | --------------- | --------------- | -------------------------------------------------------------------- |
| `branch` | string | — | **Required.** Explicit branch for the sandbox |
| `sandbox` | SandboxProvider | — | **Required.** Sandbox provider (e.g. `docker()`, `podman()`) |
| `cwd` | string | `process.cwd()` | Host repo directory — relative paths resolve against `process.cwd()` |
| `hooks` | SandboxHooks | — | Lifecycle hooks (`host.*`, `sandbox.*`) — run once at creation time |
| `copyToWorktree` | string[] | — | Host-relative file paths to copy into the sandbox at creation time |
| `timeouts` | Timeouts | — | Override default timeouts (e.g. `{ copyToWorktreeMs: 120_000 }`) |
| Option | Type | Default | Description |
| ---------------- | --------------- | --------------- | ------------------------------------------------------------------------------------------------- |
| `branch` | string | — | **Required.** Explicit branch for the sandbox |
| `sandbox` | SandboxProvider | — | **Required.** Sandbox provider (e.g. `docker()`, `podman()`) |
| `cwd` | string | `process.cwd()` | Host repo directory — relative paths resolve against `process.cwd()` |
| `namespace` | string | `"sandcastle"` | Prefix for `.<namespace>/{worktrees,logs,patches}/`. The `.sandcastle/.env` lookup is unaffected. |
| `hooks` | SandboxHooks | — | Lifecycle hooks (`host.*`, `sandbox.*`) — run once at creation time |
| `copyToWorktree` | string[] | — | Host-relative file paths to copy into the sandbox at creation time |
| `timeouts` | Timeouts | — | Override default timeouts (e.g. `{ copyToWorktreeMs: 120_000 }`) |

#### `Sandbox`

Expand Down Expand Up @@ -401,11 +411,12 @@ await sandbox.close();

#### `CreateWorktreeOptions`

| Option | Type | Default | Description |
| ---------------- | ---------------------- | ------- | ------------------------------------------------------------------------- |
| `branchStrategy` | WorktreeBranchStrategy | — | **Required.** `{ type: "branch", branch }` or `{ type: "merge-to-head" }` |
| `copyToWorktree` | string[] | — | Host-relative file paths to copy into the worktree at creation time |
| `timeouts` | Timeouts | — | Override default timeouts (e.g. `{ copyToWorktreeMs: 120_000 }`) |
| Option | Type | Default | Description |
| ---------------- | ---------------------- | -------------- | ------------------------------------------------------------------------------------------------- |
| `branchStrategy` | WorktreeBranchStrategy | — | **Required.** `{ type: "branch", branch }` or `{ type: "merge-to-head" }` |
| `namespace` | string | `"sandcastle"` | Prefix for `.<namespace>/{worktrees,logs,patches}/`. The `.sandcastle/.env` lookup is unaffected. |
| `copyToWorktree` | string[] | — | Host-relative file paths to copy into the worktree at creation time |
| `timeouts` | Timeouts | — | Override default timeouts (e.g. `{ copyToWorktreeMs: 120_000 }`) |

#### `Worktree`

Expand Down Expand Up @@ -665,25 +676,26 @@ Removes the Podman image.

### `RunOptions`

| Option | Type | Default | Description |
| -------------------- | ------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent` | AgentProvider | — | **Required.** Agent provider (e.g. `claudeCode("claude-opus-4-6")`, `pi("claude-sonnet-4-6")`, `codex("gpt-5.4-mini")`, `opencode("opencode/big-pickle")`) |
| `sandbox` | SandboxProvider | — | **Required.** Sandbox provider (e.g. `docker()`, `podman()`, `docker({ imageName: "sandcastle:local" })`) |
| `cwd` | string | `process.cwd()` | Host repo directory — anchor for `.sandcastle/` artifacts and git operations. Relative paths resolve against `process.cwd()`. |
| `prompt` | string | — | Inline prompt (mutually exclusive with `promptFile`) |
| `promptFile` | string | — | Path to prompt file (mutually exclusive with `prompt`). Resolves against `process.cwd()`, **not** `cwd`. |
| `maxIterations` | number | `1` | Maximum iterations to run |
| `hooks` | SandboxHooks | — | Lifecycle hooks (`host.*`, `sandbox.*`) |
| `name` | string | — | Display name for the run, shown as a prefix in log output |
| `promptArgs` | PromptArgs | — | Key-value map for `{{KEY}}` placeholder substitution |
| `branchStrategy` | BranchStrategy | per-provider default | Branch strategy: `{ type: 'head' }`, `{ type: 'merge-to-head' }`, or `{ type: 'branch', branch: '…' }` |
| `copyToWorktree` | string[] | — | Host-relative file paths to copy into the sandbox before start (not supported with `branchStrategy: { type: 'head' }`) |
| `logging` | object | file (auto-generated) | `{ type: 'file', path }` or `{ type: 'stdout' }` |
| `completionSignal` | string \| string[] | `<promise>COMPLETE</promise>` | String or array of strings the agent emits to stop the iteration loop early |
| `idleTimeoutSeconds` | number | `600` | Idle timeout in seconds — resets on each agent output event |
| `resumeSession` | string | — | Resume a prior Claude Code session by ID. Incompatible with `maxIterations > 1`. Session file must exist on host. |
| `signal` | AbortSignal | — | Cancel the run when aborted. Kills the in-flight agent subprocess and cancels lifecycle hooks; the worktree is preserved on disk. Rejects with `signal.reason`. |
| `timeouts` | Timeouts | — | Override default timeouts for built-in lifecycle steps. Currently supports `{ copyToWorktreeMs?: number }` (default: 60 000). |
| Option | Type | Default | Description |
| -------------------- | ------------------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent` | AgentProvider | — | **Required.** Agent provider (e.g. `claudeCode("claude-opus-4-6")`, `pi("claude-sonnet-4-6")`, `codex("gpt-5.4-mini")`, `opencode("opencode/big-pickle")`) |
| `sandbox` | SandboxProvider | — | **Required.** Sandbox provider (e.g. `docker()`, `podman()`, `docker({ imageName: "sandcastle:local" })`) |
| `cwd` | string | `process.cwd()` | Host repo directory — anchor for `.sandcastle/` artifacts and git operations. Relative paths resolve against `process.cwd()`. |
| `namespace` | string | `"sandcastle"` | Prefix for the temporary branch (`<namespace>/<timestamp>`), worktree dir (`<namespace>-<timestamp>`), and `.<namespace>/{worktrees,logs,patches}/`. The `.sandcastle/.env` lookup is unaffected. |
| `prompt` | string | — | Inline prompt (mutually exclusive with `promptFile`) |
| `promptFile` | string | — | Path to prompt file (mutually exclusive with `prompt`). Resolves against `process.cwd()`, **not** `cwd`. |
| `maxIterations` | number | `1` | Maximum iterations to run |
| `hooks` | SandboxHooks | — | Lifecycle hooks (`host.*`, `sandbox.*`) |
| `name` | string | — | Display name for the run, shown as a prefix in log output |
| `promptArgs` | PromptArgs | — | Key-value map for `{{KEY}}` placeholder substitution |
| `branchStrategy` | BranchStrategy | per-provider default | Branch strategy: `{ type: 'head' }`, `{ type: 'merge-to-head' }`, or `{ type: 'branch', branch: '…' }` |
| `copyToWorktree` | string[] | — | Host-relative file paths to copy into the sandbox before start (not supported with `branchStrategy: { type: 'head' }`) |
| `logging` | object | file (auto-generated) | `{ type: 'file', path }` or `{ type: 'stdout' }` |
| `completionSignal` | string \| string[] | `<promise>COMPLETE</promise>` | String or array of strings the agent emits to stop the iteration loop early |
| `idleTimeoutSeconds` | number | `600` | Idle timeout in seconds — resets on each agent output event |
| `resumeSession` | string | — | Resume a prior Claude Code session by ID. Incompatible with `maxIterations > 1`. Session file must exist on host. |
| `signal` | AbortSignal | — | Cancel the run when aborted. Kills the in-flight agent subprocess and cancels lifecycle hooks; the worktree is preserved on disk. Rejects with `signal.reason`. |
| `timeouts` | Timeouts | — | Override default timeouts for built-in lifecycle steps. Currently supports `{ copyToWorktreeMs?: number }` (default: 60 000). |

### `RunResult`

Expand Down
Loading