Quicksand Image Tools

This package provides development tools for building custom VM images for the quicksand agent harness.

Installation

bash

pip install quick-sandbox
quicksand install dev

CLI Usage

The recommended way to build custom images:

bash

# Initialize a build directory (creates Dockerfile, builds base image if needed)
quicksand-image-tools init ./my-image ubuntu    # or: alpine

# Customize the generated Dockerfile, then build the VM image
quicksand-image-tools build-image ./my-image/Dockerfile -o my-image.qcow2

Example Dockerfile

After running quicksand-image-tools init ./my-image ubuntu, a Dockerfile is created with the versioned base image. Add your customizations:

dockerfile

FROM quicksand/ubuntu-base:24.04.0

# Add your customizations here
RUN apt-get update && apt-get install -y nodejs && rm -rf /var/lib/apt/lists/*

The base images include the kernel, agent, and init configuration. You just add your packages.

Python API

Build a VM image programmatically:

python

import asyncio
from quicksand_image_tools import build_image
from quicksand import Sandbox, SandboxConfig

async def main():
    # Build from a Dockerfile path
    image_path = build_image("./Dockerfile")

    # Use the custom image
    async with Sandbox(SandboxConfig(image_path=str(image_path))) as sb:
        result = await sb.execute("node --version")
        print(result.stdout)

asyncio.run(main())

Dockerfile Requirements

When building FROM a base image (quicksand/ubuntu-base or quicksand/alpine-base), you just add your packages - the base handles everything else.

For scratch Dockerfiles, you must:

Install a kernel: Ubuntu linux-image-virtual or Alpine linux-virt
Build the Rust agent via multi-stage Docker build
Configure a systemd service or OpenRC script to run the agent on boot

See the examples/custom_image.py for a complete working example.

CLI Reference