2887ad4122
Documents tmux, user systemd, and pm2 options for running long-lived processes. Notes lingering requirement for systemd.
162 lines
3.7 KiB
Markdown
162 lines
3.7 KiB
Markdown
# 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
|
|
```
|