Ability to specify a pre-built custom image instead of building one

[joonas]

I'd love to have the ability to use a pre-built image with all of my project-specific dependencies already installed instead of having moat build the image as part of the launch process.

Does this seem like something that would be of interest for the project to support?

If so, I'd be happy to take a swing at implementing it, but I can appreciate that it might not fit in the scope of what moat was originally intended to do.

[dpup]

Thanks for the suggestion!

A fully custom image (where moat skips its own build entirely) would be difficult to support because moat's runtime depends on a lot of internal setup: a moatuser account at UID 5000, gosu for privilege dropping, our moat-init.sh entrypoint (which handles SSH bridging, agent config staging, Docker socket detection, clipboard setup, and privilege drops), CA cert paths, SSH known hosts, etc. That contract is internal and changes across releases, so custom images would break silently on upgrades.

What could work is a custom base image — you provide the FROM line, and moat layers its infrastructure on top:

# moat.yaml
base_image: myorg/my-project-deps:latest

Moat would generate a Dockerfile like:

FROM myorg/my-project-deps:latest
# --- moat's layers below ---
RUN apt-get install -y gosu ca-certificates ...
RUN useradd -m -u 5000 moatuser ...
COPY moat-init.sh /usr/local/bin/moat-init
ENTRYPOINT ["/usr/local/bin/moat-init"]

Your base image would only need to be Debian-based (moat uses apt-get to install its dependencies). No special users, paths, or tools required — moat adds all of that.

You could still combine it with dependencies: in moat.yaml if needed (e.g., add the Docker CLI on top of your base).

Limitations:

• Base image must be Debian-based (Ubuntu, Debian, etc.) — Alpine/Fedora won't work since moat's layers use apt
• If your image already has a user at UID 5000, there'd be a conflict (we could detect and handle this)
• First build still runs moat's layers on top, but they're small and cache well — rebuilds after config changes would be fast

Would this work for you?

[joonas]

A fully custom image (where moat skips its own build entirely) would be difficult to support because moat's runtime depends on a lot of internal setup: a moatuser account at UID 5000, gosu for privilege dropping, our moat-init.sh entrypoint (which handles SSH bridging, agent config staging, Docker socket detection, clipboard setup, and privilege drops), CA cert paths, SSH known hosts, etc. That contract is internal and changes across releases, so custom images would break silently on upgrades.

That all makes, I was sort of hoping to mirror all of that setup in my own image built (declaratively) using my preferred tooling (melange, apko), but I totally get that could become a completely unnecessary support burden while you're iterating quickly on the project.

What could work is a custom base image — you provide the FROM line, and moat layers its infrastructure on top:

# moat.yaml
base_image: myorg/my-project-deps:latest

Moat would generate a Dockerfile like:

FROM myorg/my-project-deps:latest
# --- moat's layers below ---
RUN apt-get install -y gosu ca-certificates ...
RUN useradd -m -u 5000 moatuser ...
COPY moat-init.sh /usr/local/bin/moat-init
ENTRYPOINT ["/usr/local/bin/moat-init"]

Your base image would only need to be Debian-based (moat uses apt-get to install its dependencies). No special users, paths, or tools required — moat adds all of that.

You could still combine it with dependencies: in moat.yaml if needed (e.g., add the Docker CLI on top of your base).

I think I could work with this, it certainly gets me closer to my ideal state, where the base image is ships with a bunch of utilities I'd love to have available for the agent to use without having to install them on start.

Would this work for you?

So yeah, this would definitely work!

Is this something you'd like help implementing (I'd assumed so given the help wanted label, but worth confirming) or would you prefer to take it on yourself?

I'm good to go either way, but happy to offer my help in case you've got other things to prioritize

[dpup]

If you're down, I'd definitely take a PR :)

[dpup]

I guess we could also have dangerously_set_custom_image as a hidden option, but until the core stabilizes it could mean you're chasing a moving target.

[joonas]

If you are open to it, I would be happy to implement both options as I see utility in both.

I would probably start with being able to specify the base image you want to use (as long as it's of Debian/Ubuntu flavor), because that seems like it'll get the most mileage.

As a follow-up, for folks who are willing to accept that there's likely going to be some churn, the hidden option seems like a nice way to experiment with additional OS that are closer to the environment I would normally run with.

[dpup]

Sounds good!