> ## Documentation Index
> Fetch the complete documentation index at: https://alto.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# image

> The `image` key defines the type of image on which to run your code

## Overview

```yaml alto.yml theme={null}
...
  image:
    type: docker
    base: python:3.10.8-slim-bullseye
    registry: dockerhub
    registry_creds:
      username: ...
      password: ...
...
```

Introduced in `v0.0.5`, the image configuration option gives you the ability to run your
code in a custom image within their infrastructure's environment. For example, you can
run their code on a Docker image within their EC2 instance.

## Why use images?

Great question! After all, agents are already their own execution environment — what's
the additional benefit of using images? There are a few:

* **Python versioning**: let's say that your project relies on a version of Python that
  doesn't come pre-installed on your agent (e.g., your project relies on Python 3.10, but
  your agent only has Python 3.9 out-of-the-box). Installing a new version of Python on an
  agent can take a while — rather than deal with this, it's easier to use an image to
  handle your code's execution.
* **Dependency management**: same story as above — let's say your project relies on a
  package version that isn't compatible with your agent's runtime current version of
  Python. Rather than having to rollback your local Python installation or install another
  version of Python on your machine, you can run your code in an agent with a
  pre-specified Python version.
* **Agent-agnostic deployment**: images don't care what agent they're run on. That is,
  if you were to run your code on the agent's environment itself, you may have to tweak
  the code slightly if you decide to change the agent type (e.g., from an EC2 instance to
  an EMR cluster). Using an image eliminates this concern, since the codes runtime is
  separate from the agent's runtime.

## Key Specification

The `image` key accepts the following keys:

### Required keys

* `type`: the image type. As of now, the supported types are:  `docker`
* `base`: the base image upon which to build your custom image. This cannot be specified
  alongside `context`.
* `context`: path to the image context to use to build the image (e.g., the image
  Dockerfile). If this is specified, then all other image build parameters are ignored.
  This cannot be specified alongside `base`.

<Warning>`base` and `context` are mutually exclusive. If `base` is specified, then Alto
will build your context (e.g., your Dockerfile) for you. Otherwise, Alto will rely on
the context at the path you provide</Warning>

### Optional keys

* `image_build_cmds`: custom commands to run when building your image (e.g., `apt ...`).
* `registry`: the registry in which to push your image. As of now, the supported types
  are: `dockerhub` and `ecr`. If not specified, then defaults to `ecr`.
* `registry_creds`: credentials for your chosen registry as nested key-value pairs:
  * `username`: your registry username
  * `password`: your registry password

<Info>If the `registry_creds` are not specified, then Alto will try to infer them or will prompt you for them.</Info>

## Example

Here's a simple configuration for a Docker image on an EC2 agent:

```yaml alto.yml theme={null}
my-new-ec2-agent:
  infra:
    type: ec2
    instance_type: t2.micro
    ami_image: ami-01c647eace872fc02
    python_version: 3.11  # this will be ignored!
  image:
    type: docker
    base: python:3.10.8-slim-bullseye
    registry: dockerhub
    registry_creds:
      username: "XXXXXXXXXXXXXXXXX"
      password: "XXXXXXXXXXXXXXXXX"
  entrypoint:
    type: function
    cmd: main.write_txt_file
  requirements: requirements.txt
  env:
    AWS_ACCESS_KEY_ID: "{{ env('AWS_ACCESS_KEY_ID') }}"
    AWS_SECRET_ACCESS_KEY: "{{ env('AWS_SECRET_ACCESS_KEY') }}"
    AWS_DEFAULT_REGION: "{{ env('AWS_DEFAULT_REGION') }}"
```