agent-container 0.1.0__tar.gz

agent_container-0.1.0/.env.example

@@ -0,0 +1,25 @@
+# Copy to .env and fill in real values. .env is gitignored; never commit it.
+# See docs/credentials.md for the rationale and security trade-offs.
+
+# --- GitHub auth (HTTPS push) ---
+# Create at: https://github.com/settings/tokens
+# Scopes: repo (required), workflow (optional)
+GH_TOKEN=
+
+# --- Git identity (not secret) ---
+GIT_USER_NAME=Your Name
+GIT_USER_EMAIL=you@example.com
+
+# --- Agent provider keys ---
+# OPTIONAL: leave blank to log in interactively inside the container instead
+# (claude -> /login, codex login). Interactive login persists on the container's
+# per-name credential volume and auto-refreshes — preferred for subscription
+# accounts. See docs/credentials.md and the README "Log in to agents" section.
+# Claude Code (API-key billing):
+ANTHROPIC_API_KEY=
+# Codex (@openai/codex):
+OPENAI_API_KEY=
+# pi-coding-agent is multi-provider; uncomment the ones you actually use.
+# GOOGLE_API_KEY=
+# MISTRAL_API_KEY=
+# GROQ_API_KEY=

agent_container-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+# CI gate for agent-container: runs the runtime-free pytest suite and builds the
+# distributions on every push and PR. This does NOT run on tag pushes; the
+# release itself is gated by publish.yml, which re-runs the suite before build.
+name: ci
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+
+# Cancel superseded runs for the same ref so rapid successive pushes don't pile
+# up runners (does not dedupe the push/pull_request pair — different refs).
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: pytest + build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Run the pytest suite
+        # --no-project keeps the run hermetic; the --with pins mirror the
+        # bin/agent-container PEP 723 inline metadata (kept in sync with pyproject).
+        run: >
+          uv run --no-project --with pytest
+          --with 'typer>=0.12,<1' --with 'questionary>=2.0,<3' --with 'rich>=13,<15'
+          pytest bin/tests
+      - name: Build distributions
+        run: uv build

agent_container-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,54 @@
+# Publish agent-container to PyPI via Trusted Publishing (OIDC — no stored secrets).
+#
+# Trigger: pushing a tag matching v* (e.g. v0.1.0). Builds an sdist + wheel with
+# `uv build` and uploads them with pypa/gh-action-pypi-publish, which mints a
+# short-lived OIDC token. The operator configures the PyPI trusted publisher once
+# (project: agent-container, owner: ondrasek, repo: agent-container, workflow: publish.yml,
+# environment: release) — no API token is ever stored in the repo.
+name: publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Run the pytest suite
+        # Gate the release on green: mirrors ci.yml (ci.yml does NOT run on tag
+        # pushes, so the suite is re-run here). A failure here fails the build
+        # job, and `publish` needs: build — so a red tagged commit never ships.
+        # --with pins mirror the bin/agent-container PEP 723 inline metadata.
+        run: >
+          uv run --no-project --with pytest
+          --with 'typer>=0.12,<1' --with 'questionary>=2.0,<3' --with 'rich>=13,<15'
+          pytest bin/tests
+      - name: Build distributions
+        run: uv build
+      - name: Upload dist artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write # OIDC token for Trusted Publishing
+    steps:
+      - name: Download dist artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

agent_container-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Runtime credentials and per-host config — see docs/credentials.md
+.env
+.env.local
+.env.*.local
+
+# Claude Code harness artifacts (workflow scripts saved per-session)
+.claude/
+
+# OS noise
+.DS_Store
+Thumbs.db
+
+# Editor noise
+*.swp
+*.swo
+.idea/
+
+# Python build artifacts (bin/tests pytest suite)
+__pycache__/
+*.pyc
+.pytest_cache/
+
+# Packaging / uv project mode (root pyproject.toml)
+.venv/
+*.egg-info/
+dist/
+build/
+# NOTE: uv.lock IS committed. agent-container is an application/CLI (not a library), so
+# the lockfile is checked in for reproducible dev envs (`uv sync`). Do not ignore it.

agent_container-0.1.0/CLAUDE.md

