Image (v2)

ImageService

class ImageService()

Image build/pull/list namespace.

ImageService.init

def __init__(impl: AsyncImageService, bridge: SyncBridge) -> None

ImageService.build

def build(builder: ImageBuilder,
          /,
          *,
          name: Optional[str] = None,
          idle_expiry_seconds: Optional[int] = None,
          region: Optional[str] = None,
          cpu_arch: Optional[str] = None,
          timeout: Optional[float] = None) -> Image

Build (or import) an image from an ImageBuilder declaration.

ImageService.delete

def delete(image_id: str) -> None

ImageService.follow_build_logs

def follow_build_logs(image_id: str,
                      *,
                      on_logs: _LogsCallback,
                      on_event: Optional[_EventCallback] = None,
                      cursor: Optional[str] = None,
                      timeout: Optional[float] = None) -> BuildLogFollowResult

Observe a submitted image build. Timeout is in seconds, not execution TTL.

ImageService.get

def get(image_id: str,
        *,
        wait: Literal['ready'] | None = None,
        timeout: Optional[float] = None) -> Image

ImageService.iter

def iter(*,
         anonymous: bool = False,
         sandbox_id: Optional[str] = None,
         name: Optional[str] = None,
         cursor: Optional[str] = None,
         limit: Optional[int] = None,
         platform: Optional[Literal['true', 'false', 'any']] = None) -> Iterator[Image]

ImageService.promote

def promote(image_id: str, name: str) -> Image

Name an ANONYMOUS image, making it permanent (PATCH /images/{id}).

ImageService.pull

def pull(image: str,
         *,
         name: Optional[str] = None,
         region: Optional[str] = None,
         timeout: Optional[float] = None) -> Image

AsyncImageService

class AsyncImageService()

Image build/pull/list namespace.

AsyncImageService.init

def __init__(transport: AsyncTransport) -> None

AsyncImageService.follow_build_logs

async def follow_build_logs(image_id: str,
                            *,
                            on_logs: _LogsCallback,
                            on_event: Optional[_EventCallback] = None,
                            cursor: Optional[str] = None,
                            timeout: Optional[float] = None) -> BuildLogFollowResult

Observe a submitted image build. Timeout is in seconds, not execution TTL.

AsyncImageService.build

async def build(builder: ImageBuilder,
                /,
                *,
                name: Optional[str] = None,
                idle_expiry_seconds: Optional[int] = None,
                region: Optional[str] = None,
                cpu_arch: Optional[str] = None,
                timeout: Optional[float] = None) -> Image

Build (or import) an image from an ImageBuilder declaration.

