{"id":48963713,"url":"https://github.com/kubedoll-heavy-industries/agentcontainers","last_synced_at":"2026-04-18T03:03:11.094Z","repository":{"id":352126829,"uuid":"1213647498","full_name":"Kubedoll-Heavy-Industries/agentcontainers","owner":"Kubedoll-Heavy-Industries","description":"Immutable, reproducible, least-privilege runtime environments for AI agents","archived":false,"fork":false,"pushed_at":"2026-04-18T01:48:38.000Z","size":824,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-18T02:41:34.267Z","etag":null,"topics":["ai-agents","containers","devcontainers","ebpf","oci","security","slsa"],"latest_commit_sha":null,"homepage":"https://agentcontainers.dev","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kubedoll-Heavy-Industries.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-APACHE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-17T15:55:27.000Z","updated_at":"2026-04-18T01:45:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Kubedoll-Heavy-Industries/agentcontainers","commit_stats":null,"previous_names":["kubedoll-heavy-industries/agentcontainers"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/Kubedoll-Heavy-Industries/agentcontainers","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kubedoll-Heavy-Industries%2Fagentcontainers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kubedoll-Heavy-Industries%2Fagentcontainers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kubedoll-Heavy-Industries%2Fagentcontainers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kubedoll-Heavy-Industries%2Fagentcontainers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kubedoll-Heavy-Industries","download_url":"https://codeload.github.com/Kubedoll-Heavy-Industries/agentcontainers/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kubedoll-Heavy-Industries%2Fagentcontainers/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31954737,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","containers","devcontainers","ebpf","oci","security","slsa"],"created_at":"2026-04-18T03:03:07.103Z","updated_at":"2026-04-18T03:03:11.088Z","avatar_url":"https://github.com/Kubedoll-Heavy-Industries.png","language":"Go","funding_links":[],"categories":["Sandboxing \u0026 Isolation"],"sub_categories":[],"readme":"# agentcontainers\n\n**Immutable, reproducible, least-privilege runtime environments for AI agents.**\n\n`agentcontainers` extends the [devcontainer.json](https://containers.dev/) specification to add security policy, supply chain verification, and human-in-the-loop permission approval for persistent AI agents (Claude Code, Codex CLI, Copilot Workspace, and similar tools).\n\n\u003e \"AI agents are threatening to break the blood-brain barrier between the application layer and the OS layer.\"\n\u003e — Meredith Whittaker, President of Signal, SXSW 2025\n\n---\n\n## Why\n\nPersistent AI agents require broad, long-lived system permissions. They read and write files, execute shell commands, make network requests, and consume credentials — often with the same ambient authority as the user who launched them. This is the equivalent of running every application as root on a shared machine with no network policy and no syscall filtering.\n\n`agentcontainers` applies the lessons of a decade of container security to the agent problem:\n\n| Threat | Mechanism |\n|--------|-----------|\n| Unapproved binary execution | Default-deny approval broker + eBPF enforcer |\n| Argument injection / subshell escapes | Six-layer defense-in-depth (AST → seccomp → eBPF → AppArmor → Falco) |\n| File access outside declared paths | Read-only root FS, explicit bind mounts |\n| Network exfiltration | cgroup-scoped BPF connect4/sendmsg hooks |\n| Credential theft | Secrets injected via tmpfs at `/run/secrets`; never in env vars |\n| Supply chain attacks on tools/skills | OCI-packaged, Sigstore-signed, SBOM-attested, digest-pinned |\n| Capability escalation without approval | Human-in-the-loop approval with capability diff |\n\n---\n\n## Status\n\n**Pre-Alpha.** M0–M4 are shipped; M5 (ecosystem) is in planning. The build and tests pass. The API and schema are not yet stable.\n\n| Milestone | Status | What shipped |\n|-----------|--------|-------------|\n| M0: Foundation | Shipped | `agentcontainer init/run/exec/ps/stop/logs/save/audit`, schema, Docker runtime, approval broker, Rust eBPF enforcer |\n| M1: Verify | Shipped | `agentcontainer lock/verify/shim/sbom/component`, lockfile, OCI digest pinning, WASM tool hosting |\n| M2: Sandbox | Shipped | Docker Sandbox VM backend, in-VM enforcement, compose-in-sandbox, multi-arch enforcer image |\n| M3: Attest | Shipped | `agentcontainer sign`, Sigstore integration, SLSA provenance, drift threshold enforcement, offline verification |\n| M4: Enterprise | Mostly complete | Org policy as OCI layer, secrets (Vault/Infisical/1Password/OIDC), per-MCP LSM credential enforcement |\n| M5: Ecosystem | Planning | VS Code extension, Firecracker backend, Linux K8s, MCP registry integration |\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- Go 1.23+\n- Docker Desktop (macOS) or Docker Engine (Linux)\n- [mise](https://mise.jdx.dev/) for task running\n- `cosign` (optional, for signature verification)\n\n### Install\n\n```bash\ngit clone https://github.com/Kubedoll-Heavy-Industries/agentcontainers\ncd agentcontainers\nmise install\nmise run build       # builds to tmp/agentcontainer\n```\n\nOr install directly:\n\n```bash\ngo install github.com/Kubedoll-Heavy-Industries/agentcontainers/cmd/agentcontainer@latest\n```\n\n### Initialize an agent container\n\n```bash\n# In your project directory\nagentcontainer init\n\n# This generates agentcontainer.json. If a devcontainer.json already exists,\n# it is used as the base and extended with agent-specific defaults.\n```\n\n### Pin dependencies\n\n```bash\nagentcontainer lock    # resolves all OCI references to digests and writes agentcontainer-lock.json\nagentcontainer verify  # verifies lockfile coverage and optionally checks signatures\n```\n\n### Run an agent\n\n```bash\nagentcontainer run     # starts the container + enforcer sidecar\nagentcontainer exec -- claude   # executes inside the container with approval gating\n```\n\n---\n\n## agentcontainer.json\n\nAny valid `devcontainer.json` is a valid `agentcontainer.json`. The `agent` key adds capabilities, policy, secrets, and provenance configuration:\n\n```jsonc\n{\n  \"image\": \"ghcr.io/my-org/my-agent:latest\",\n  \"agent\": {\n    \"capabilities\": {\n      \"network\": {\n        \"egress\": {\n          \"allowedDomains\": [\"api.github.com\", \"registry.npmjs.org\"]\n        }\n      },\n      \"filesystem\": {\n        \"readOnlyPaths\": [\"/workspace\"],\n        \"writablePaths\": [\"/workspace/.cache\"]\n      },\n      \"tools\": {\n        \"allowedBinaries\": [\"git\", \"npm\", \"node\"],\n        \"requireApproval\": true\n      }\n    },\n    \"policy\": {\n      \"source\": \"oci://ghcr.io/my-org/policy:latest\"\n    },\n    \"secrets\": {\n      \"GITHUB_TOKEN\": \"vault://vault.corp/secret/github#token\",\n      \"NPM_TOKEN\":    \"op://Engineering/npm/token\"\n    }\n  }\n}\n```\n\nFull schema reference: [SPEC.md](./SPEC.md)\n\n---\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────┐\n│  Host (trusted)                                     │\n│                                                     │\n│  agentcontainer CLI ─────────────────────────────  │\n│     │                                               │\n│     ▼                                               │\n│  Agentcontainer Runtime                             │\n│     ├── Policy engine (config → ContainerPolicy)    │\n│     ├── Approval broker (human-in-the-loop gating)  │\n│     ├── Secrets manager (OIDC / Vault / 1Password)  │\n│     └── OCI verifier (Sigstore / lockfile)          │\n│     │                                               │\n│     ▼           gRPC                                │\n│  ┌──────────────────────────────────────────────┐  │\n│  │  Isolated OCI Container (UNTRUSTED)          │  │\n│  │    └── Agent process (Claude Code, etc.)     │  │◄──── Developer / IDE\n│  └──────────────────────────────────────────────┘  │\n│     │                                               │\n│     ▼           gRPC                                │\n│  agentcontainer-enforcer sidecar (Rust + Aya eBPF)             │\n│     ├── cgroup/connect4/sendmsg BPF hooks           │\n│     ├── LSM file_open hook (credential gating)      │\n│     └── WASM Component tool host                   │\n└─────────────────────────────────────────────────────┘\n```\n\nEnforcement is **fail-closed**: if the enforcer sidecar is unavailable, the container does not start.\n\nFor full architecture details, threat model, and design decisions: [SPEC.md](./SPEC.md)\n\n---\n\n## Development\n\n```bash\nmise run build          # build binary to tmp/agentcontainer\nmise run test           # go test -race ./...\nmise run test:cover     # tests with coverage report\nmise run lint           # golangci-lint\nmise run dev            # live reload with air\n\n# Before declaring work complete:\ngo build ./... \u0026\u0026 go vet ./... \u0026\u0026 go test -race ./...\n```\n\nRepository layout:\n\n| Path | What's there |\n|------|-------------|\n| `cmd/agentcontainer/` | Binary entry point |\n| `internal/cli/` | Cobra command definitions, one file per command |\n| `internal/config/` | Schema types, JSONC parser, validator |\n| `internal/container/` | Runtime backends (Docker, Compose, Sandbox) |\n| `internal/enforcement/` | gRPC strategy, policy translation |\n| `internal/signing/` | Sigstore/cosign integration, SLSA provenance |\n| `internal/oci/` | OCI Distribution Spec client, push/pull |\n| `internal/orgpolicy/` | Org policy extraction, merge, comparison |\n| `internal/secrets/` | Secret provider implementations |\n| `enforcer/` | Rust: agentcontainer-ebpf (Aya BPF), agentcontainer-enforcer (Tokio gRPC) |\n| `SPEC.md` | Full specification (~1600 lines) |\n| `ROADMAP.md` | Milestone plan with status |\n| `prd/` | Per-feature PRDs |\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## Security\n\nSee [SECURITY.md](./SECURITY.md) for the vulnerability reporting policy and threat model.\n\n## License\n\nApache 2.0. See [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkubedoll-heavy-industries%2Fagentcontainers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkubedoll-heavy-industries%2Fagentcontainers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkubedoll-heavy-industries%2Fagentcontainers/lists"}