@@ -0,0 +1,47 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project intent
+
+Build a **containerized development environment** designed to run remotely (e.g., Hetzner VPS) as an always-on container that the user attaches to and detaches from over SSH. Inside, multiple AI coding agents (Claude Code, Codex, pi-coding-agent) and editors (nvim) run under tmux. Multiple such containers may run in parallel, each holding working copies of one or more git repositories.
+
+This is a greenfield repo — no code has been written yet. Treat the section below as the design contract, not a description of existing code.
+
+## Hard constraints
+
+These are load-bearing design decisions, not preferences:
+
+1. **No reliance on container persistence.** Every agent must `commit` AND `push` every change. The container is treated as ephemeral; if it dies, no work is lost. Any feature or workflow that depends on uncommitted state is wrong by construction.
+2. **Editor-agnostic, not VSCode-locked.** The user explicitly rejected devcontainers because tooling support outside VSCode is nonexistent. Do not introduce `.devcontainer/` configs or any design that assumes a VSCode client. SSH + tmux is the canonical attach path.
+3. **Multiple parallel containers.** Naming, port allocation, volume mounts, and git identity must all support N containers running simultaneously on the same host without collision.
+4. **Push auth must work non-interactively.** Agents commit autonomously, so SSH keys / git credentials inside the container must be configured to push without prompts. Never embed long-lived secrets in the image — inject at runtime.
+
+## Decisions
+
+- **Runtime + base image:** Podman + `debian:12-slim`. See [`docs/decisions/0001-runtime-and-base-image.md`](docs/decisions/0001-runtime-and-base-image.md).
+- **CLI:** a single tool, `agent-container` (`bin/agent-container`) — a PEP 723 uv script (Typer + questionary + rich) covering the whole lifecycle (build/up/attach/logs/down/purge) plus an interactive wizard. Its on-disk contract (container names `agent-container-<name>`, the `2200 + name-hash` port, `$XDG_STATE_HOME/agent-container/<name>.port` state files, `~/.config/agent-container/hosts.conf`) is the single source of truth; the shell completions read the same state files. Runtime default is platform-aware (docker-first on macOS, podman-first on Linux); override with `AGENT_CONTAINER_RUNTIME`.
+- **Packaging + release:** ships to PyPI as the `agent_container` module via a hatchling `force-include` wheel (`bin/agent-container` → `agent_container/__init__.py`; completions → `agent_container/completions/*` package data). `REPO_ROOT` resolves location-independently (`AGENT_CONTAINER_REPO` → `Dockerfile`+`completions/` marker → `None`) so a **non-editable** PyPI install works standalone (`up/down/list/attach/logs/purge/completions`); only `build` needs a checkout (via `AGENT_CONTAINER_REPO`/`--context`). `uv tool install --editable .` remains the dev path. Push a `v*` tag → `.github/workflows/publish.yml` uploads via PyPI **Trusted Publishing** (OIDC, no stored secrets); `ci.yml` gates on the pytest suite + `uv build`. Licensed **MIT** ([`LICENSE`](LICENSE)).
+
+## Architecture sketch (to be built)
+
+Expect the repo to grow into roughly:
+
+- **Container image** — base OS + tmux + SSH server + nvim + git + the agent CLIs (Claude Code, Codex, pi-coding-agent) and their language runtimes.
+- **Orchestration layer** — scripts or compose/quadlet definitions to launch, name, attach to, and tear down containers on the remote host.
+- **Bootstrap / entrypoint** — sets up git identity, injects credentials, starts sshd + a default tmux session, optionally clones configured repos.
+- **Attach tooling** — a thin client-side helper for `ssh user@host -t tmux attach -t <session>` style flows across multiple hosts/containers.
+
+When adding a component, keep these layers separate. Don't bake host-specific orchestration into the image.
+
+## Conventions for future work
+
+- Prefer **rootless / Podman-compatible** patterns where reasonable; avoid features that only work on Docker Desktop.
+- Treat the **commit-and-push discipline** as a property of the agent configuration, not something to enforce via git hooks alone (hooks can be bypassed; the agents themselves should be configured to push).
+- When proposing a tool or dependency, justify it against the constraints above — especially the "not VSCode-locked" one.
+
+## Out of scope (don't add unless asked)
+
+- IDE integrations beyond plain SSH/tmux/nvim.
+- Multi-user / multi-tenant access controls — single operator (the user) is assumed.
+- Kubernetes manifests — the target is a single VPS running a container runtime, not a cluster.

agent_container-0.1.0/Dockerfile

