# AGENTS.md - Dev Server Guide

Guidelines for AI coding agents on ops-jrz1.

## Environment

- **OS**: NixOS (not Ubuntu/Debian - no apt)
- **Shell**: bash
- **Home**: `/home/<username>` (private, 700)

## Available Tools

System-wide (ready to use):
```
python3, uv          # Python dev
bun, node, npm       # JS/TS dev (bun preferred - faster)
zig                  # Zig compiler
git, vim, curl, tmux # Basics
opencode, bd         # AI coding tools
```

## Installing Packages

**JS packages** (gemini-cli, etc.) - use bun for faster installs:
```bash
bun install -g @google/gemini-cli
bun install -g @anthropic-ai/claude-code
```

**Nix packages** (go, rust, etc.):
```bash
nix profile install nixpkgs#go
nix profile install nixpkgs#rustc
nix profile list        # See installed
nix profile remove <n>  # Remove by index
```

**Python packages**:
```bash
uv venv && source .venv/bin/activate
uv pip install <package>
```

## Resource Limits

Per-user limits are enforced:
- **Memory**: 50% of system (~1GB)
- **Processes**: 200 max
- **Network**: 30 new connections/min (burst 60)

If you hit limits, your processes may be killed. Design accordingly.

## File Locations

| Path | Purpose |
|------|---------|
| `~/.npm-global/` | npm global packages |
| `~/.nix-profile/` | nix profile packages |
| `~/.config/` | App configs (claude, etc.) |
| `/tmp/` | Temp files (fast, cleared on reboot) |

## Networking

- Outbound connections are logged and rate-limited
- No inbound ports (use SSH tunnels for local services)
- Example tunnel: `ssh -L 8080:localhost:8080 dev-server`

## Security Model

Simple Unix isolation - no containers, VMs, or complex sandboxing:
- Home directories are private (`chmod 700 ~`)
- Per-user resource limits (memory, processes, network)
- Watchdogs kill runaway processes
- Shared tokens via group-readable files

This is a learning environment, not a hostile multi-tenant system.

## AI Agent Sandbox Conflicts

Some AI coding agents (Codex, etc.) run commands in their own sandbox with seccomp
filters. This can block nix daemon access even though the server allows it.

**Symptom**: `nix store ping` or `nix develop` fails with "Operation not permitted"
from within the agent, but works from your regular SSH session.

**Fix for Codex CLI**: Disable redundant sandboxing (server already provides isolation):

```bash
# One-off
codex -s danger-full-access

# Permanent (~/.codex/config.toml)
sandbox_mode = "danger-full-access"
```

Other agents may have similar sandbox settings - check their docs if nix commands fail.

## Do NOT

- Run `sudo` (you don't have access)
- Install with `apt` or `yum` (this is NixOS)
- Fork-bomb or stress test (watchdogs will kill you)
- Store secrets in plain files (use env vars)

## Running Persistent Services

Three options for keeping code running:

### 1. tmux/screen (simplest)
```bash
tmux new -s mybot
python bot.py
# Ctrl-b d to detach, tmux attach -t mybot to reconnect
```

### 2. User systemd services
```bash
# Create service file
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/mybot.service << 'EOF'
[Unit]
Description=My bot

[Service]
ExecStart=/home/YOURUSER/.bun/bin/bun run /home/YOURUSER/mybot/index.js
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target
EOF

# Enable and start
systemctl --user daemon-reload
systemctl --user enable --now mybot
systemctl --user status mybot
systemctl --user logs -f mybot
```

**Note:** User services stop when you log out unless lingering is enabled (ask admin).

### 3. Process managers (pm2, etc.)
```bash
bun install -g pm2
pm2 start bot.js --name mybot
pm2 save
```

## Getting Help

```bash
# Check what's installed
which <tool>
nix profile list

# Search for packages
nix search nixpkgs <name>

# Check resource usage
htop
```