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>

Emes Tools (tissue, jwz, idle)

For now, install per-user (lands in ~/.local/bin, already in PATH):

curl -fsSL https://evil-mind-evil-sword.github.io/releases/idle/install.sh | sh

Notes:

• idle installs tissue and jwz (zawinski) plus jq if needed.
• Use emes tools for agent workflow; this repo still uses beads (bd) for infrastructure issue tracking.

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)

Getting Help

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

# Search for packages
nix search nixpkgs <name>

# Check resource usage
htop