026f82e697
Codex CLI seccomp filters block nix daemon access. Workaround: disable redundant sandbox since server provides isolation. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
131 lines
3.2 KiB
Markdown
131 lines
3.2 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>
|
|
```
|
|
|
|
## Emes Tools (tissue, jwz, idle)
|
|
|
|
For now, install per-user (lands in `~/.local/bin`, already in PATH):
|
|
|
|
```bash
|
|
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):
|
|
|
|
```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)
|
|
|
|
## Getting Help
|
|
|
|
```bash
|
|
# Check what's installed
|
|
which <tool>
|
|
nix profile list
|
|
|
|
# Search for packages
|
|
nix search nixpkgs <name>
|
|
|
|
# Check resource usage
|
|
htop
|
|
```
|