Your whole system, running locally
Multi-service local development environment. Orchestrate services, infrastructure, and reverse proxying with a single lo1 up.
lo= loopback interface,1from::1(IPv6 loopback)
lo1-demo.mp4
| Package | Description |
|---|---|
@lo1/cli |
CLI application — lo1 init, lo1 up, lo1 down, lo1 status |
@lo1/sdk |
Plugin SDK — types, config schemas, and utilities for plugin authors |
@lo1/plugin-celerity |
Celerity plugin — blueprint-driven compose, provisioning, and seeding |
| Dependency | Version | Purpose |
|---|---|---|
| Node.js | 24+ | CLI runtime |
| Docker | 20.10+ | Container services, infrastructure, reverse proxy |
| Git | 2.x | Repository cloning (lo1 init) |
Docker Compose v2 is included with Docker Desktop (macOS/Windows) and modern Docker Engine (Linux).
lo1 runs on macOS, Linux and Windows. On Windows, run it from PowerShell with Docker Desktop. Inside WSL 2, lo1 sets up the hosts file and certificate authority in Linux only, so browsers on Windows won't reach or trust the workspace.
On Linux with TLS enabled, also install certutil, which lo1 uses to add its certificate authority to Chrome and Firefox. Those browsers don't read the system store:
sudo apt install libnss3-tools # Debian, Ubuntu
sudo dnf install nss-tools # Fedora
sudo pacman -S nss # Archlo1 runs on Node.js 24 or later. You can install it with npm, pnpm, Yarn or Bun, but Node.js is still needed: the lo1 command runs on Node whichever package manager installed it.
# Install globally (pick your package manager)
npm install -g @lo1/cli # npm
pnpm add -g @lo1/cli # pnpm
yarn global add @lo1/cli # Yarn
bun install -g @lo1/cli # Bun
# Initialize a workspace (clones repositories, sets up infrastructure)
lo1 init
# Start all services
lo1 up
# Check service status
lo1 status
# Stop everything
lo1 downDefine your workspace in lo1.yaml:
version: "1"
name: my-project
services:
api:
type: service
path: ./services/api
port: 3000
command: bun run dev
frontend:
type: app
path: ./services/web
port: 5173
command: bun run dev
proxy:
tld: local
tls:
enabled: trueThe @lo1/sdk package publishes a JSON Schema for IDE autocompletion and validation.
proxy.tls.mode picks how the proxy gets its certificates.
Caddy's built-in CA issues the certificates, and lo1 up installs the root into
the host trust store. Only the machine running lo1 trusts them, so other devices
on the LAN will see certificate warnings.
- macOS: your login keychain, which may show a password dialog the first time.
- Linux: the system store (needs
sudo), plus Chrome's and Firefox's stores whencertutilis installed. - Windows: your user's certificate store, after Windows asks you to confirm the "Caddy Local Authority" certificate.
On Windows, writing the hosts file needs administrator rights, so unless
PowerShell is running as Administrator, lo1 up shows a UAC prompt.
Caddy obtains and renews publicly trusted certificates itself over the DNS-01
challenge, so every device on the network accepts them with nothing to install.
Because the stock Caddy image cannot solve DNS challenges, lo1 rebuilds the
proxy image with the matching caddy-dns
provider module.
proxy:
tld: dev # a real domain you control, e.g. my-project.dev
tls:
enabled: true
mode: acme
acme:
provider: cloudflare # any caddy-dns provider name
tokenEnv: CF_API_TOKEN # host env var holding the DNS API credential
email: me@example.com # ACME account email
domains: ["*.my-project.dev"] # names ACME should cover
ca: letsencrypt # or "staging" while you are testing
resolvers: ["1.1.1.1"]
propagationTimeout: 5mThe credential is passed to the container by name (${CF_API_TOKEN}), so the
secret never lands in a generated file. Export it in the shell you run lo1 up
from. A .env file is not enough on its own, because lo1 checks the process
environment and fails before Docker Compose would interpolate one.
domains declares which names ACME issues for. Hosts covered by a wildcard are
folded into a single site block, so Caddy orders one certificate for the whole
set rather than one per service, and adding a service needs no new issuance.
Anything that does not match domains falls back to the internal CA, which is
what lets a workspace mix the two. A service given
proxy.domain: api.local.example.com gets a publicly trusted certificate, while
the default api.<workspace>.local host keeps using Caddy's local CA, since no
public CA can issue for a .local name. Leaving domains empty lets ACME cover
every site, which only works if every host is a public name.
Renewal is entirely Caddy's job. It renews in the background and reloads itself, so there is no external ACME client to run and no reload hook to wire up.
Other providers work the same way. Set provider to route53, digitalocean,
azure, or any other name matching a module in the
caddy-dns org. Providers needing more than a
single credential take extra environment variables through env: [...] and
nested directive options through options: {...}. Use module to override the
Go module path when you need a specific version.
Reaching the domains from other devices. Real certificates are only half of
what is needed, because the other devices also have to resolve those names to
this machine. Point A records for the domain, or for the wildcard, at this
machine's LAN IP in the DNS zone you already control, or add the hosts to your
router's DNS. lo1's /etc/hosts management only covers the machine running it.
See CONTRIBUTING.md for development setup, commands, and commit conventions.