docs: align wiki to the Karafka writing style
Style-only pass across 39 pages: reduce decorative bold to scannable labels and
callouts, Title Case headings, expand contractions, present tense, US English,
cut filler and --- separators, tag code fences. Commands, code, config,
COI_* env vars, paths, URLs, wiki links/anchors, and tables left unchanged.
docs: rebrand to Coi (drop all-caps COI; Coi primary, coi command)
COI -> Coi across all pages; sidebar + Home first-mention use "Coi (Code on Incus)".
Preserved: COI_* env-var names and the literal "# COI Sandbox ..." context markers
(they document the actual on-disk marker text). Lowercase coi commands unchanged.
Align wiki with 0.11.1: OrbStack guide, filesystem-first UID mapping, dir-pool health warning, idempotent context injection, version-fix note
- macOS Setup Guide: OrbStack is now a first-class documented option
(setup steps, how COI handles the FUSE-backed macOS share via
raw.idmap, the OrbStack >=2.2.2 silent-breakage background, storage
notes); 'How It Works' rewritten around the v0.11.1 filesystem check
with the reactive fallback; Manual Override reframed as rarely
needed; Colima instructions now install Incus from Zabbly (Ubuntu's
6.0 is below the required 6.1).
- Configuration/Architecture/File-Transfer/FAQ pages: UID-mapping
mechanism descriptions updated (auto-selected shift vs raw.idmap),
disable_shift comment rewritten, Colima-only framing widened to
Colima/Lima/OrbStack.
- System Health Check/Troubleshooting/Best Practices/Getting Started/
Linux Setup Guide: dir-pool driver warning documented (detection,
cost, fix), example output shows the new 'pool (driver)' label,
manual-setup example no longer recommends a dir pool, Zabbly note
reframed around the automatic raw.idmap recovery, #673 version/update
known-issue note added.
- Troubleshooting/Supported-Tools/Profiles: idempotent marker-delimited
sandbox-context injection documented incl. auto-healing of bloated
files; tool interface snippets synced (AlwaysSetupConfig, full effort
level list).
- nftables internals: NFT monitoring is disabled by default.
- Nav (Home/Sidebar/Footer): 0.10.1->0.11.0 migration links; FAQ count
fix; IPv6 host-side blocking wording.
Post-release audit: fix ~50 inaccuracies vs v0.10.0 behavior
Triple-check audit of every page against the released binary and code.
Systemic: firewalld -> nftables (stale since the v0.9 #405 migration) across
Network-Isolation, Linux-Setup-Guide, Architecture-and-Security-Model,
Getting-Started, Home, FAQ*, Best-Practices, Troubleshooting,
System-Health-Check — including the whole 'Firewalld Setup' section that
told users to create the wrong sudoers file (/etc/sudoers.d/coi-firewalld);
now documents nftables + /etc/sudoers.d/coi-nft (matching install.sh), the
real error string, use_sudo=false, and the real orphan classes and health
check names. Distro-default-firewall tips (Fedora/openSUSE) kept but
decoupled from COI's own mechanism.
Audit-Log: JSONL examples and field reference rewritten to the real
ThreatEvent shape (id/timestamp/level/category/title/description/evidence/
action — the old examples used fields that never existed); COI_AUDIT_*
tuning corrected (host env is not forwarded; use incus config set).
Security-Best-Practices: default protected-paths table matches the 0.10
set; protection-weakening keys documented as trusted-scope only (untrusted
project configs are sanitized); #533 linked-worktree support and #556 git
identity seeding documented.
Command usage: coi update core --check (not coi update --check), coi info
<session-id>, coi persist <container>, coi run's interactive build prompt,
stop-before-publish in the image workflow, --slot pinning.
Config accuracy: memory enforce default is soft; effort_level accepts
low/medium/high/xhigh/max/auto (default unset); [limits.disk] values are
I/O rates not storage caps (Best-Practices example fixed); protected_paths
default list completed; threat levels are INFO/WARNING/HIGH/CRITICAL.
Navigation: 0.9->0.10 migration section linked from Home, sidebar, and
footer; broken FAQ prompt-injection anchor retargeted.
docs: fix bugs and fill content gaps from re-analysis
Bug fixes:
- Linux-Setup-Guide: fix usermod command (incus,incus-admin not
'incus incus-admin $USER' which passed incus-admin as a username)
- Image-Management: clarify Best Practices item 4 — coi image publish
captures filesystem state, not process memory; stateful = snapshots only
Content improvements:
- Home.md: add one-sentence description of what COI is before the callout
- Tmux-Automation: replace non-deterministic sleep-based CI examples with
polling helpers; add Note callout explaining why fixed sleeps are unreliable
- FAQ.md: expand Troubleshooting Quick Links from 2 to 7 entries covering
container pause/kill, privileged=true error, Docker Compose, DNS build issues
- Resource-and-Time-Limits: add prose section explaining what each limit
actually does (CPU enforce/priority, memory hard vs soft, swap semantics,
disk I/O cgroup blkio, tmpfs, runtime auto-stop)
- File-Transfer: add UID shifting note explaining automatic ownership mapping
and when to chown after pushing to system paths
- Security-Monitoring: clarify [monitoring] vs [monitoring.nft] as two
independent subsystems with separate prerequisites
- Configuration: note that forward_env is top-level in profiles vs under
[defaults] in main config
- Migration-Guide: add 4 more entries from Troubleshooting content (bool
pointer fix, settings.json deep merge, Docker Compose three-step launch,
EXDEV session save fix, UID/GID remapping)
docs: add Architecture, Getting-Started, and split FAQ into categories
- Add Architecture-and-Security-Model.md — conceptual "why COI" page
covering the threat model, all defense layers, architecture diagram,
and what COI does/does not protect against
- Add Getting-Started.md — step-by-step first-session walkthrough
covering install, coi build, coi shell, resume, parallel sessions,
and persistent mode, with links to next steps
- Split FAQ.md into three category files:
- FAQ-Platform-Comparisons.md (6 questions + comparison table)
- FAQ-Security-and-Trust.md (5 questions)
- FAQ-Setup-and-Operation.md (9 questions)
- Rewrite FAQ.md as a pure index with category table + troubleshooting
quick links
- Update Home.md: new Getting-Started and Architecture nav section,
point new-user callout to Getting-Started, list FAQ category pages
docs: quick-win formatting pass across all wiki pages
- Add H1 title to all 16 pages that were missing one
- Add FAQ question index with 22 anchor-linked entries grouped by category
- Add See Also section to all 19 pages with curated cross-links
- Upgrade three high-risk inline warnings to blockquote callouts:
allow_local_network_access, mount parent dir, disable_protection
docs: replace em dashes with hyphens across all wiki pages
docs(faq): add Q&A on agentic development process
Explains that COI is partially built using AI coding agents and is
often developed inside COI itself (dogfooding).
Reduce documentation duplication and improve structure
- Deduplicate Sandbox Context: Configuration.md now links to Supported-Tools.md
instead of repeating the full auto-context section
- Move mount how-to from FAQ to Configuration.md "Mounting Additional Files" section;
FAQ entry replaced with short pointer
- Add "Getting Started" callout to Home.md for new users
- Trim Configuration.md Profiles section to a pointer (was duplicating Profiles.md)
Fix documentation inconsistencies for 0.8.0 release
- Profiles: migrate all examples from deprecated top-level image/persistent/[build]
to [container]/[container.build] nesting (0.8.0 rejects the old format)
- Resource-and-Time-Limits: replace obsolete [profiles.X] flat syntax with
directory-based profile config.toml examples
- Security-Monitoring: fix phantom config keys (rate_limit → rate_limit_per_second,
remove non-existent suspicious_unlimited, file_write_threshold_mb, file_write_rate_mb_per_sec)
- FAQ: move Aider from "currently supported" to "coming soon" (not yet registered)
- Troubleshooting: fix tmpfs_size default comment (empty string, not 4GiB),
remove phantom file_write_threshold_mb reference
- File-Transfer: fix /root/.claude paths to /home/code/.claude
- Container-Operations: document coi info, coi version, coi clean --pools/--orphans/--dry-run
- Profiles: add note explaining [[mounts]] (profiles) vs [[mounts.default]] (main config)
Add Slack community links to FAQ and Troubleshooting pages
Closes #289 (wiki portion)
Update wiki for 0.8.0 release
- Rename default image coi → coi-default
- Move config path ~/.config/coi/config.toml → ~/.coi/config.toml
- Drop /etc/coi/ and ~/.config/coi/ from config hierarchy
- Replace coi build custom with profile-based build workflow
- Rename coi profile show → coi profile info
- Document profile inheritance (inherits field)
- Document coi profile create/edit/delete commands
- Remove non-existent coi config --init reference
Update wiki for CLI flag removal and readonly mount support
Remove references to 21 CLI flags that are now config/profile-only.
Replace --network, --monitor, --ssh-agent, --forward-env, --timezone,
--mount, --env, --limit-*, --writable-git-hooks examples with config
TOML equivalents. Add readonly = true mount documentation and Claude
skills/commands/plugins mounting guide (ref #260).
Still-valid flags (--format, --capture, --tty, --env on container exec,
--timeout, --compression on build) are unchanged.
Update wiki for 0.8.0 unreleased changes
System-Health-Check.md:
- Rewrite example output with all 27 current checks
- Expand "What's Checked" table with all categories and checks
- Add Security Posture Details section (status logic table)
- Add Version Checks section (Incus >= 6.1, nftables >= 0.9.0, kernel >= 5.15)
- Add JSON output example with security_posture details
- Update notes for Colima/Lima and privileged profile detection
Security-Best-Practices.md:
- Add privileged container guard, security posture verification, and
kernel version enforcement to defense-in-depth summary (8 → 11 layers)
Troubleshooting.md:
- Add "COI refuses to start: security.privileged=true" entry with fix
- Add "Kernel version warning on startup" entry
FAQ.md:
- Fix [container] → [paths] for preserve_workspace_path config
docs: add Configuration page and document 0.8.0 features across wiki
- Create Configuration.md with full config reference (was linked but missing)
- Add SSH agent forwarding and env var forwarding to Container-Lifecycle-and-Sessions
- Update Network-Isolation with TTL-aware DNS refresh behavior
- Add sandbox context file docs to Supported-Tools
- Add SSH/env forwarding security considerations to Security-Best-Practices
- Fix stale mount_claude_config reference in FAQ
- Update env var isolation statement in FAQ for forward_env
- Add Configuration link to Home page
docs(faq): add entry about orphaned firewalld zone bindings
Explains that orphaned veth entries in firewalld are typically caused
by Docker on the host (not COI), and how to clean them up or prevent
accumulation with a cron job.
docs: expand FAQ with community questions and security monitoring emphasis
Add 6 new FAQ entries based on YouTube community feedback:
- Why not just use Docker with a volume?
- How is COI different from Distrobox?
- Why does COI use Colima on macOS?
- Can I use Lima/limactl or a plain VM instead?
- Why run an AI agent locally instead of in the cloud?
- Can I use COI with local/self-hosted AI models?
Update existing entries (Docker Sandboxes, DevContainers, comparison table)
to highlight security monitoring capabilities as a key differentiator.
fix: replace non-existent coi monitor audit references with actual commands
The `coi monitor audit` subcommand is not implemented (commented out in
code). Replace all references with the actual working approach: reading
audit JSONL files directly from ~/.coi/audit/.
Pages updated:
- Security-Monitoring.md (4 references)
- Troubleshooting.md (2 references)
- FAQ.md (1 reference)
docs: add FAQ entry for mounting extra context files into containers
Addresses issue #175 — documents how to mount additional context
files (opencode agents, AGENTS.md, coding standards) into containers
using --mount flag or config file mounts. Emphasizes mounting
subdirectories rather than the parent config directory to avoid
conflicts with COI's config management.
docs: update wiki with recent fixes and improvements
Security Monitoring:
- Add large file write detection, gateway IP RFC1918 exclusion
- Document dropped event tracking and orphan NFT rule cleanup
- Add alert deduplication and NFT error routing details
Troubleshooting (6 new entries):
- Docker Compose fails in session containers
- Permission denied / UID/GID mismatch
- Security settings silently disabled (config merge bug)
- Firewall rules accumulating
- Settings.json overwritten
- Cross-device link session save errors
Supported Tools:
- Add Claude effort level configuration
- Fix opencode config path to XDG-compliant location
- Update Go interfaces (ToolWithConfigDirFiles, ToolWithEffortLevel)
Network Isolation:
- Clarify gateway IP auto-exclusion from RFC1918 checks
- Document cleanup on all termination paths including nftables
- Remove duplicated container access section
Container Lifecycle:
- Add coi persist and coi resume commands
- Document Docker/Compose support in sessions
- Note sync.Once cleanup protection
Container Operations:
- Document three-step launch sequence for Docker support
- Add UID/GID remapping and extra mount documentation
FAQ: Add Docker Compose and preserve_workspace_path entries
Resource Limits: Add tmpfs_size to disk limits config
docs: update wiki for recent security monitoring features
Security-Monitoring.md:
- Add large write detection for data exfiltration
- Add disk space monitoring (/tmp > 80% warning)
- Add coi resume command documentation
- Add threat deduplication (30-second window)
- Add complete configuration options
- Add threat level table with severities
- Add example for detecting data exfiltration
- Add NFT cleanup troubleshooting
Supported-Tools.md:
- Update opencode resume behavior (--continue flag)
- Add permission bypass row to comparison table
System-Health-Check.md:
- Clarify Incus storage pool thresholds
Troubleshooting.md:
- Add section for container paused by monitoring
- Add section for container killed by monitoring
- Document coi resume workflow
FAQ.md:
- Add real-time threat detection to protection list
- Add monitoring best practices
docs: update /tmp default to disk-backed in FAQ and Troubleshooting
docs: add /tmp full → agent hang to FAQ and Troubleshooting (#135)
Remove redundant H1 header from FAQ page