# zinit Path Configuration
This document describes how zinit handles configuration and socket paths across different platforms and environments.
## Path Defaults
### Linux (System/PID1 mode)
**Configuration Directory:**
- Default: `/etc/zinit/services` (service configs)
- System services: `/etc/zinit/system` (PID1 mode only)
- Environment override: `ZINIT_CONFIG_DIR`
**Socket Path:**
- Default: `/run/zinit.sock`
- Environment override: `ZINIT_SOCKET`
**Usage:**
```bash
# Start server in PID1 mode (loads /etc/zinit/system and /etc/zinit/services)
zinit-pid1
# Start standalone server
zinit-server --pid1-mode
# With environment overrides
ZINIT_CONFIG_DIR=/custom/path ZINIT_SOCKET=/custom/socket zinit-server
```
### macOS / Windows (Standalone mode)
**Configuration Directory:**
- Default: `$HOME/hero/cfg/zinit`
- Environment override: `ZINIT_CONFIG_DIR`
**Socket Path:**
- Default: `$HOME/hero/var/zinit.sock`
- Environment override: `ZINIT_SOCKET`
**Usage:**
```bash
# Start standalone server
zinit-server
# With environment overrides
ZINIT_CONFIG_DIR=~/my-services ZINIT_SOCKET=/tmp/custom.sock zinit-server
```
## Implementation Details
Paths are centralized in `src/sdk/socket.rs`:
### Constants
```rust
pub const SYSTEM_SOCKET: &str = "/run/zinit.sock"; // Linux
pub const SYSTEM_CONFIG_DIR: &str = "/etc/zinit/services"; // Linux
pub const USER_SOCKET_SUFFIX: &str = "hero/zinit/zinit.sock"; // macOS/Windows
pub const USER_CONFIG_DIR_SUFFIX: &str = "hero/zinit/services"; // macOS/Windows
```
### Functions
```rust
pub fn system_path() -> PathBuf // /run/zinit.sock
pub fn user_path() -> PathBuf // $HOME/hero/var/zinit.sock
pub fn default_path() -> PathBuf // Uses system if exists, else user
pub fn system_config_dir() -> PathBuf // /etc/zinit/services
pub fn user_config_dir() -> PathBuf // $HOME/hero/zinit/services
pub fn config_dirs() -> Vec<PathBuf> // [user_config_dir, system_config_dir]
```
## Mode Selection
### Standalone Mode (default)
- Uses `user_path()` and `user_config_dir()`
- Works on any OS
- Services not isolated from user services
### PID1 Mode
- Uses `system_path()` and `system_config_dir()`
- Requires Linux (guarded by `#[cfg(not(target_os = "linux"))]`)
- Loads system services first, then user services
- System services protected from bulk operations
## CLI Connection
When connecting to the daemon, the CLI tries paths in order:
1. `--socket` argument (if provided)
2. System path (if exists): `/run/zinit.sock`
3. User path: `$HOME/hero/var/zinit.sock`
```bash
# Uses default path detection
zinit list
# Override socket path
zinit --socket /custom/path/zinit.sock list
```
## Environment Variable Behavior
Both server and client respect these environment variables:
- `ZINIT_CONFIG_DIR`: Override config directory
- `ZINIT_SOCKET`: Override socket path
- `ZINIT_LOG_LEVEL`: Set log level (trace, debug, info, warn, error)
- `ZINIT_CONTAINER`: Container mode flag (zinit-pid1 only)
## Development
### Using run.sh (macOS development)
```bash
./run.sh
# Starts server with:
# - Socket: /tmp/zinit-dev.sock
# - Config: /tmp/zinit-dev-config
# - Auto-detects and kills existing process
```
### Custom Paths
```bash
# Server with custom paths
ZINIT_CONFIG_DIR=/tmp/services ZINIT_SOCKET=/tmp/test.sock zinit-server
# Client connecting to custom socket
ZINIT_SOCKET=/tmp/test.sock zinit list
```
## Notes
- `/run` is preferred over `/var/run` on modern Linux systems
- User paths include `hero/` as a namespace to avoid conflicts
- Paths are resolved at runtime, not compile-time, allowing flexibility
- All path functions are tested in unit tests