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)

Getting Help

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

# Search for packages
nix search nixpkgs <name>

# Check resource usage
htop

2.8 KiB Raw Blame History