Install Atelier

Atelier ships as a single self-installing binary. You run it on a Linux node; it sets up k3s, registry, Gitea, and the Atelier control plane in one go.

Before you install

Atelier is early-access software provided “as is”, with no warranty. It makes paid LLM API calls using your own provider credentials and costs can add up — read the full Disclaimer & risks before installing, and set spend alerts on your LLM accounts.

System requirements

Atelier runs a full k3s cluster — control plane, registry, Gitea, storage, and the platform itself — on a single host. Provision a host that meets at least:

Resource	Minimum
CPU	4 cores
RAM	16 GB
Free disk	30 GB
OS	Linux, x86-64 (amd64) or arm64
Access	a non-root user with sudo — installing as root is not supported

You’ll also need outbound HTTPS — the cluster pulls all platform images (atelier-core, atelier-ui, mcp-fetch) directly from ghcr.io/atelier-project/....

The installer runs a preflight check and stops on a clearly-undersized host — its hard floors are 4 CPU cores, ~14 GB RAM, and 30 GB free disk. Provision the 16 GB above rather than the floor: the lower RAM threshold exists only so a nominally-16 GB machine isn’t rejected over firmware-reserved memory. Give it more headroom if you can — the apps you build run on the same cluster.

If you’re deliberately running on a smaller machine or VM (for example a Mac with OrbStack), you can lower the RAM floor with the ATELIER_MIN_RAM_MB environment variable: set it to the number of MB you want, or 0 to skip the RAM check entirely. The disk floor has the same override in ATELIER_MIN_DISK_MB. These are at-your-own-risk escapes for a host the preflight would otherwise reject; the default footprint is still tuned for a 16 GB host, and a genuinely reduced-footprint install profile is on the roadmap.

Installing on a laptop? You’ll need a VM

Atelier installs k3s, so it must run on Linux. macOS and Windows can’t host it directly; run it inside a Linux virtual machine. Atelier ships images and an installer for both amd64 and arm64, so the VM should match your machine’s architecture.

• Apple Silicon Mac (M1/M2/M3…) — run a native arm64 Linux VM. OrbStack is the smoothest option (lightweight, fast, native arm64); Lima or Colima also work well. Use the atelier-install-arm64 installer binary.
• Intel Mac, Windows, or Linux — a standard amd64 Linux VM (for example via Lima, Multipass, or VirtualBox). Use the default atelier-install binary.

Create a VM running a mainstream Linux (Ubuntu Server is a safe choice), sized to the requirements above (4 CPU cores, 16 GB RAM, 30 GB disk), then install Atelier inside it exactly as you would on any Linux host. On Apple Silicon, a native arm64 VM runs Atelier without emulation, so it is fast; avoid emulating x86-64, which is slow.

Storage on a Mac/OrbStack VM: Atelier defaults to Longhorn for storage, but Longhorn can’t attach volumes inside OrbStack/Lima/Colima (the iSCSI data path times out). Install with ATELIER_STORAGE_CLASS=local-path to use k3s’s built-in local-path storage instead, which needs no iSCSI:

ATELIER_STORAGE_CLASS=local-path ./atelier-install-arm64

local-path stores volumes as plain host directories — perfect for a single-node dev VM. (Keep the default Longhorn for a real multi-node cluster.)

One caveat for arm64 clusters: the apps you build are compiled for the cluster’s architecture, so their Dockerfiles need arm64-compatible base images. Most modern official images are multi-arch, so this is rarely an issue.

Air-gapped / offline installs

Fresh installs of v0.9.8-beta and later currently require ghcr.io reach. First-class offline / air-gapped support (load all three images from local tarballs, point the catalog at an in-cluster registry) is planned as a follow-up. If that’s a blocker for you, let us know on Discord.

Prepare the host

Atelier’s storage layer (Longhorn) needs the host’s iSCSI and NFS client packages — open-iscsi and nfs-common. Without open-iscsi and a running iscsid, Longhorn volumes can’t attach and the install stalls partway through.

On Debian / Ubuntu this is automatic. The installer installs the packages and enables the iscsid service for you as one of its steps — there’s nothing to do here.

On other distributions the installer can’t guess the package names, so install the iSCSI and NFS clients yourself before running it, then enable iscsid. For example, on Fedora / RHEL:

sudo dnf install -y iscsi-initiator-utils nfs-utils
sudo systemctl enable --now iscsid

The installer checks for iscsiadm and stops with clear guidance if the iSCSI client is missing on a non-Debian host.

Install

Download the installer, then run it:

curl -Lo atelier-install https://tryatelier.blob.core.windows.net/tryatelier/latest/atelier-install
chmod +x atelier-install
./atelier-install

That’s the whole download — no image tarballs needed. The installer binary is stamped with its own version at build time and templates the matching GHCR tags into the manifests it applies, so a v0.13.0-beta installer brings up a cluster running v0.13.0-beta images.

To pin a specific version, swap latest for the tag (e.g. v0.12.0-beta) in the URL.

The installer runs interactively. It first asks for the portal domain — the hostname the portal is served at — defaulting to atelier.home.arpa; press Enter to accept the default or type your own. It then works through preflight checks, k3s, storage, Gitea, and the control plane on its own.

Installer options

The installer needs no flags for a standard install, but accepts these:

