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

# Custom images

> Turn a Docker or OCI image into a snapshot, then start machines from it.

Import a Docker or OCI image from a registry as a snapshot, then start machines from it.

```bash theme={null}
instabox snapshot import node:16-buster --name node16     # a few minutes
instabox create --name dev --snapshot node16
instabox exec dev -- node -v                              # v16.20.2, the image's
```

The result is a snapshot like any other (see [Snapshots](https://instabox.sh/docs/machines/snapshots.md)). Import works on every
plan.

## How an import works

`snapshot import` starts a throwaway machine and pulls the image there with Docker. It lays the image's
files over the machine's own, then restarts the machine to check that it boots and answers. Last, it
saves the machine as a snapshot and deletes the throwaway machine. The throwaway machine is an
`agent-browser` one and counts while it runs.

## What a machine from an image has

* **The image's files win**: its programs, libraries, `/usr/local`, `/opt`, `/root`, `/home`, `/app`
  and its users.
* **Its `ENV`** reaches every session (exec, SSH, login shells), and the directories its `PATH` adds
  come first.
* **Its `ENTRYPOINT` and `CMD`** run as the `instabox-image.service` systemd unit, in its `WORKDIR`, as
  its `USER` (root when unset), restarted on failure. Read the output with
  `journalctl -u instabox-image.service`. `--no-entrypoint` leaves the unit out.
* **What makes it a machine stays**: systemd, sshd, sudo, the machine's user (UID 1000, so the image's
  user with that ID, such as `node`, is that user), `/data` and the shared libraries the machine's own
  programs load.
* `/etc/instabox/image.json` records the image's reference, digest and config.

## Limits

* `linux/amd64` images only.
* An image you built locally must be pushed to a registry first (`docker push ghcr.io/you/img:tag`).
* `EXPOSE`d ports are not published. Use `instabox port publish` as for any machine. See
  [Public and private ports](https://instabox.sh/docs/access/ports.md).
* Snapshot limits apply (the free plan keeps 5).

> [accordion] Init, apt, and the C library
>
> A machine runs systemd as its init. The image's own init (tini, s6) is present but not run, only its
> `ENTRYPOINT` and `CMD`. `apt` manages the machine's own system. The image's packages are there as
> files, but `apt` cannot see or remove them. Debian and Ubuntu images, old ones too (Debian 10 buster),
> run on the machine's newer C library. Alpine (musl) images work best-effort.

## Reference

### `snapshot import` flags

| Flag | What it does |
| - | - |
| `--registry-username U` | A private image, with `INSTABOX_REGISTRY_PASSWORD` set or `--registry-password-stdin`. The password is not kept in the snapshot. |
| `--keep-builder` | Keep the throwaway machine, also after a failure, to look around with `instabox ssh`. |
| `--no-verify` | Skip the restart check. |
| `--timeout` | Bound the pull and the overlay (default `30m`). |
| `--json` | Print the result as one object. |