AI Toolkit — a reference implementation for managing AI coding agents at scale

This repository is a reference implementation of how an organization can manage AI coding agents across many engineers and projects, using two composable building blocks:

• APM — an agent package manager. It packages the primitives an AI coding agent consumes (skills, agent definitions, project-instruction fragments, hooks, MCP server registrations) and distributes them into a project, fanning a single source definition out to each AI harness you target (Claude Code, GitHub Copilot, and others).
• Docker Sandboxes (sbx) — a containerized runtime that wraps the agent process in a microVM, so an agent running with high autonomy is bounded by an OS-level execution boundary, not just in-agent policy.

The packages and kits in this repo are worked examples, not the headline. The headline is the pattern: how you turn "every engineer configures their AI agent by hand" into a curated, versioned, auditable, sandbox-able stack that a platform team owns and every project installs. Fork this repo, swap the example content for your own, and you have your organization's agent platform.

The pattern, in one picture

   ┌─────────────────────────────────────────────────────────────┐
   │  APM packages  →  deploy PRIMITIVES into a project           │
   │     skills · agents · instructions · hooks · MCP servers     │
   │     (one source definition → fanned out per AI harness)      │
   ├─────────────────────────────────────────────────────────────┤
   │  Safety substrates  →  set the PERMISSION POSTURE            │
   │     base-readonly (deny-by-default) | base (exec + hooks)    │
   ├─────────────────────────────────────────────────────────────┤
   │  Docker sandbox  →  CONTAIN execution in a microVM           │
   │     wraps the agent process; workspace bind-mounted in       │
   └─────────────────────────────────────────────────────────────┘

Three independent layers. Packages deploy primitives; substrates set the safety posture; sandboxes contain execution. You can adopt any subset — primitives only, primitives plus a posture, or all three with sandboxed execution on top.

Building blocks

1. APM packages (the distribution layer)

Each unit of agent configuration is an APM package under packages/. A package is a self-contained, OpenAPM-conformant directory that APM installs directly from a git host by subpath — no clone, no central marketplace required, just read access to the repo:

You list the packages your project needs in a declarative apm.yml manifest and run apm install (see Installing below). APM owns the per-harness formatting: one source skill lands in the right place for Claude Code (.claude/skills/) and for Copilot (.agents/skills/); one source instruction or agent definition fans out to each target you declare. You author a primitive once; APM places it correctly everywhere.

This repo ships its agent primitives as APM packages so that adding or curating agent capability becomes a reviewable, versioned change — a pull request against a manifest, not a wiki page of copy-paste setup steps.

2. Safety substrates (the permission-posture layer)

Two cross-cutting packages set the agent's permission posture. A project picks one:

Substrate	Posture	Use it for
base-readonly	Locked-down, deny-by-default. Execution, web access, sub-agents, notebook edits denied; suggest-only.	Read-only / analysis / audit flows where the agent should never run code.
base	Execution-allowed, with safety hooks. Audit-logs every tool call (secrets redacted) and blocks dangerous shell patterns (curl|bash, rm -rf /, force-push).	Engineering / build / test flows where the agent needs to run code.

The substrates never coexist in one project — you choose the posture that matches the work.

3. Example kits (illustrative curation)

The remaining packages are examples of how you'd curate domain-specific capability for a team. They demonstrate the two supported kit shapes:

• APM-native kits aggregate upstream agent content directly as dependencies and let APM do the deployment. Use this when the upstream content is APM-addressable and your value is curation — choosing the right subset and wiring it together. The curated default stack and the research kit are examples.
• External-installer-wrapper kits ship a small setup.sh that dispatches to a complete, well-maintained upstream installer (curl-bash, npm, etc.). Use this when re-implementing the upstream under APM idiom would just fork working logic. The Databricks and AWS kits are examples.

These exist to show the mechanics of curation. When you adopt this repo, you'd replace them with kits for your own sectors and tools.

4. The companion-not-dependency model

A deliberate, load-bearing convention: kits do not bundle a safety substrate as a dependency. A kit ships its capability; its README recommends a companion substrate, which the consumer installs explicitly alongside it. This keeps the consumer in control of their own permission posture instead of inheriting one transitively, and keeps each install's footprint honest in the lockfile. The full curated experience is therefore always two explicit entries — the capability and its recommended posture, declared together:

# apm.yml
targets: [claude, copilot]
dependencies:
  apm:
    - rearc/ai-toolkit/packages/rearc-default-stack
    - rearc/ai-toolkit/packages/rearc-base-readonly

5. The Docker-sandbox runtime layer

For agents running with high autonomy, sandbox/ adds the outer boundary: it wraps the agent process in a microVM via Docker Sandboxes. This is a separate, orthogonal layer — not an APM package. APM deploys primitives into the project's files; the sandbox bind-mounts that same workspace at the same absolute path, so the project-level APM deployments (hooks, instructions, skills) are automatically visible inside the microVM. The two compose cleanly: the substrate hooks are per-tool-call inner policy; the sandbox is the outer process boundary.

bash sandbox/install/setup.sh        # one-time per host: installs sbx
cd <your project>
apm install                          # deploy primitives project-level (reads apm.yml)
sbx run claude .                     # launch the agent inside a microVM

