Internals

This page describes workspace metadata, project identity, and stored state. See How it works for the architecture.

Workspace metadata

Each para-<name> container stores its project, routes, and domain in Incus configuration, and its IP in the eth0 device configuration. para reads this metadata directly with incus list.

• para ls requires a reachable Incus daemon.
• The generated Caddyfile includes workspaces from every project on the machine, regardless of which project generated it.

The shared home volume

Each project gets one Incus custom volume (security.shifted=true, which is what lets one volume attach to many unprivileged containers with correctly shifted ownership), mounted in every workspace of that project at /para/shared. Your provision hook decides what goes on it.

It is per-project by default (para-home-<project>); point several projects at one PARA_VOLUME to share auth across them. para rm never touches it.

Workspace names are machine-global

A name maps to one para-<name> container, so sh/rm/down address it by bare name from anywhere with no ambiguity. para up <name> refuses a name already owned by another project rather than adopting its container, and it names the owner.

Project discovery

Finding the .paraspace/ directory is only a file lookup. A project's identity is PARA_PROJECT_NAME, so moving or renaming the checkout never orphans its workspaces.

Where state lives

What	Where
User config	${XDG_CONFIG_HOME:-~/.config}/para/config
Generated Caddyfile	${XDG_STATE_HOME:-~/.local/state}/para/Caddyfile
Caddy pidfile	${XDG_STATE_HOME:-~/.local/state}/para/caddy.pid
Workspace identity	the container's own Incus config
Shared home volume	Incus volume para-home-<project>

para config edit creates the user config from a commented template on first use. Later runs open the existing file for you to edit.