Custom images

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

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). 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).
EXPOSEd ports are not published. Use instabox port publish as for any machine. See Public and private ports.
Snapshot limits apply (the free plan keeps ).

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.

Get started

Use cases

Machines

Access

Security

Account

Reference

How an import works

What a machine from an image has

Limits

Reference

`snapshot import` flags

​How an import works

​What a machine from an image has

​Limits

​Reference

​snapshot import flags

How an import works

What a machine from an image has

Limits

Reference

`snapshot import` flags