The builder is the only way to say WHAT to build — ImageBuilder. from_dockerfile(...), .from_registry(...), or the fluent .run_commands / .env / .workdir chain — in both SDKs (parity with TypeScript's images.build(builder, options)). name omitted makes the image anonymous; idle_expiry_seconds is then its idle-retention window — deleted once that long has passed without a sandbox being created from it (every create restarts the clock); omitted ⇒ the server maximum (DAYTONA_ANON_IMAGE_MAX_IDLE).

AsyncImageService.pull

async def pull(image: str,
               *,
               name: Optional[str] = None,
               region: Optional[str] = None,
               timeout: Optional[float] = None) -> Image

AsyncImageService.get

async def get(image_id: str,
              *,
              wait: Literal['ready'] | None = None,
              timeout: Optional[float] = None) -> Image

AsyncImageService.promote

async def promote(image_id: str, name: str) -> Image

Name an ANONYMOUS image, making it permanent (PATCH /images/{id}).

Promotion only: an image that already has a name answers 409 — renaming a named image is not offered (sandboxes reference images by id, so a rename would silently relabel every sandbox created from it).

AsyncImageService.delete

async def delete(image_id: str) -> None

AsyncImageService.list

async def list(*,
               anonymous: bool = False,
               sandbox_id: Optional[str] = None,
               name: Optional[str] = None,
               cursor: Optional[str] = None,
               limit: Optional[int] = None,
               platform: Optional[Literal['true', 'false', 'any']] = None) -> ListResult[Image]

List images (GET /images).

platform picks the platform images the operator publishes for every project: "false" (the server default) lists the project's own images, "true" lists only the non-deprecated platform images (the default one carries default=True), and "any" lists both.

AsyncImageService.iter

async def iter(*,
               anonymous: bool = False,
               sandbox_id: Optional[str] = None,
               name: Optional[str] = None,
               cursor: Optional[str] = None,
               limit: Optional[int] = None,
               platform: Optional[Literal['true', 'false', 'any']] = None) -> AsyncIterator[Image]

BuildLogFollowResult

@dataclass(frozen=True)
class BuildLogFollowResult()

Attributes:

status str
reason BuildLogDoneReason
output_complete bool
cursor str | None = None
raw_reason str | None = None

BuildLogStateEvent

@dataclass(frozen=True)
class BuildLogStateEvent()

Attributes:

status str
error str | None = None
deadline_at str | None = None
type Literal['state'] = 'state'

BuildLogChunkEvent

@dataclass(frozen=True)
class BuildLogChunkEvent()

Attributes:

data_base64 str
start_offset str
next_offset str
cursor str
type Literal['log'] = 'log'

BuildLogGapEvent

@dataclass(frozen=True)
class BuildLogGapEvent()

Attributes:

requested_offset str
first_available_offset str
dropped_bytes str
cursor str
reason BuildLogGapReason = 'truncated'
type Literal['gap'] = 'gap'
raw_reason str | None = None

BuildLogUnavailableEvent

@dataclass(frozen=True)
class BuildLogUnavailableEvent()

Attributes:

reason str
type Literal['unavailable'] = 'unavailable'

BuildLogSourceChangedEvent

@dataclass(frozen=True)
class BuildLogSourceChangedEvent()

Attributes:

reason str
type Literal['source_changed'] = 'source_changed'

BuildLogDoneEvent

@dataclass(frozen=True)
class BuildLogDoneEvent()

Attributes:

result BuildLogFollowResult
type Literal['done'] = 'done'

BuildLogErrorEvent

@dataclass(frozen=True)
class BuildLogErrorEvent()

Attributes:

error str
code str
retryable bool
trace_id str | None = None
type Literal['error'] = 'error'

ImageBuilder

@dataclass(frozen=True, slots=True)
class ImageBuilder()

ImageBuilder.from_registry

@classmethod
def from_registry(ref: str) -> Self

ImageBuilder.from_dockerfile

@classmethod
def from_dockerfile(content: str) -> Self

ImageBuilder.pip_install

def pip_install(*packages: str) -> Self

ImageBuilder.run_commands

def run_commands(*commands: str) -> Self

ImageBuilder.env

@overload
def env(name: str, value: str, /) -> Self

ImageBuilder.env

@overload
def env(values: Mapping[str, str], /) -> Self

ImageBuilder.workdir

def workdir(path: str, /) -> Self

ImageBuilder.build_request_source

def build_request_source() -> tuple[dict[str, str] | None, str | None]

ImageBuilder.render_dockerfile

def render_dockerfile() -> str

Render the Dockerfile the build request carries.

Byte-identical to TypeScript's ImageBuilder.toDockerfile() for the same builder: one line per layer, a single trailing newline (a POSIX text file), no trailing whitespace. The text is the build's content key, so the two SDKs must agree to the byte or the same build would dedupe differently across them.

ImageRef

@dataclass(frozen=True, slots=True)
class ImageRef()

Attributes:

id str
name Optional[str] = None

Image

@dataclass(frozen=True, slots=True)
class Image()

Attributes:

id str
name Optional[str]
status str
region str
anonymous bool
retention ArtifactRetention
var_class str
available_in list[str]
origin str
created_at Optional[str] = None
error Optional[str] = None
expires_at Optional[str] = None
source Optional[ImageSource] = None
bytes Optional[int] = None
layer_count Optional[int] = None
cursor Optional[str] = None
format_version Optional[int] = None
format_outdated bool = False
platform bool = False
default bool = False
deprecated bool = False
updated_at Optional[str] = None
disk_mib Optional[int] = None
raw_retention str = field(default='', kw_only=True)

BuildLogDoneReason

BuildLogDoneReason = Literal['terminal', 'deadline', 'not_applicable', 'resource_deleted', 'unknown']

BuildLogGapReason

BuildLogGapReason = Literal['truncated', 'unknown']

BuildLogEvent

BuildLogEvent = BuildLogStateEvent | BuildLogChunkEvent | BuildLogGapEvent | BuildLogUnavailableEvent | BuildLogSourceChangedEvent | BuildLogDoneEvent | BuildLogErrorEvent

ImageBuildResponse

ImageBuildResponse = _gen.api.AsyncOperation

ImageJob

ImageJob = ImageBuildResponse

ImageDto

ImageDto = _gen.api.ImageListItem

ArtifactRetention

ArtifactRetention = Literal['permanent', 'idle', 'unknown']

ImageSource

ImageSource = Union[RegistryImageSource, DockerfileImageSource, NamedImageSource, ManifestImageSource]

On this page

Computersfor Agents