nixos-config

Declarative, reproducible computing environment with NixOS and home-manager

한국어 문서

---

Overview

A comprehensive NixOS configuration for building identical computing environments anywhere, designed for seamless collaboration between humans and AI agents.

Goals

• Reproducibility: Declarative configuration as code
• Scalability: From Oracle Cloud Free Tier VMs to local machines
• Consistency: Regolith Linux i3wm workflow with Doom Emacs integration
• Transparency: AI-agent friendly declarative systems

---

Features

Window Manager

i3wm (default)

• Regolith 3 style: gaps, borders, custom colors
• py3status + Emacs org-clock integration
• Declarative config via home-manager
• picom compositor

GNOME (specialisation)

• Alternative desktop environment
• Boot menu selection

Emacs Integration

• dotdoom-starter integration
• mu4e email client (mbsync)
• org-mode task tracking on status bar
• edit-input: Edit web forms with Emacs
• rofi-pass integration

Development Environment

Modular per-language configs:

• Python, Nix, C/C++, LaTeX, Shell, Elisp
• Tools: gh, lazygit, aider-chat, direnv

Local AI (ThinkPad)

Ollama with Vulkan on AMD Radeon 780M (Mesa RADV). Package/service is kept, but boot auto-start is disabled; start manually only when local embedding is needed.

Item	Value
Package	ollama-vulkan (auto-selected by acceleration = "vulkan")
GPU	AMD Radeon 780M (RADV PHOENIX)
Recommended model	qwen3-embedding:4b (Q4, 2.5GB, 2560-dim)
Endpoint	http://127.0.0.1:11434
Keep-alive	OLLAMA_KEEP_ALIVE=10m — idle 10분 후 VRAM 언로드

History: 2026-04-15 추가 → 04-17 revert (always-on 정책) → 05-07 재도입 (andenken/semantic-memory 세션 임베딩 빈도 ↑, OpenRouter 보조) → 05-21 자동 시작 비활성 (현재 미사용, 수동 시작 유지).

Manual use:

sudo systemctl start ollama
ollama pull qwen3-embedding:4b

Docker Services (Oracle VM)

Self-hosted services running on Oracle Cloud ARM VM:

