crusher

crusher

CLI tool for building OCI images, creating Crush sandbox containers, and packing Docker Sandbox agent kits — all powered by functional programming combinators.

Contents

• Prerequisites
• Install
• Commands
  • build
  • create
  • sbx
• Project Structure
• Development

Prerequisites

• Go 1.25+
• Docker — OCI image builds and container management
• sbx — Docker Sandbox CLI (for sbx subcommand)

Install

go install github.com/dictybase-docker/crusher/cmd/crusher@latest

Or build from source:

git clone https://github.com/dictybase-docker/crusher.git
cd crush-sandbox
go build -o crusher ./cmd/crusher

Commands

build

Build an OCI image using the Docker CLI. Supports embeddable Dockerfile, custom build args for tool versions, and multiple tags.

crusher build [--name NAME] [--tag TAG] [--file PATH] [--embed] [--golangci-lint-version VER] [--crush-version VER] [--gotestsum-version VER] [--moxide-version VER] [--sem-version VER] [--rtk-version VER]

Tool versions are passed as --build-arg to Docker. Build context is always the current directory (.).

Example:

# Build with defaults
crusher build

# Build with custom image name and tag
crusher build --name my-image --tag v1.0

# Build using embedded Dockerfile with custom tool versions
crusher build --embed --crush-version 1.2.3 --go-version 1.24.0

create

Create and start a Crush sandbox container with pre-configured volume mounts for config, data, skills, and workspace directories.

crusher create --config PATH --data PATH --skills PATH --api-key KEY [--name NAME] [--image NAME] [--workspace PATH] [--github-token TOKEN] [--volume PATH]

Required mounts are mapped under /home/agent/crush/ inside the container. Extra volumes are mounted read-only under /home/agent/mount/.

Example:

# Create a Crush container with directory mounts
crusher create \
  --config ~/.crush/config \
  --data ~/.crush/data \
  --skills ~/.crush/skills \
  --api-key "sk-..." \
  --workspace ~/my-project

# Create with additional read-only volume and GitHub token
crusher create \
  --config ~/.crush/config \
  --data ~/.crush/data \
  --skills ~/.crush/skills \
  --api-key "sk-..." \
  --volume /data/reference \
  --github-token "ghp_..."

sbx

Generate, validate, and pack a Docker Sandbox agent kit. Reads an optional crush.json config, renders a spec.yaml, validates with the sbx CLI, stores secrets, packs into a zip, and optionally creates the sandbox instance.

crusher sbx --api-key KEY [--output PATH] [--config PATH] [--skills PATH] [--name NAME] [--create] [--crush-version VER] [--golangci-lint-version VER] [--go-version VER] [--gotestsum-version VER] [--moxide-version VER] [--sem-version VER] [--rtk-version VER]

The pipeline: generate spec → validate kit → store secret → pack kit → (optionally create sandbox) → cleanup temp dir.

Example:

# Pack a kit with default config
crusher sbx --api-key "sk-or-..."

# Pack with custom config and skills, then create the sandbox
crusher sbx \
  --api-key "sk-or-..." \
  --config ~/.crush/config/crush.json \
  --skills ~/.crush/skills \
  --name my-sandbox \
  --create \
  --output ./my-kit.zip

Project Structure

.
├── cmd/
│   └── crusher/
│       └── main.go              # CLI entry point, subcommand registration
├── internal/
│   ├── containerbuild/
│   │   ├── command.go           # build subcommand: CLI flags, InputFromCommand, Action
│   │   ├── input.go             # Input, CommandSpec, DockerfileResource types
│   │   ├── validate.go          # Pure Either-based input validation
│   │   ├── args.go              # Pure argv rendering for container build
│   │   ├── exec.go              # IOEither-based process execution with resource cleanup
│   │   ├── resource.go          # FileResolver, EmbeddedResolver for Dockerfile
│   │   ├── embed.go             # //go:embed Dockerfile
│   │   └── Dockerfile           # Embedded default Dockerfile
│   ├── containercreate/
│   │   ├── command.go           # create subcommand: CLI flags, InputFromCommand, Action
│   │   ├── input.go             # Input, ResolvedInput, ContainerResult, MountSpec types
│   │   ├── validate.go          # Path validation and container name generation
│   │   ├── args.go              # Pure argv rendering for container create
│   │   ├── exec.go              # Process execution with container start
│   │   ├── mounts.go            # Volume mount resolution
│   │   └── namegen.go           # Container name auto-generation
│   ├── containersbx/
│   │   ├── command.go           # sbx subcommand: CLI flags, InputFromCommand, Action
│   │   ├── input.go             # Input, ResolvedInput, KitResult, execState types
│   │   ├── validate.go          # Input normalization and validation
│   │   ├── specgen.go           # spec.yaml template rendering
│   │   ├── config.go            # crush.json reader with OpenRouter default
│   │   ├── exec.go              # Multi-stage pipeline: generate → validate → pack → create
│   │   ├── embed.go             # //go:embed spec.yaml.tmpl
│   │   └── spec.yaml.tmpl       # Docker Sandbox agent spec template
│   └── fp/
│       ├── conversion.go        # ToEither helper for IOEither → Either conversion
│       └── conversion_test.go

Packages

All packages are built with fp-go functional programming combinators and use urfave/cli for the CLI framework.

Development

# Run tests
gotestsum --format pkgname-and-test-fails --format-hide-empty-pkg -- ./...

# Run tests with verbose output
gotestsum --format testdox --format-hide-empty-pkg -- ./...

# Lint
golangci-lint run ./...

# Format
golangci-lint fmt

# Build
go build -o crusher ./cmd/crusher