I’ve written a lot lately about Docker sandboxes as a great tool for working safely with coding agents but what I failed to mention is that those sandboxes don’t include any of the tools you need to create smart contract on Starknet or elsewhere.

At the heart of a sandbox there’s a Docker image that supports common programming languages like Node, Python or Go but it doesn’t include binaries for compiling Cairo or tools to interact with Starknet.

You can of course install all the binaries you want inside a sandbox with help from the coding agent but those changes are localized, if you create a new sandbox those binaries won’t be present. This approach doesn’t scale well when you manage multiple agents in multiple sandboxes.

Fortunately Docker provides a mechanism to extend the binaries available on a sandbox by using “templates”.

Templates

A template is a custom Docker image that extends one of the official base images for coding agents and adds additional dependencies that you’d like in a sandbox when created.

Docker maintains two base images for every coding agent, one that includes Docker CLI and one that doesn’t. You can tell them apart by the -docker suffix in the image tag.

# Base image for OpenCode WITHOUT Docker CLI
docker/sandbox-templates:opencode

# Base image for OpenCode WITH Docker CLI
docker/sandbox-templates:opencode-docker

Four our Starknet template we are going to use the sandbox-templates:opencode-docker image as our base because I prefer OpenCode as a coding agent and because I want my agent to be able to spin up Docker containers if needed.

Project Setup

We start by creating a project folder for our custom template called sn-template:

$ mkdir sn-template

Next we create a Dockerfile where we’ll define the base image for our template and all the additional dependencies we want a sandbox to have.

$ touch sn-template/Dockerfile
# sn-template/Dockerfile

FROM docker/sandbox-templates:opencode-docker

Installing Starkup

The easiest way to install all the binaries needed for Starknet development is to use starkup. Starkup is a shell script that installs the asdf package manager and then uses it to install the compatible version of the following Starknet dependencies:

To install Starkup we use the shell script shown in their docs in non-interactive mode.

# sn-template/Dockerfile

FROM docker/sandbox-templates:opencode-docker

USER agent

# Install Starknet toolchain via Starkup
RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.starkup.sh | sh -s -- --yes

# Add asdf shims to PATH for non-interactive shells
ENV PATH="${PATH}:/home/agent/.asdf/shims"

We use the predefined user agent from the base image to make sure the binaries go to the home folder and don’t require sudo for execution.

If you were to install Starkup directly on your computer you wouldn’t have to worry about updating PATH as we do in the last line of the Dockerfile to make sure all the new binaries are resolved correctly. Starkup’s installation script does it for you by updating .bashrc.

The problem is that a sandbox runs in non-interactive mode so .bashrc is never loaded and thus PATH is never updated. We have to do it ourselves explicitly in the Dockerfile.

Now that we have a custom Docker image that includes all the dependencies we need, we are ready to create a template for our sandboxes.

Creating a Template

To create a template we need to build the image from the Dockerfile we just created.

$ docker build --no-cache -t sn-template:v1 ./sn-template

We need to make sure to use the options --no-cache because Docker is not versioning their base images and because starkup only offer two versions to install: compatible and latest. You need to make sure to always get the latest version of all tools by avoiding reading from the cache when building the image.

Once built we can check the size of the image from the terminal.

$ docker image ls
>>> i Info → U In Use
IMAGE ID DISK USAGE CONTENT SIZE EXTRA
sn-template:v1 6994f82f7d99 2.49GB 0B

The resulting image is big at 2.49 GB but we can’t blame Starkup for it, the base image itself is already 2 GB in size. Starkup added 490 MB by installing 7 Starknet tools plus asdf.

From here there are two paths forward: you can push the image to a registry like Docker Hub if you want to share your template with other people or you can package the image into a tarball and load it into Docker sandbox if you are the only consumer of the template.

I’m going to do everything local for this tutorial so I’ll start by packing the image.

$ docker image save sn-template:v1 -o sn-template/image.tar

Next, we are going to load the packaged image into Docker sandbox so it becomes available as a template that can be used when creating a new sandbox.

$ sbx template load sn-template/image.tar

If everything went well we should be able to see our image as an available template.

$ sbx template ls
>>>
REPOSITORY TAG IMAGE ID FLAVOR CREATED
docker.io/library/sn-template v1 557ea1fbca4d opencode-docker Less than a minute ago

Using a Template

Our custom template is ready to be used so let’s `create` a new sandbox using the --template flag on a sample project folder called myapp.

$ sbx create opencode --name sn-sbx --template sn-template:v1 ./myapp

Make sure to only use the opencode agent with this template as it’s the only one compatible given the base image we chose.

Launch the sandbox to interact with the coding agent.

$ sbx run --name sn-sbx

OpenCode should have opened so ask the agent to inspect its environment.

[build] $ Do you have tools for Starknet development in your environment?
>>>
Yes — all the Starknet tools are available.
I can compile, test, deploy, and profile Starknet contracts,
and run a local devnet — all out of the box.

We have now a reusable Starknet template to use with Docker sandbox.

Conclusion

A template is a way to customize the environment of your sandbox in a way that is repeatable and easy to share with other people. I only showed you a basic template that adds Starkup to a sandbox for Starknet development but you could go much further than that. If you find yourself frequently entering a sandbox in interactive mode with sbx exec it <sandbox> bash then you might want to add other tools like LazyVim for exploring and editing files directly and oh-my-szh for a more informative shell.

You could even go a step further and create a kit to also define which domains a Starknet specific templates should have access to, custom files you want to always load from your host, etc. Just be mindful that a Sandbox Kit is still an experimental feature with frequent breaking changes.

David

Author

David Barreto