User Overrides

Per-user configuration via /etc/podspawn/users/<username>.yaml for customizing images, resources, shell, environment, and dotfiles.

User overrides let server admins customize container settings for individual users. Each override file lives at /etc/podspawn/users/<username>.yaml, where <username> matches the SSH username.

If the file does not exist for a given user, no overrides are applied and the server defaults from /etc/podspawn/config.yaml are used.

alice.yaml

bob.yaml

carol.yaml

Full example

# /etc/podspawn/users/alice.yaml
image: ubuntu:24.04
cpus: 4.0
memory: 8g
shell: /bin/zsh
mode: persistent
env:
  EDITOR: nvim
  TERM: xterm-256color
dotfiles:
  repo: https://github.com/alice/dotfiles.git
  install: ./install.sh

The install script runs as the non-root container user. Use sudo for operations that need root privileges. A non-zero exit code from the install script is logged as a warning but does not prevent the session from starting.

Override precedence

When multiple configuration layers specify the same field, the most specific one wins:

Project config (projects.yaml) -- highest priority
User overrides (this file)
Server defaults (/etc/podspawn/config.yaml)

This applies to all fields including mode. For example, if the server default mode is grace-period but a user override sets mode: persistent, that user's sessions will use persistent mode.

For env variables specifically, all layers are merged. If the same key appears in multiple layers, the higher-priority layer wins.

Use cases

Power user with more resources:

# /etc/podspawn/users/bob.yaml
cpus: 8.0
memory: 16g

User who needs a custom image:

# /etc/podspawn/users/carol.yaml
image: ghcr.io/myorg/custom-dev:latest
shell: /bin/zsh

User with dotfiles automation:

# /etc/podspawn/users/dave.yaml
dotfiles:
  repo: https://github.com/dave/dotfiles.git
  install: make install

User Overrides

Full example

Fields

dotfiles

Override precedence

Use cases

On this page