File layout

Everything Monoceros creates lives under one home directory, ~/.monoceros ($MONOCEROS_HOME). Configs, the materialized containers and backups all sit there by convention - which is why commands work from any directory. This page shows what is where.

New to Monoceros? Start with Installation.

Note

acme is just a sample workbench name - it’s whatever you passed to monoceros init. Substitute your own throughout.

The layout

• Directory~/.monoceros

  • Directorycontainer-configs

    • acme.yml the source of truth for the acme workbench
    • acme.env its secrets (never committed)
  • Directorycontainer

    • Directoryacme the materialized dev container (1:1 with the config; build output)

      • .devcontainer generated devcontainer.json, compose, post-create, features
      • projects your cloned repos and apps (an app may carry .monoceros/launch.json)
      • home persistent tool state and logins, kept across rebuilds
      • data service data (Postgres, MySQL, …) when the yml declares services
      • logs apply transcripts, plus <app>/<target>.log for long-running app servers
      • .monoceros container state: state.json, git identity, commands.md, run/<app>/<target>.pid
      • AGENTS.md AI-tool briefing (CLAUDE.md imports it)
      • acme.code-workspace the VS Code workspace file
  • Directorycontainer-backups one folder per remove, each holding the container plus its yml + env

    • acme-2026-06-02T22-29-16-300Z
  • Directoryssh attach helpers for monoceros open / IDE attach (ADR 0022)

    • config.d per-workbench SSH config includes
    • exec-acme.sh the attach helper for acme
  • Directorytraefik

    • dynamic per-workbench proxy route files (the *.localhost hostnames)
  • monoceros-config.yml optional global defaults
  • .machine-state.json internal machine-local bookkeeping (e.g. upgrade prune)

One config, one container

Each config maps to exactly one container: container-configs/<name>.yml becomes container/<name>/. That is why the working directory never matters - every command addresses a workbench by name:

monoceros apply acme
monoceros shell acme

Tip

You never edit container/<name>/ by hand. It is regenerated from the yml on every apply - treat it as build output. The yml is the source of truth.

Backups, and what is shared

container-backups/<name>-<timestamp>/ is a directory written on every monoceros remove (backup is on by default): a full copy of the container plus the <name>.yml and <name>.env it was built from, so monoceros restore <path> can bring it back.

traefik/ and ssh/ are machine-wide, not per-workbench. One Traefik proxy routes every workbench’s *.localhost hostnames (see The Monoceros proxy), and ssh/ holds the per-workbench attach helpers used by monoceros open and IDE attach. Both are managed for you - you never edit them by hand.