Flag	What it does
--domain <hostname>	Set the portal domain non-interactively (skips the prompt). Subdomains gitea.<domain> and kasten.<domain> are derived automatically.
--with-k10	Also install Kasten K10 for Kubernetes-native backup and restore.
--skip-k3s	Skip the k3s install — use when k3s is already present on the host.
--dry-run	Preview every action without changing anything on the host.
--tui	Use the experimental full-screen TUI instead of the default plain stdout logging.
--config-path <path>	Where to write the generated atelier.toml (default ./atelier.toml).
--upgrade	Upgrade an existing install rather than bootstrapping a new one — see Upgrading.

After install

The installer finishes with an “Atelier is ready” screen showing the portal URL (by default http://atelier.home.arpa/), the Gitea URL, and the generated passwords. Save those — they aren’t shown again.

Make the address resolve

Atelier serves its portal at a hostname — atelier.home.arpa by default — not an IP address. On a home or lab network without custom DNS, that hostname won’t resolve from your browser until something tells it where to point. Three real options, easiest first:

Option 1 — Hosts file (quick start, one or two devices)

On each machine you’ll browse from, add one line that maps both the portal hostname and the Gitea hostname to the IP of the host Atelier is installed on:

<ATELIER_HOST_IP>  atelier.home.arpa gitea.atelier.home.arpa

• macOS / Linux — edit /etc/hosts (e.g. sudo nano /etc/hosts).
• Windows — edit C:\Windows\System32\drivers\etc\hosts as Administrator.

<ATELIER_HOST_IP> is the LAN IP of the machine — or VM — you installed Atelier on. If you installed into a VM, use the VM’s IP; run hostname -I (or ip addr) on that host to find it.

The “Atelier is ready” installer screen prints ready-to-paste hosts-file commands for Linux/macOS and Windows with this node’s IP already filled in — copy the one for whatever machine you browse from.

If you chose a custom domain at the installer prompt (or passed --domain), substitute it above (and gitea.<your-domain>).

Stops working at scale. Per-device, doesn’t help iOS/Android (their hosts file isn’t editable without jailbreak), breaks on OS reinstall. Use this for your first day; switch to one of the options below once it’s annoying you.

Option 2 — Your existing home DNS server (recommended for ongoing use)

If you already run a DNS server on your network — Pi-hole, AdGuard Home, OPNsense/pfSense, unbound on a router, Synology, USG — add one A record (or one wildcard) and every device on the network resolves Atelier hostnames automatically.

Server	Recipe
Pi-hole / AdGuard Home	Settings → DNS → Local DNS Records: atelier.home.arpa → <ATELIER_HOST_IP>. Repeat for gitea.atelier.home.arpa.
OPNsense / pfSense	Services → Unbound DNS → Host Overrides: same pair of records.
dnsmasq (any flavor)	address=/atelier.home.arpa/<ATELIER_HOST_IP> plus the Gitea line, then reload.
Router with custom DNS	Vendor varies; look for “Local DNS” or “Host Overrides”.

Wildcard form *.atelier.home.arpa — supported by most of the above — also covers any per-app subdomains you add later.

This is the option you actually want for a homelab. Five minutes, zero per-device config, works for phones and tablets.

Option 3 — Tailscale Split DNS (off-LAN access from any tailnet device)

If you reach the cluster over Tailscale and want zero per-device config across LAN + mobile + remote, see Tailscale Split DNS guide — it covers the dnsmasq-on-the-node + Split DNS rule recipe end to end.

The trade-off vs. Option 2: Split DNS only helps tailnet members. It’s the right answer when you want phones/laptops to roam off-LAN and still reach the cluster. If everything stays on the LAN, Option 2 is simpler.

Why Atelier doesn’t manage DNS for you

A node-level dnsmasq managed by the installer was considered and parked. DNS infrastructure carries hard availability requirements and conflicts with whatever’s already on :53 on the node (systemd-resolved especially) — owning it means owning a whole new class of “why can’t I reach my cluster” failure mode for the dubious benefit of saving a five-minute click on a UI you already use. The contract (<your-portal-hostname> → <node-ip>, optionally wildcard) is small, stable, and works with every DNS server in this category.

Open the portal

Once the hostname resolves, open the portal URL the installer showed. The first user you create becomes the cluster admin.

Configure a language model (optional)

A fresh install has no LLM configured — and that’s fine. Atelier builds and runs apps without one: every build path (bring a container image, clone a repo, or push your own code) is a deterministic container build, no LLM involved.

An LLM is optional. Add one in Settings → LLM Profiles (your own key — Anthropic, OpenAI, OpenRouter, or a local model — billed by the provider directly) to unlock the assistive features: the Nova operations agent, automatic crash diagnosis, the supervisor’s analysis, and post-build code review. Without one, those features simply stay quiet — nothing errors, nothing blocks.

To have an agent author an app for you from a plain-language description, enable the bundled Build with AI agent (Settings → AI), which drives the platform with its own provider credentials.

Continue with:

• Using Atelier — creating your first app, build pipeline, deploy controls, and what each settings panel does.
• Tailscale access — reach your Atelier instance from outside the LAN.
• Upgrading — when a new release comes out.
• Troubleshooting — common problems and how to diagnose them.

If you get stuck, the Discord is the fastest route to help.