Service	URL	Description
Caddy	reverse proxy	Auto HTTPS (Let's Encrypt) for all services
Remark42	comments.junghanacs.com	Self-hosted comment system
Mattermost	chat.junghanacs.com	Team chat + OpenClaw integration hub
OpenClaw	localhost:18789 (SSH tunnel)	AI assistant gateway
Umami	self-hosted	Privacy-focused web analytics

OpenClaw features:

• Telegram bots: personal (main agent) + 힣(glg) digital garden guide
• Mattermost channel: @openclaw bot in chat.junghanacs.com
• Multi-agent routing: each bot → independent agent with own workspace
• Custom Dockerfile: gh CLI, ripgrep, fd, jq, tree, skills support
• claude-cli native (2026-05-26): main/mini agents run on the claude-cli provider — OpenClaw spawns Anthropic's official claude Code CLI directly (via @anthropic-ai/claude-code package). Uses the host's Claude Pro/Max OAuth (~/.claude/.credentials.json), so usage draws from the Max 20x rate tier instead of the per-token extra usage pool that third-party harnesses get throttled to. Comes with 1M context window (same as the desktop Claude Code surface), workspace-aware skill discovery, and shared session JSONLs under ~/.claude/projects/. See AGENTS.md §3 → claude-cli provider for the full mechanism.
• ACP route: bbot (Claude opus-4-7) / gemini agents run through the pi-shell-acp OpenClaw plugin — third-party native ACP plugin path with its own pi backend (not @openclaw/acpx). bbot/gemini are candidates for migration to claude-cli after further validation. See AGENTS.md §2 → ACP route for the architectural position.
• Web UI (Control UI): SSH tunnel ssh -N -L 18789:127.0.0.1:18789 oracle → http://127.0.0.1:18789/
• Config managed in private repo: openclaw-config (Oracle VM agent workspace)

run.sh shortcuts (from laptop):

./run.sh  # then:
# t) Start OpenClaw SSH tunnel + dashboard
# r) Restart Oracle Docker services
# s) Oracle Docker service status

See docker/ for compose files and setup guides.

home-manager Modules

users/junghan/modules/
├── shell.nix, i3.nix, dunst.nix, picom.nix
├── emacs.nix, email.nix, fonts.nix
└── development/  # Per-language

Before: 341 lines → After: 118 lines (-65%)

Fortune

Custom fortune data with Kevin Kelly's life advice:

• fortunes/advice/ — Excellent Advice for Living, 68 Bits, 99 Additional Bits
• Deployed to ~/.fortunes via home-manager

---

Installation

Device Profiles

Profile	Device	CPU	Usage
thinkpad	ThinkPad P16s Gen 2	AMD Ryzen 7 PRO 7840U	Work laptop
laptop	Samsung NT930SBE	Intel i7	Personal laptop
nuc	Intel NUC	Intel i7 4-Core	Home server
oracle	Oracle Cloud VM	ARM (Ampere)	Remote server (Free Tier) + Docker services

Prerequisites

• NixOS 25.11+
• Flakes enabled

Quick Start

git clone https://github.com/junghan0611/nixos-config.git
cd nixos-config

# Edit configuration
vim hosts/nuc/configuration.nix

# Build
sudo nixos-rebuild switch --flake .#nuc

Oracle Cloud VM

Based on mtlynch.io Oracle Cloud NixOS Guide (with modifications)

See templates/nixos-oracle-vm/

---

Usage

# Rebuild
sudo nixos-rebuild switch --flake .#nuc

# Update
nix flake update

# Email sync
mbsync -a

Keybindings (i3)

Key	Action
Mod+d	rofi launcher
Mod+p	rofi-pass
Mod+i	edit-input (Emacs)
Mod+c	Toggle picom
Mod+n	Close notification

---

Philosophy

Reproducibility: The Blacksmith's Forge

"A computer is not a black box—it's the blacksmith's forge. The master controls the tools, the apprentice (agent) assists, but tool selection remains under the master's command."

Core Insight: Reproducible computing environments are essential for human-AI collaboration.

Key Principles:

1. Reproducibility = Trust

Traditional OS:
  - "What's installed?" → Unknown
  - "What version?" → Unclear
  - Agent: Guesses, trial-and-error

NixOS:
  - configuration.nix = Single source of truth
  - Agent: Precise, reproducible actions

2. Master's Control

Blacksmith (Human):
  - Selects tools (nixos-config)
  - Controls environment
  - Final judgment

Tools (Computer):
  - Keyboard, editor, languages
  - Extended body

Apprentice (AI Agent):
  - Assists, but doesn't choose tools
  - Tool selection = Master's domain

3. Scale: Desktop → Data Center

Same syntax, infinite scale:
  - Desktop: configuration.nix
  - Server: configuration.nix (same pattern)
  - Cluster: flake.nix (same philosophy)

→ Learn once, apply everywhere

4. Transparency for Agents

What agents need to know:
  - Your tools? (environment.systemPackages)
  - Your editor? (programs.emacs)
  - Your languages? (pkgs.python311)

nixos-config provides:
  - Complete environment specification
  - Exact versions (flake.lock)
  - Full transparency

→ Agents generate precise, working code

Read More: NixOS: Reproducibility and the Blacksmith's Philosophy

---

References

Inspiration

• hlissner/dotfiles - Doom Emacs maintainer's NixOS config
• ElleNajt/nixos-config - home-manager patterns
• mtlynch.io Oracle Cloud NixOS - Oracle VM guide (modified for templates/)

Related

• dotdoom-starter - My Doom Emacs config
• openglg-config - Companion repo. Portable service stack (Docker Compose: Caddy/Authelia/Postgres/Metabase/...) plus a portable home-manager (home/) that lands on any Debian/Ubuntu host. Use this nixos-config when you own the host; use openglg-config when you only get the user shell on top of it (rented VPS, AVF VM, foreign machine).

---

Documentation

Operator Docs (handbook)

운영자(사람·에이전트)가 이 repo에서 일할 때 읽는 핸드북. 시간축으로 셋, 디바이스축으로 둘이 분업한다 — 과거는 ROADMAP, 현재는 AGENTS, 미래는 NEXT. 디바이스별 상세는 필요할 때만 꺼내본다.

시간축:

• AGENTS.md - 현재 운영 상태 SSOT (디바이스 공통 baseline). 디바이스 식별 + 공통 명령 + 디바이스 핸드북 라우팅. "지금 어떤 상태인가"만 답한다.
• NEXT.md - 다음 할 일 (휘발성 후속). 미완 작업과 검증 항목. 끝나면 지우고, ✅ 완료분은 ROADMAP으로 흘려보낸다.
• ROADMAP.md - 버전·업그레이드·운영 결정 이력 SSOT. OpenClaw 5.2→5.27 업그레이드 연혁, claude-cli 전환, 정공법들. "어떻게 여기까지 왔는가"를 답한다.

디바이스축 (필요할 때만):

• ORACLE.md - Oracle / OpenClaw 운영 핸드북. ownership, 봇 model routing, env/secret SSOT, 업그레이드/restart, skills deploy, 함정. oracle 디바이스 또는 OpenClaw 작업일 때만 연다 — 다른 디바이스엔 불필요.
• THINKPAD.md - ThinkPad 로컬 AI (Ollama Vulkan policy). thinkpad 작업일 때만.
• docs/openclaw-gotchas.md - 함정 카탈로그 (활성/비활성/역사). 다음 세션이 또 밟을 것.

Configuration Guides

• CHANGELOG.md - NixOS 시스템 구성 변경 이력 (패키지·모듈·키바인딩, Keep a Changelog 형식) — OpenClaw 운영 이력은 ROADMAP.md로 분리
• Package Installation Guide - How to add packages (for AI agents and users)
• External Packages - Non-NixOS 패키지 SSOT (pnpm/harness/gog/uv) — 설치·버전체크 스크립트 (run.sh e)/E)에서 호출)
• Keybindings Reference - i3 keybindings

Docker Service Guides

• Remark42 Setup - Comment system deployment
• Mattermost Setup - Team chat + bot integration
• OpenClaw Setup - AI gateway deployment (multi-agent, Telegram + Mattermost)
• Umami Setup - Web analytics deployment

Analysis and Strategy

See docs/ (denote format):

• Analysis documents
• Integration plans
• Strategy guides

---

License

MIT License

Author

Jung Han (junghanacs)

• 힣's Digital Garden
• @junghan0611