caic docs

Appearance

Installation ​

Prerequisites ​

  • Docker or Podman installed and running

caic uses Docker when both runtime commands are installed, and Podman when only Podman is installed. Configuration covers choosing the runtime for new tasks.

Install ​

bash
curl -fsSL https://caic.xyz/install.sh | bash

The install script:

  1. Downloads the latest caic and md binaries to ~/.local/bin/
  2. Copies a default config.toml to ~/.config/caic/ (if not already present)
  3. Installs and starts a system service (systemd on Linux, launchd on macOS)

After installation, caic is running on http://localhost:2242. The default root = "." is resolved from the service working directory, not from the directory where you invoked the installer. The systemd unit uses your home directory. Set an explicit [core] root in ~/.config/caic/config.toml before adding repositories.

Set NO_SERVICE=1 to skip service installation:

bash
curl -fsSL https://caic.xyz/install.sh | NO_SERVICE=1 bash

If the GitHub release API is rate-limited, set GITHUB_TOKEN for authentication:

bash
export GITHUB_TOKEN="ghp_..."
curl -fsSL https://caic.xyz/install.sh | bash

systemd user service (Linux) ​

The install script sets up the systemd service automatically. To install manually:

bash
mkdir -p ~/.config/systemd/user ~/.config/caic
cp contrib/caic.service ~/.config/systemd/user/
cp contrib/config.toml ~/.config/caic/config.toml
# Edit ~/.config/caic/config.toml

systemctl --user daemon-reload
systemctl --user enable --now caic

View logs:

bash
journalctl --user -o cat -f -u caic

caic watches its own executable and config.toml for changes and restarts automatically when either is modified.

caic imports PATH, SSH_AUTH_SOCK, and other exported values from your interactive login shell at startup. The unit starts without requiring a keyring socket. To use only the service environment instead, set [core] shell_env = false in config.toml.

The unit optionally reads ~/.config/caic/caic.env. With shell_env = false, use this file for service-only environment overrides, such as adding ~/.local/bin to PATH. The service starts normally when the file is absent.

launchd user agent (macOS) ​

The install script sets up the launchd agent automatically. To install manually, publish the plist with your own absolute paths:

bash
mkdir -p ~/.config/caic "$HOME/Library/LaunchAgents"
cp contrib/config.toml ~/.config/caic/config.toml
# Edit ~/.config/caic/config.toml

plist="$HOME/Library/LaunchAgents/com.caic.caic.plist"
logs="$HOME/Library/Logs/caic"
mkdir -p "$logs"
cp contrib/com.caic.caic.plist "$plist"
plutil -replace ProgramArguments.0 -string "$HOME/.local/bin/caic" -- "$plist"
plutil -replace StandardOutPath -string "$logs/stdout.log" -- "$plist"
plutil -replace StandardErrorPath -string "$logs/stderr.log" -- "$plist"
plutil -lint -- "$plist"

launchctl bootstrap gui/$(id -u) "$plist"

View logs:

bash
tail -f "$HOME/Library/Logs/caic/stdout.log" "$HOME/Library/Logs/caic/stderr.log"

launchd starts caic directly, without a shell wrapper. To update an existing agent, replace its plist and run launchctl bootout then launchctl bootstrap. Log rotation needs separate configuration.

The launchd template does not set a working directory, so do not rely on the relative default root = ".". Set [core] root to an absolute repository parent directory.

Install from source ​

See the caic README for building and installing caic from source with Go.

Next steps ​

Your agents. Your machine.

caic and md · Apache 2.0