lastlight-overlay

Create & customize a Last Light overlay

Last Light keeps per-deployment customization in a private overlay at instance/, layered over the packaged defaults at startup. The overlay can hold config.yaml, secrets/, and overrides of any asset — workflows/, workflows/prompts/, skills/, agent-context/. An overlay copy shadows the built-in by logical name, so you only fork what you want to change.

These are host-local file operations on the working directory (resolved from --home → LASTLIGHT_HOME → saved serverHome → ~/lastlight).

1. Scaffold or adopt the overlay

lastlight server setup

This scaffolds/adopts the working directory: clones the core repo if needed, then creates a fresh overlay (scaffold + optional private gh repo create) or clones an existing overlay repo — your choice at the prompt. It also symlinks instance/docker-compose.override.yml and saves the working dir for later lastlight server … commands.

Read references/overlay-layout.md for the full directory shape and how the layering/merge rules work (arrays replace, maps deep-merge, overlay wins by name).

2. Tune non-secret config

Edit instance/config.yaml to set managedRepos, and optionally override models, variants, routes, approvals, disabled.*. Secrets stay in instance/secrets/.env (never in config.yaml).

3. Fork built-in assets to customize them

Use lastlight fork — it copies a built-in into instance/ so your edited copy shadows the default. Read references/forking.md for exactly what each fork copies and the editing workflow.

lastlight fork                     # list forkable workflows + agent-context (marks what's already forked)
lastlight fork <workflow>          # copy a workflow YAML + every prompt & skill its phases reference
lastlight fork agent-context       # copy soul.md / rules.md / security.md (the persona)
lastlight fork agent-context soul.md   # just one persona file
#   add --force to overwrite an existing overlay copy; --home <dir> to target a specific working dir

Then edit the copied files under instance/….

4. Apply

• Config-only or overlay-asset edits (committed to the overlay): take effect with lastlight server restart agent — no image rebuild.
• If the overlay is a separate git repo, commit + push there first, then restart.

lastlight server status            # shows forked/overridden assets + version drift
lastlight server restart agent

Done when

The overlay exists with the intended config.yaml and any forked assets under instance/, lastlight server status lists the overrides, and the agent has been restarted to apply them. Report which assets were forked and where they live.