agent

Portable harness tooling for terminal AI agents (grok, codex, claude, opencode, agy) used with Ansible playbooks such as boxcar-ops.

This repository holds scripts and templates. Operator-specific state lives in the playbook checkout under .agent/ (not here).

Install

Clone as a sibling of playbook/ and vault/ in your playbook root:

git clone ssh://[email protected]/ansible-roles/agent.git agent

The parent playbook's .gitignore should list agent/ (nested repo, not tracked in the parent).

On first use, the playbook creates .agent/ for local state:

<playbook-root>/
  agent/          ← this repo
  .agent/         ← per-clone workspace (parent repo or local only)
    .config/      harness installs + credentials (gitignored)
    .run/         ssh-agent sessions (gitignored)
    ssh/          keys.d/, config.d overrides
    logs/         agent review logs

Optional per-environment overrides (vault-style):

deploy/<env>/.agent/ssh/
deploy/<env>/.agent/logs/

Usage

From the playbook root (boxcar-ops: ./run.sh):

./run.sh agent list
./run.sh agent grok
./run.sh agent codex actual
./run.sh agent grok --container
./run.sh agent grok --container --resume <session-id>
./run.sh agent-setup grok          # install or upgrade harness in .agent/.config/
./run.sh agent-setup codex
./run.sh agent-setup claude
./run.sh agent-setup agy
./run.sh agent sessions
./run.sh agent prune
./run.sh agent shell                  # interactive shell in agent runtime container
./run.sh agent shell -- git status    # one-shot command in container

Harness-specific flags (--resume, --sandbox off, etc.) pass through unchanged.

Install and upgrade

./run.sh agent-setup <harness> installs into .agent/.config/<harness>/ via podman. Re-run to upgrade when a binary is already present:

Harness	First install	Re-run (upgrade)
grok	upstream install script	grok update
codex	install.sh	codex update (delegates to install.sh; needs full UBI + tar)
claude	install.sh	claude update (relocates binary into workspace bin/; full UBI for setup/upgrade)
opencode	upstream install script	opencode upgrade -m curl
agy	Antigravity install script (--dir)	agy update

Path resolution

All scripts resolve paths through bin/agent-path.sh:

Command	Resolves to
agent-path.sh	.agent/ workspace root
agent-path.sh ssh	.agent/ssh (or deploy/<env>/.agent/ssh)
agent-path.sh logs	.agent/logs (or env override)
agent-path.sh config grok	.agent/.config/grok
agent-path.sh tool ssh/config	agent/ssh/config template

Environment: PLAYBOOK_DEPLOY_ENV or VAULT_DEPLOY_ENV (default actual).

Components

Script	Role
agent-launch.sh	Entry from playbook; env selection, session start, harness or container launch
agent-session.sh	Sourceable ssh-agent session + traps (must be sourced, not executed)
agent-runtime.sh	Per-session .agent/.run/<pid>/, vault key → ssh-add, generated ssh.config
agent-path.sh	Tool vs workspace path resolver
agent-container.sh	Podman install/run/shell for grok, codex, claude, opencode, agy
agent-build.sh	Build the agent runtime container image
agent-push.sh	Push the agent runtime container image
agent-ssh.sh	One-shot SSH using agent identity
agent-ssh-key.sh	Print ssh-agent socket for ansible

SSH model

1. Base defaults: agent/ssh/config (this repo).
2. Static routes: .agent/ssh/config.d/*-enable (playbook workspace).
3. Per-session auth: .agent/.run/<launcher-pid>/runtime-enable (generated).
4. Wrapper: .agent/.run/<launcher-pid>/ssh.config includes the above.

Private keys live in .agent/ssh/keys.d/ (any algorithm — ed25519, RSA, etc.). Each private file needs a matching .pub sibling; names are free-form inside keys.d/ (every non-*.pub file is treated as a private key). Ansible Vault encrypt before commit. agent-runtime.sh loads all keys from keys.d/ into the session ssh-agent via ./run.sh vault view → ssh-add (memory only). Legacy flat keys in .agent/ssh/ still work when keys.d/ is empty. Set AGENT_SSH_KEY to load a single key by basename.

Container mode

Build the runtime image once (UBI 10 minimal + git, ssh client, etc.):

./run.sh agent-build
./run.sh agent-build --tag git.boxcar.sh/containers/agent-runtime:latest
./run.sh agent-build --base-image registry.access.redhat.com/ubi10/ubi-minimal@sha256:...
./run.sh agent-push

Defaults live in agent/build/build.env (AGENT_BASE_IMAGE, AGENT_RUNTIME_IMAGE, optional AGENT_IMAGE_SOURCE). Copy or symlink to .agent/build.env to override per playbook (deploy/<env>/.agent/build.env wins when present). Precedence: shell env → .agent/build.env → agent/build/build.env. After build, harness run/shell uses AGENT_RUNTIME_IMAGE unless AGENT_IMAGE is set.

• Runtime image: built agent-runtime (default tag git.boxcar.sh/containers/agent-runtime:latest).
• Setup/upgrade image: full ubi10/ubi for initial install and codex/claude/opencode upgrades (update may need tar).
• Volume: .agent/.config/<harness>/ mounted at /boxcar-agent/.{grok,codex,claude,opencode,agy}.
• Repo mount: full playbook tree at the same absolute path (for ansible + ssh-agent socket under .agent/.run/).
• Runtime shell: ./run.sh agent shell opens bash in the runtime image with .agent/.config/shell/ mounted as $HOME (history, bin/, .local/ persist per playbook).
• Sandbox: not disabled by default; pass harness flags at launch if needed.

Samples

• etc/doas.conf.sample — optional tighter doas rules for the agent user; not deployed automatically.

See also

• Parent playbook AGENTS.md — bootstrap and fleet-wide conventions.
• Parent CLAUDE.md — Claude Code entrypoint (auto-discovered); should reference AGENTS.md.
• AGENTS.md in this repo — concise notes for coding agents.