ai-agent-setup

Tooling and documentation for running AI coding agents under a dedicated UNIX user, separate from the human operator's account.

Why a separate user

Running an agent under your own UID gives it everything you have: your environment, your SSH agent socket, your terminal-multiplexer sockets, your cached cloud credentials, and (with a permissive ptrace_scope) the ability to attach to your other processes. File modes and sandboxes patch some of this; a separate UID closes it structurally — /run/user/<uid> and the multiplexer socket directories are mode 0700, /proc/<pid>/environ is not readable across UIDs, and cross-UID ptrace needs CAP_SYS_PTRACE. This repository collects the setup needed to make that split practical day to day.

Two paths

The documentation serves two situations, sharing one set of reference material:

1. New setup — provisioning an agent user from scratch, before any agent has run on the machine. Start at docs/provisioning.md.
2. Migration — for a user who has already been running agents on their personal account: an existing agent state directory, existing checkouts, and existing credentials that must not be carried over. The runbook is docs/migration.md.

The execution roadmap for open work lives in TODO.md.

Repository layout

Path	Contents
AGENTS.md	Canonical instructions for agents working in this repository
CLAUDE.md	Claude Code entry point; imports AGENTS.md
CONTRIBUTING.md	Contribution rules, binding humans and agents alike
docs/provisioning.md	Provisioning the dedicated agent user
docs/shared-repos.md	Sharing checkouts between the human and the agent
docs/credentials.md	The agent's read-only cloud profiles and SSH key
docs/migration.md	Migrating from agents on the human's personal account
docs/verification.md	Verifying agent isolation and credentials
docs/adr/	Architecture decision records (MADR)
bin/	Setup and maintenance tooling, POSIX sh
tests/	Tests for the tooling, one script per tool
Makefile	make lint and make test over the tooling
TODO.md	Execution roadmap and status
BACKLOG.md	One-line roll-up of open work
LICENSE	MIT license

Conventions

Everything user-specific — usernames, groups, paths — is configurable, and the repository carries only placeholders; see ADR-0001. Design decisions are recorded as ADRs under docs/adr/.

License

MIT.