Skip to main content

​
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: 
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: 
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

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

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

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

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: 
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: 
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:
OptionTypeDescription
findLinksstring[]URLs to search for packages
indexUrlstringBase URL of Python Package Index
extraIndexUrlsstring[]Extra URLs for package index
prebooleanInclude pre-release and development versions
extraOptionsstringRaw 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' })
  1. Layer optimization: Order commands from least to most frequently changing to maximize Docker layer caching.
  2. Keep images small: Only install necessary packages to reduce build time and storage.
  3. Use build logs: Enable onSnapshotCreateLogs to monitor build progress and debug issues.

Build docs developers (and LLMs) love

Get started for freeTalk to us