Installing Custom Dependencies

Learn how to install additional languages or tools inside Sculptor’s task containers.

Overview

Use this flow when your project requires tools or languages not preinstalled in Sculptor’s default container.

Sculptor supports creating container environments using parts of the dev container specification.

For further discussion of dev container optimization, see our blog post.

---

Steps

1. Create a devcontainer.json file

Inside your repository, create and commit:

<repo>/.devcontainer/devcontainer.json

The contents of this file can point to either a public Docker image or a Dockerfile inside your repository. To use a Dockerfile inside your repo, the contents of this file would be something like:

{
  "name": "My Project's Dev Container",
  "build": {
    "dockerfile": "Dockerfile"
  }
}

Just like VS Code, Sculptor supports JSON5 syntax, including comments inside the JSON and trailing commas in this file.

Use a Dockerfile in the same directory to configure any dependencies. For example:

FROM ubuntu:24.04

# Prevent interactive prompts during package installation
ENV DEBIAN_FRONTEND=noninteractive

# Install system dependencies
RUN apt-get update && apt-get install -y \
    build-essential \
    git \
    curl \
    ca-certificates \
    python3 \
    python3-pip \
    python3-venv \
    ffmpeg \
    sudo \
    ncdu \
    && rm -rf /var/lib/apt/lists/*

# Copy uv from official image
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

# ...

Tip: You can ask Sculptor to generate and update the dev container configuration and Dockerfile for a project whenever a task fails due to missing dependencies.

Example prompt:

Configure a devcontainer.json file in this repo to prebake useful dependencies for a project that involves <rust/go/java/kotlin/maven/gradle>.

Options (choose exactly one):
1. Configure the dev container to run as the root user.
2. Configure the dev container to run as a development user, with passwordless sudo privileges.
3. Configure the dev container to run as a development user without sudo privileges (prevents the agent from running sudo).

Keep in mind:

• If Sculptor edits its own dev container configuration, those changes will not take effect in the active task's environment. They will appear for future tasks launched with that dev container configuration.

• Sculptor supports dev containers derived from Ubuntu, Alpine, Debian and other Linux distributions.

• Sculptor does NOT currently support dev container images that use Nix to manage packages.

---

2. Start a new task

• Dependencies cannot be added retroactively to an existing task.

• After the container builds, check the Logs tab to confirm your dev container build ran successfully.

More dev container details

Sculptor supports the following dev container options from the dev container spec:

• build

  • dockerfile

  • context

• image (mutually exclusive with build.dockerfile)

• containerUser (or defaults to the last active user in the Dockerfile)

Sculptor does NOT currently support, and will ignore, the following dev container options (this list is not exhaustive):

• Docker Compose

• Lifecycle commands (onCreateCommand, updateContentCommand, etc.)

• Mounts (mounts)

• Ports (forwardPorts)

For a sample project using a complex dev container, see our sample repo.