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.

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.6 KiB Raw Blame History