AIHero

    Reference

    CLI commands

    Edit this page on GitHub
    On this page

    sandcastle init

    Scaffolds the .sandcastle/ config directory and, for an image-based provider, builds the container image. This is the first command you run in a new repo.

    See Init for what init asks, checks and writes.

    OptionRequiredDefaultDescription
    --image-nameNosandcastle:<repo-dir-name>Image name to build, also passed as imageName to the scaffolded main file's sandbox
    --agentNoInteractive promptAgent to use (claude-code, pi, codex, cursor, opencode, copilot)
    --modelNoAgent's default modelModel to use (e.g. claude-sonnet-4-6). Defaults to agent's default
    --sandboxNoInteractive promptSandbox provider to use (bwrap, seatbelt, docker, podman)
    --templateNoInteractive promptTemplate to scaffold (e.g. blank, simple-loop)
    --issue-trackerNoInteractive promptIssue tracker to use (github-issues, beads, custom)
    --create-labelNoInteractive prompttrue / false — whether to create the Sandcastle GitHub label (only with --issue-tracker github-issues)
    --build-imageNoInteractive prompttrue / false — whether to build the sandbox image now (ignored with --issue-tracker custom or a native provider)
    --install-template-depsNoInteractive prompttrue / false — whether to install template host deps (e.g. zod for the planner templates)

    sandcastle docker build-image

    Rebuilds the Docker image from an existing .sandcastle/ directory. Use this after modifying the Dockerfile. On Linux/macOS, the build automatically passes --build-arg AGENT_UID=$(id -u) and AGENT_GID=$(id -g) so the image's agent user matches the host UID — this prevents permission errors on image-built files without runtime chown.

    OptionRequiredDefaultDescription
    --image-nameNosandcastle:<repo-dir-name>Docker image name
    --dockerfileNo—Path to a custom Dockerfile (build context will be the current working directory)

    sandcastle docker remove-image

    Removes the Docker image.

    OptionRequiredDefaultDescription
    --image-nameNosandcastle:<repo-dir-name>Docker image name

    sandcastle podman build-image

    Builds the Podman image from an existing .sandcastle/ directory. Use this after modifying the Containerfile.

    OptionRequiredDefaultDescription
    --image-nameNosandcastle:<repo-dir-name>Podman image name
    --containerfileNo—Path to a custom Containerfile (build context will be the current working directory)

    sandcastle podman remove-image

    Removes the Podman image.

    OptionRequiredDefaultDescription
    --image-nameNosandcastle:<repo-dir-name>Podman image name