How It Works

Exodus is not a black box. Here's exactly what happens when you deploy.

Clean vs Dirty Builds

Mode	Source	Use Case
Clean (default)	git archive HEAD	Production deploys. Only committed files. Reproducible.
Dirty (--dirty)	Working directory	Testing local changes before committing.

# Clean build (default) - uses latest git commit
exodus build

# Dirty build - includes uncommitted changes
exodus build --dirty

INFO

Clean builds guarantee reproducibility: same commit = same build. Use --dirty only for testing.

Deployment Flow (Hybrid Build)

Local                           Server
  │                               │
  ├──── 1. SSH Connect ──────────►│
  ├──── 2. Prepare Source         │
  ├──── 3. Install Deps           │
  ├──── 4. Next.js Build          │
  ├──── 5. Stage Artifacts        │
  ├──── 6. Upload Bundle ────────►│
  │                               ├──── 7. Docker Build (minimal)
  │                               ├──── 8. Start Container
  │                               ├──── 9. Health Check
  │                               ├──── 10. Update Caddy
  │                               ├──── 11. Stop Old Container
  │                               │
  ◄─────────── Done ──────────────┤

Step by Step

Step	What Happens
SSH Connect	Secure connection using your stored credentials
Prepare Source	git archive HEAD (clean) or copy working dir (dirty)
Install Deps	pnpm install --frozen-lockfile (or npm/yarn/bun)
Next.js Build	Runs next build locally with standalone output
Stage Artifacts	Collects .next/standalone, .next/static, public
Upload Bundle	Compressed tarball streamed to server
Docker Build	Minimal image: copies pre-built artifacts + installs runtime deps
Start Container	New container launched with env vars injected
Health Check	Waits for app to respond
Update Caddy	Routes traffic to new container (zero-downtime)
Stop Old	Previous container stopped, old images pruned

Security Model

WARNING

Your credentials and secrets never leave your machine unless you explicitly push them.

Data	Location
SSH credentials	~/.config/exodus/config.yml (local only)
Server secrets	/opt/exodus/secrets/{project}/.env (on VPS)

Server Setup

First exodus connect provisions your VPS:

System

• Updates all packages
• Installs base tools (curl, git, jq, htop)
• Creates 2GB swap file (prevents OOM crashes on 1GB VPS)
• Creates /opt/exodus directories

Security

• UFW firewall (only ports 22, 80, 443 open)
• Fail2Ban (auto-bans IPs after failed SSH attempts)

Docker

• Docker Engine with log rotation (max 10MB)
• exodus_network bridge network
• Daily auto-prune cron job

Caddy

• Reverse proxy with automatic SSL via Let's Encrypt

Build Methods

exodus build --method <method>

Method	Description
auto	Auto-detect best method (default)
local	Build locally, push image to server
hybrid	Build locally, push tarball, load on server
remote	Upload source, build entirely on server