ops-jrz1/docs/server-AGENTS.md

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:

bun install -g @google/gemini-cli
bun install -g @anthropic-ai/claude-code

Nix packages (go, rust, etc.):

nix profile install nixpkgs#go
nix profile install nixpkgs#rustc
nix profile list        # See installed
nix profile remove <n>  # Remove by index

Python packages:

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):

# 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)

tmux new -s mybot
python bot.py
# Ctrl-b d to detach, tmux attach -t mybot to reconnect

2. User systemd services

# 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.)

bun install -g pm2
pm2 start bot.js --name mybot
pm2 save

Getting Help

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

# Search for packages
nix search nixpkgs <name>

# Check resource usage
htop