Custom Images

Use custom Docker images and configure dynamic image builds for Daytona sandboxes

Overview

Daytona supports creating sandboxes from custom Docker images in two ways:

• Pre-built images from Docker registries
• Dynamic images using Daytona’s declarative Image builder

Using Pre-built Images

You can create sandboxes from any public or private Docker image:

TypeScript

import { Daytona } from '@daytonaio/sdk'

const daytona = new Daytona()

// Use any Docker image from a registry
const sandbox = await daytona.create({
  image: 'python:3.12-slim-bookworm',
  resources: {
    cpu: 2,
    memory: 4,
    disk: 20
  }
})

Declarative Image Builder

Daytona provides a declarative API for building custom images programmatically:

Base Images

Start with a base image using one of these methods:

TypeScript

import { Image } from '@daytonaio/sdk'

// Use any Docker base image
const image1 = Image.base('alpine:3.18')

// Use Debian Slim with Python (optimized for data science)
const image2 = Image.debianSlim('3.12')  // Python 3.12
const image3 = Image.debianSlim('3.13')  // Python 3.13
const image4 = Image.debianSlim()        // Latest supported version

Installing Python Packages

TypeScript

import { Image } from '@daytonaio/sdk'

// Install packages from PyPI
const image = Image.debianSlim('3.12')
  .pipInstall(['numpy', 'pandas', 'matplotlib', 'scipy', 'scikit-learn'])
  .pipInstall('requests', {
    indexUrl: 'https://pypi.org/simple',
    extraIndexUrls: ['https://custom.pypi.org/simple'],
    pre: true  // Include pre-release versions
  })

// Install from requirements.txt
const image2 = Image.debianSlim('3.12')
  .pipInstallFromRequirements('requirements.txt')

// Install from pyproject.toml
const image3 = Image.debianSlim('3.12')
  .pipInstallFromPyproject('pyproject.toml', {
    optionalDependencies: ['dev', 'test']
  })

Adding Files and Directories

TypeScript

import { Image } from '@daytonaio/sdk'

const image = Image.debianSlim('3.12')
  // Add a local file
  .addLocalFile('config.json', '/app/config.json')
  // Add a local directory
  .addLocalDir('src', '/app/src')
  // Run shell commands
  .runCommands(
    'apt-get update && apt-get install -y git curl',
    'mkdir -p /app/data'
  )

Environment Variables and Working Directory

TypeScript

import { Image } from '@daytonaio/sdk'

const image = Image.debianSlim('3.12')
  .env({
    NODE_ENV: 'production',
    API_KEY: 'your-key',
    DEBUG: 'true'
  })
  .workdir('/home/daytona/workspace')

Complete Example

TypeScript

import { Daytona, Image } from '@daytonaio/sdk'
import fs from 'fs'

const daytona = new Daytona()

// Create a custom data science image
const image = Image.debianSlim('3.12')
  .pipInstall(['numpy', 'pandas', 'matplotlib', 'scipy', 'scikit-learn'])
  .runCommands(
    'apt-get update && apt-get install -y git',
    'mkdir -p /home/daytona/workspace'
  )
  .workdir('/home/daytona/workspace')
  .env({
    PYTHONUNBUFFERED: '1',
    PROJECT_ENV: 'development'
  })
  .addLocalFile('config.json', '/home/daytona/workspace/config.json')

// Create sandbox with dynamic image
const sandbox = await daytona.create(
  {
    image,
    resources: {
      cpu: 4,
      memory: 8,
      disk: 50
    }
  },
  {
    timeout: 120,
    onSnapshotCreateLogs: console.log  // Stream build logs
  }
)

Using Dockerfiles

You can also build images from existing Dockerfiles:

TypeScript

import { Image } from '@daytonaio/sdk'

const image = Image.fromDockerfile('./path/to/Dockerfile')

const sandbox = await daytona.create({ image })

Advanced Dockerfile Commands

For advanced use cases, you can add raw Dockerfile commands:

TypeScript

import { Image } from '@daytonaio/sdk'

const image = Image.base('ubuntu:22.04')
  .dockerfileCommands([
    'RUN apt-get update',
    'RUN apt-get install -y build-essential',
    'EXPOSE 8080',
    'HEALTHCHECK CMD curl --fail http://localhost:8080 || exit 1'
  ])
  .entrypoint(['/bin/bash'])
  .cmd(['-c', 'echo Hello World'])

Image Build Options

Supported Python Versions

Daytona’s debianSlim() method supports:

• Python 3.9 (3.9.22)
• Python 3.10 (3.10.17)
• Python 3.11 (3.11.12)
• Python 3.12 (3.12.10)
• Python 3.13 (3.13.3)

Pip Install Options

The pipInstall() method accepts these options:

Option	Type	Description
findLinks	string[]	URLs to search for packages
indexUrl	string	Base URL of Python Package Index
extraIndexUrls	string[]	Extra URLs for package index
pre	boolean	Include pre-release and development versions
extraOptions	string	Raw options passed to pip install

Best Practices

1. Use snapshots for repeated builds: If you’re creating multiple sandboxes with the same image, create a snapshot first:

const snapshot = await daytona.snapshot.create({
  name: 'my-custom-image',
  image: myImage,
  resources: { cpu: 2, memory: 4, disk: 20 }
})

// Reuse the snapshot for faster creation
const sandbox1 = await daytona.create({ snapshot: 'my-custom-image' })
const sandbox2 = await daytona.create({ snapshot: 'my-custom-image' })

2. Layer optimization: Order commands from least to most frequently changing to maximize Docker layer caching.

3. Keep images small: Only install necessary packages to reduce build time and storage.

4. Use build logs: Enable onSnapshotCreateLogs to monitor build progress and debug issues.

Related

• Resource Management - Configure CPU, memory, and disk
• Snapshots - Create reusable images