@@ -0,0 +1,166 @@
+# syntax-compatible with both `docker build` and `podman build`.
+# No BuildKit-specific features. See docs/decisions/0001-runtime-and-base-image.md.
+#
+# Layering rationale (cheapest-to-rebuild last):
+#   1. apt base packages          — rarely changes; large; cached aggressively.
+#   2. Node 22 LTS (NodeSource)   — rarely changes; medium.
+#   3. Agent CLIs (npm globals)   — changes with agent releases.
+#   4. Neovim upstream tarball    — changes with nvim releases.
+#   5. User + sshd config         — cheap; placed late so earlier layers cache.
+#   6. entrypoint.sh              — changes most often (item C); last.
+
+FROM debian:12-slim
+
+# Fail fast on any unhandled error inside RUN blocks.
+SHELL ["/bin/bash", "-o", "pipefail", "-c"]
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    LANG=C.UTF-8 \
+    LC_ALL=C.UTF-8 \
+    TZ=UTC
+
+# --- Layer 1: base OS packages ----------------------------------------------
+# Single RUN so the apt cache cleanup lands in the same layer as the install.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        ca-certificates \
+        curl \
+        gnupg \
+        git \
+        openssh-server \
+        tmux \
+        zsh \
+        sudo \
+        locales \
+        less \
+        jq \
+        build-essential \
+        python3 \
+        python3-pip \
+        python3-venv \
+    && sed -i 's/^# *\(C.UTF-8\)/\1/' /etc/locale.gen || true \
+    && locale-gen C.UTF-8 \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+# --- Layer 2: Node 22 LTS via NodeSource ------------------------------------
+RUN curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \
+    && apt-get install -y --no-install-recommends nodejs \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+# --- Layer 3: agent CLIs (global npm installs) ------------------------------
+# pi-coding-agent needs --ignore-scripts (postinstall pulls native bits we
+# don't want resolved at build time).
+RUN npm i -g @anthropic-ai/claude-code \
+    && npm i -g @openai/codex \
+    && npm i -g --ignore-scripts @earendil-works/pi-coding-agent \
+    && npm cache clean --force
+
+# --- Layer 4: Neovim from upstream stable tarball ---------------------------
+# Debian 12's nvim package is too old. Upstream ships per-architecture tarballs;
+# pick the one matching the build platform (amd64 -> x86_64 / linux64 legacy
+# name; arm64 -> linux-arm64). The asset name for amd64 also changed across
+# releases (nvim-linux64.tar.gz -> nvim-linux-x86_64.tar.gz); fall through.
+RUN set -eux; \
+    cd /tmp; \
+    BASE="https://github.com/neovim/neovim/releases/latest/download"; \
+    ARCH="$(dpkg --print-architecture)"; \
+    case "${ARCH}" in \
+        amd64) CANDIDATES="nvim-linux-x86_64.tar.gz nvim-linux64.tar.gz" ;; \
+        arm64) CANDIDATES="nvim-linux-arm64.tar.gz" ;; \
+        *) echo "unsupported architecture: ${ARCH}" >&2; exit 1 ;; \
+    esac; \
+    TARBALL=""; \
+    for CAND in ${CANDIDATES}; do \
+        if curl -fsSLO "${BASE}/${CAND}"; then TARBALL="${CAND}"; break; fi; \
+    done; \
+    if [ -z "${TARBALL}" ]; then \
+        echo "no neovim release asset matched for arch=${ARCH} (tried: ${CANDIDATES})" >&2; \
+        exit 1; \
+    fi; \
+    tar -C /usr/local -xzf "${TARBALL}" --strip-components=1; \
+    rm -f "${TARBALL}"; \
+    nvim --version | head -n1
+
+# --- Layer 5: user + sudo + sshd config -------------------------------------
+RUN useradd --create-home --home-dir /home/dev --shell /bin/bash --uid 1000 dev \
+    && echo 'dev ALL=(ALL) NOPASSWD: ALL' > /etc/sudoers.d/90-dev \
+    && chmod 0440 /etc/sudoers.d/90-dev \
+    && mkdir -p /workspace \
+    && chown dev:dev /workspace \
+    && chmod 0755 /workspace
+
+# sshd: dev-only, key-based, no root, no passwords.
+# Host keys are deliberately NOT generated here — entrypoint does it at first
+# launch so every container instance gets a distinct identity.
+RUN mkdir -p /etc/ssh \
+    && rm -f /etc/ssh/ssh_host_* \
+    && { \
+        echo 'AllowUsers dev'; \
+        echo 'PasswordAuthentication no'; \
+        echo 'PermitRootLogin no'; \
+        echo 'PubkeyAuthentication yes'; \
+        echo 'Port 22'; \
+        echo 'UsePAM yes'; \
+        echo 'ChallengeResponseAuthentication no'; \
+        echo 'PrintMotd no'; \
+        echo 'AcceptEnv LANG LC_*'; \
+    } > /etc/ssh/sshd_config.d/10-agent-container.conf \
+    && mkdir -p /home/dev/.ssh \
+    && chown dev:dev /home/dev/.ssh \
+    && chmod 0700 /home/dev/.ssh
+
+# --- Layer 5b: per-container volume mount points + persistent shell env -----
+# Each of these dirs is the mount point of a per-container named volume
+# (agent-container-<name>-{claude,codex,pi,shellenv,tmux}). Pre-creating them dev-owned
+# (uid 1000) BEFORE the USER switch means a fresh, empty named volume
+# initializes dev-owned too — the runtime seeds a new volume from the image
+# directory's contents AND ownership/permissions. Without this the volume
+# would come up root-owned and the agents could not write their credentials.
+#
+# pi-coding-agent's config/auth dir is ~/.pi (verified: package.json piConfig
+# .configDir = ".pi"; dist/config.js getAgentDir() -> ~/.pi/agent, auth.json
+# at ~/.pi/agent/auth.json). Overridable at runtime via PI_CODING_AGENT_DIR.
+# The credential dirs are 0700; .agent-container (shell env) and .config/tmux (tmux.conf
+# + tpm plugins) are non-secret and 0755. ~/.config/tmux is XDG-standard: tmux
+# 3.x on debian:12 reads ~/.config/tmux/tmux.conf, so persisting that dir on its
+# own named volume carries the operator's tmux.conf/plugins across down/up.
+#
+# Shell-env wiring: agents and the operator drop KEY=VALUE exports in
+# ~/.agent-container/env (on the shellenv volume, so it survives down/up). BOTH bash and
+# zsh source it, guarded so a malformed file cannot break the shell. dev's
+# LOGIN SHELL stays bash (sshd/tmux/entrypoint assume bash); zsh is available
+# but not the default.
+#
+# The hook lives in ~/.bashrc (read by interactive shells). Login shells — SSH
+# login sessions AND tmux panes (tmux spawns the default shell as a LOGIN shell
+# when no default-command is set) — read ~/.bash_profile, not ~/.bashrc, so
+# ~/.bash_profile must chain to ~/.bashrc. We source Debian's stock ~/.profile
+# to do that: it sources ~/.bashrc under bash (firing the hook) AND restores the
+# ~/.local/bin + ~/bin PATH additions that ~/.bash_profile would otherwise shadow
+# (e.g. for `pip install --user` tools). This bash_profile->profile->bashrc chain
+# is load-bearing for login-shell panes; do not "simplify" it away.
+RUN set -eux; \
+    mkdir -p /home/dev/.claude /home/dev/.codex /home/dev/.pi /home/dev/.agent-container /home/dev/.config/tmux; \
+    chown -R dev:dev /home/dev/.claude /home/dev/.codex /home/dev/.pi /home/dev/.agent-container /home/dev/.config; \
+    chmod 0700 /home/dev/.claude /home/dev/.codex /home/dev/.pi; \
+    chmod 0755 /home/dev/.agent-container /home/dev/.config/tmux; \
+    HOOK='if [ -f "$HOME/.agent-container/env" ]; then set -a; . "$HOME/.agent-container/env"; set +a; fi'; \
+    printf '\n# agent-container: source persistent shell env if present (guarded)\n%s\n' "$HOOK" >> /home/dev/.bashrc; \
+    printf '# agent-container: source persistent shell env if present (guarded)\n%s\n' "$HOOK" >> /home/dev/.zshrc; \
+    printf '# agent-container: login shells load ~/.profile (sources ~/.bashrc + adds ~/.local/bin to PATH)\n[ -f "$HOME/.profile" ] && . "$HOME/.profile"\n' >> /home/dev/.bash_profile; \
+    chown dev:dev /home/dev/.bashrc /home/dev/.zshrc /home/dev/.bash_profile
+
+# --- Layer 6: entrypoint (most-frequently-changed; STUB until item C) -------
+# Two-step COPY+chmod instead of `COPY --chmod=` so the file builds under both
+# the legacy builder and BuildKit; --chmod requires BuildKit specifically.
+COPY entrypoint.sh /usr/local/bin/entrypoint.sh
+RUN chmod 0755 /usr/local/bin/entrypoint.sh
+
+EXPOSE 22
+
+USER dev
+WORKDIR /workspace
+
+ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]

agent_container-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ondrej Krajicek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.