# Custom images

> Bring your own container image, public or private.

This page covers running your own image, what the image must provide, and how the start command, environment variables and secrets reach it.

## Run your own image

<tabs sync="interface">
<tabs-item label="Console">

On the deploy page, **Set overrides** takes the image reference, for example `ghcr.io/acme/trainer:1.4`, and the registry credential to pull it with.

</tabs-item>

<tabs-item label="CLI">

```bash
featherless-cloud instance create --name trainer --image ghcr.io/acme/trainer:1.4 --gpu-count 1
featherless-cloud exec --image ghcr.io/acme/trainer:1.4 --gpu-count 1 -- python train.py
```

Add `--registry <name>` to choose a registry credential for a private image.

</tabs-item>
</tabs>

## Check that your image will run

- The image must support `linux/amd64`.
- It must be in a registry reachable over HTTPS, such as Docker Hub, GitHub Container Registry or your own.
- GPU images need the libraries for the GPU you choose: ROCm for AMD GPUs, CUDA for NVIDIA GPUs.
- For SSH, the image must run as root and include an SSH server, or a package manager (`apt`, `dnf`, `yum`, `apk` or `zypper`) that can install one. Without it, use the browser terminal.

A tag can move to a new build between deploys. Deploy by digest (`image@sha256:…`) when every run must use the same build.

## Pull from a private registry

[Add registry credentials](/get-started/credentials#add-registry-credentials) for the registry first. With **Automatic**, the image is pulled without credentials when it's public, and otherwise with a credential for its registry that your organization has added.

## Set the start command

The **Start command** replaces the image's default command. It's split on spaces and runs without a shell, so quotes and variables like `$HOME` are passed as written. To use shell features, put them in a script and run the script.

## Pass environment variables

Environment variables are passed to the container and shown on the instance's **Details** tab. Values you set override a template's values with the same name.

## Read secrets in your code

Each secret is a read-only file in the container, not an environment variable:

```text
/run/featherless/secrets/<NAME>
```

`FEATHERLESS_SECRETS_PATH` holds the folder's path. Read a secret where you need it:

```bash
export HF_TOKEN="$(cat "$FEATHERLESS_SECRETS_PATH/HF_TOKEN")"
```

Secrets can't be changed after an instance is deployed.

## Next steps

<card-group>
<card icon="i-lucide-box" title="Save it as a template" to="/templates/manage">

Reuse your image and settings.

</card>

<card icon="i-lucide-key-round" title="Registry credentials" to="/get-started/credentials#add-registry-credentials">

Pull private images.

</card>
</card-group>
