Configuration

outpost needs no configuration to start — the defaults work. Everything is tunable through environment variables, optionally set once in a config file.

The config file

On startup, outpost sources ~/.config/outpost/config (override the path with OUTPOST_CONFIG) if it exists. It’s plain shell — set any of the variables below once:

OUTPOST_PROJECTS_DIR="$HOME/code/outpost-projects"
OUTPOST_TZ="Europe/Amsterdam"
OUTPOST_MEMORY="6g"
export EDITOR=hx

Variables

Variable	Default	What it does
`OUTPOST_PROJECTS_DIR`	`~/outpost-projects`	Where your project configs live (your own repo).
`OUTPOST_DIR`	resolved from the symlink	The tool repo root.
`OUTPOST_DOTFILES_DIR`	shipped `shared/home`	Dotfiles baked into the base image — point at your own.
`OUTPOST_TEMPLATES_DIR`	`<tool>/templates`	Templates for `outpost projects new`.
`OUTPOST_TZ`	`UTC`	Base-image timezone (applied on `outpost base`).
`OUTPOST_ENGINE`	`docker`	Container engine binary (e.g. `podman` — see the caveat below).
`OUTPOST_MEMORY`	(off)	Per-container memory cap (e.g. `4g`).
`OUTPOST_CPUS`	(off)	Per-container CPU cap (e.g. `4`).
`OUTPOST_SHM_SIZE`	(off, 64MB default)	Raise `/dev/shm` (e.g. `1g`) — headless Chromium/browser tests can exhaust the 64MB default and crash.
`OUTPOST_PIDS_LIMIT`	`4096`	Fork-bomb guard.
`OUTPOST_READONLY`	(off)	Run the container with a read-only rootfs (`--read-only --tmpfs /tmp --tmpfs /run`); named volumes stay writable. Opt-in hardening.
`OUTPOST_AUTO_COMMIT`	(off)	Auto-commit the projects repo on `projects new`/`rm`.
`OUTPOST_STATE_DIR`	`$XDG_RUNTIME_DIR/outpost`	Host-only state (the agent bridge socket). Falls back to `/tmp/outpost-<uid>` when `$XDG_RUNTIME_DIR` is unset (headless/cron logins).
`OUTPOST_SSH_HOST`	`dev-box`	The SSH host alias printed in the `ssh -L` hints from `outpost ports`. Set it to your own `~/.ssh/config` alias.
`OUTPOST_DASH_SESSION`	`boxes`	tmux session name for `outpost dash`.
`OUTPOST_ALLOW_UNSAFE_COMPOSE`	(off)	Bypass the host-escalation lint on `outpost up`.
`OUTPOST_SKIP_BRIDGE`	(off)	Skip the git agent bridge (observe-only sessions/tests).
`EDITOR` / `VISUAL`	first of `hx`/`nvim`/`vim`/`vi`/`nano`	Editor for `outpost projects edit` (host-side).

OUTPOST_ENGINE=podman is untested. outpost calls the engine like Docker (docker run, docker compose, docker volume, …), and a podman shim exposes the same surface, but rootless Podman and its compose provider have not been verified against outpost’s hardening flags, the socat agent bridge, or the compose lint. Treat it as experimental — Docker CE is the supported engine.

Using your own dotfiles

The base image ships tasteful, neutral default dotfiles so a fresh container has a pleasant terminal out of the box. To use your own, keep them in their own repo (the same dotfiles you use on your laptop work great), clone them on the host, and point OUTPOST_DOTFILES_DIR at them — typically in your config file:

git clone [email protected]:you/dotfiles.git ~/dotfiles
echo 'OUTPOST_DOTFILES_DIR="$HOME/dotfiles/home"' >> ~/.config/outpost/config
outpost base    # rebuild the base image with your dotfiles

Your files are overlaid on top of the shipped defaults: your versions win where they exist, and the tool-integral bits the defaults carry survive — the just tunnel recipes (.config/just/justfile) and the .bashrc PATH/fnm/outpost-sshd hooks. If you ship your own .bashrc, keep (or re-source) those hooks, or node/fnm and the Mutagen helper won’t initialise.

Per-user git identity belongs in ~/.config/git/local.gitconfig inside the container — copy the shipped local.gitconfig.example and fill it in (see Git & SSH).

AI agents default to approval-first — except opencode. The shipped Claude (defaultMode: default) and Codex (approval_policy = "untrusted") configs ask for approval. The shipped opencode config is only a $schema line with no permission block, so opencode runs its own built-in defaults unless you add one. Because the container is a hardened sandbox, you can also run any of them fully autonomous — see Running agents autonomously for the opt-in.