Per-project runtime customization (network allowlists, credential routing, pre-installed CLIs) ships as sbx mixin kits under sandbox/kits/, one per APM package whose workflows have runtime needs. See sandbox/README.md and sandbox/docs/entrypoint.md for the full workflow.

Because the layers are orthogonal, you compose them independently — primitives only, primitives plus sandbox, sandbox only, or all of it. Nothing forces the sandbox on a consumer who only wants curated skills.

Installing

The recommended pattern follows APM's own guidance: declare what your project needs in apm.yml, commit it alongside the generated apm.lock.yaml, and run apm install. Every developer and every CI job then reproduces the same agent stack from version control.

# apm.yml  — commit this and apm.lock.yaml
targets: [claude, copilot]                              # AI harnesses to deploy to
dependencies:
  apm:
    - rearc/ai-toolkit/packages/rearc-default-stack     # curated capability
    - rearc/ai-toolkit/packages/rearc-base-readonly     # its recommended safety posture

apm install            # reads apm.yml; deploys to every target listed; writes apm.lock.yaml
apm install --frozen   # in CI: install exactly from the lockfile, refuse to drift

The targets: list is how you deploy to more than one harness — APM fans every primitive out to each target you name. Pin a package by appending #<tag-or-sha> to its ref (e.g. rearc/ai-toolkit/packages/rearc-base#v1.0.0) for reproducible builds; the resolved commit is recorded in apm.lock.yaml.

Multiple harnesses: targets: or the comma-separated flag both work (APM 0.20.0+). The declarative targets: list above is the recommended path — it travels with the manifest, so every install reproduces the same fan-out. The CLI flag apm install --target claude,copilot is equivalent and also deploys to every named target. (Heads-up if you're pinned to an older APM: on 0.18.0 the multi-value flag was broken — --target claude,copilot silently deployed to only the first target. That was fixed in 0.20.0 (apm#1749). On 0.18.0, use the targets: list.)

Quick add (imperative). To drop a single package into an existing project without hand-editing the manifest, apm install <ref> also works — it installs the package and writes the dependency into your apm.yml:

apm install rearc/ai-toolkit/packages/rearc-base --target claude

Some packages need a follow-up step their README documents — for example rearc/base-readonly ships a setup.sh that writes the permission baseline into your editor settings, run once after install. The execution-allowed rearc/base substrate is APM-native and needs no setup step.

Adopting and expanding this for your organization

This repo is meant to be forked and adapted, not consumed as-is. The recommended path:

1. Fork it to your own git host — for example your-org/ai-toolkit on GitHub Enterprise, GitLab self-managed, Azure DevOps, or Bitbucket. The repo is the install source; your other repositories install packages from it by subpath.
2. Swap in your own content. Replace the example kits with kits for your sectors and tools; adjust the two safety substrates to your organization's risk posture; add your own skills, agent definitions, instruction fragments, hooks, and MCP registrations. The package shape and conventions stay; the content becomes yours.
3. Host privately and install cross-repo by subpath. Consumers reference a package as your-org/ai-toolkit/packages/<pkg>#<tag-or-sha> in their own apm.yml, authenticate with one environment variable per host, and optionally govern centrally with an org policy file. The full hosting, authentication, governance, and air-gapped-install guide is enterprise-private-host.md.
4. Pin for reproducibility. Append #<tag-or-sha> to a ref, commit the resulting apm.lock.yaml, and enforce it in CI so installs don't drift.
5. Compose the sandbox layer where you want bounded autonomy, pairing each installed package with its matching sbx kit at launch.

Because both curation (the manifest) and posture (which substrate) are explicit, every change to your org's agent stack is a reviewable diff: a new capability is a one-line manifest edit; a posture change is a substrate swap; a new sector is a new kit directory.

Cross-platform support

APM deploys to the AI harnesses you select. Claude Code and GitHub Copilot are first-class and exercised across the packages. Cursor, OpenCode, Codex, and Gemini are supported via APM's deployment but are not actively tested here. As of APM 0.18.0 you must name your targets explicitly — declare a targets: list in your apm.yml (recommended, and the way to deploy to more than one harness), or pass a single --target <harness> on the CLI. With more than one harness present and no target named, a bare apm install asks you to choose rather than guessing.

Prerequisites

Tool	Why
apm CLI	All packages are APM-distributed. See the APM install guide.
jq	Used by the substrates' setup and hook scripts to parse JSON safely.
bash on PATH	Sidecar scripts are bash. On Windows, install Git for Windows or use WSL.
Docker Hub account + sbx	Only if you adopt the sandbox runtime layer. Free tier is sufficient.

Repository layout

.
├── README.md                 # this file
├── LICENSE
├── enterprise-private-host.md # private-fork hosting + cross-repo subpath installs
├── packages/                  # one APM package per building block
│   ├── rearc-base-readonly/   # deny-by-default safety substrate
│   ├── rearc-base/            # execution-allowed safety substrate (hooks + posture)
│   ├── rearc-default-stack/   # example: curated default experience
│   └── rearc-<sector>-kit/    # example sector kits (databricks, aws, research, ...)
└── sandbox/                   # Docker-sandbox runtime layer (install + docs + kits + probes)

Each package's own README.md is the authoritative source for its install flow, prerequisites, and configuration.