anvil-app/
Anvil Desktop
Owns
Local developer workflow orchestration
Start in
src/main, src/preload, src/shared, src/renderer
Use when
A change needs repo context, review evidence, work item context, or local companion controls.
Open source tools for inspectable developer work
Local evidence before trust.
Anvil is a small family of developer tools: Desktop for repo-aware agent delivery, Registry for safer npm dependency ingress, and Cloud for inspectable app runtime contracts. The common rule is simple: make the work reviewable before anyone has to believe it.
anvil-cloud check --json
- Config
- valid
- Import policy
- pass
- Typecheck
- pass
- Build-ready
- true
One repo, four tools
Everything lives in the anvil-stack monorepo, but the split is intentional. Desktop coordinates local work, Registry controls dependency ingress, Node Base constrains install execution, and Cloud constrains app runtime contracts.
anvil-registry/
Anvil Registry and Node Base
Owns
npm dependency ingress and install execution safety
Start in
apps/gateway, apps/worker, apps/admin, apps/cli, packages, devcontainer-base
Use when
Installs need policy, caching, analysis, quarantine, overrides, reports, or safer container execution.
anvil-registry/devcontainer-base/
Anvil Node Base
Owns
Safer Node dependency installation
Start in
Dockerfile, scripts, README.md
Use when
An unknown repo needs npm installs with lifecycle scripts disabled or observed inside a container.
anvil-cloud/
Anvil Cloud
Owns
Cell runtime contracts and adapter deployment
Start in
packages/runtime, packages/builder, packages/local, packages/client, packages/cli, packages/aws
Use when
A small app or capability-bound agent should be authorable locally, inspectable before deployment, and deployable through an adapter boundary.
What each project does
The docs explain the mechanics. This is the short operational map.
Local delivery workspace
Anvil Desktop
anvil-app/
A chat-first Electron workspace for repo-aware agent delivery. It keeps conversations, repositories, work items, Git state, reviews, terminals, and handover evidence together while active work continues across workspace switches.
Boundary: Owns local delivery orchestration and evidence capture.
Status: Active desktop app with main, preload, shared IPC, and React renderer surfaces.
- Local Electron shell with SQLite persistence and typed IPC boundaries
- Chat-first workspace with focused navigation, thread history, and cross-workspace activity indicators
- Codex and LLM workflows grounded in checked-out repositories, with per-turn reasoning controls
- Optional Apple Foundation Models routing for short on-device helper prompts
- Workspace terminals reattach with buffered output while the desktop process is running
- Desktop notifications open the exact thread waiting for approval or input, or ready after completion
- Mobile, Raycast, watch, widget, and menu bar companion controls
pnpm dev
Inspectable app runtime
Anvil Cloud
anvil-cloud/
A local-first TypeScript platform for Anvil Cells and contract-first Agents: small runtime units with explicit capabilities, generated manifests, local inspection, approval gates, and adapter-driven deployment.
Boundary: Owns the Cell contract, Agent contract, runtime, auth, builder, local server, Lens, generated client, CLI, and deployment adapter boundary.
Status: Alpha implementation spans runtime, agents, auth, workflows, services, Lens, builder, local, client, CLI, and AWS preview packages.
- Cell DSL for queries, mutations, endpoints, jobs, durable workflows, supervised services, and mounted agents
- Contract-first Anvil Agents with capabilities, approvals, provider-neutral manifests, local stub inference, and AWS Bedrock provider support
- Agent Sandbox contract and AWS Lambda MicroVM provider for sandbox-required, sessionful agent workspaces
- Real auth: declarative per-handler access control, a local IdP signing real JWTs, OIDC providers by config
- Builder pipeline for import policy, typecheck, bundle, manifest, generated client output, and agent validation
- Anvil Lens local management UI plus an AWS preview adapter with CloudFormation synthesis
anvil-cloud check --json
npm policy gateway
Anvil Registry
anvil-registry/
A TypeScript registry gateway that proxies npm metadata and tarballs, evaluates deterministic policy, queues package analysis, caches artefacts, and records decisions before installs reach developers or CI.
Boundary: Owns dependency ingress, policy decisions, analysis, cache identity, and override audit.
Status: Alpha for local trials, security review, early CI experiments, and contribution work.
- npm-compatible Fastify gateway for metadata, tarballs, audit, and scoped upstreams
- Worker-backed static analysis, provenance signals, and optional LLM review context
- Postgres, object storage, queue adapters, Admin UI, CLI, Docker Compose, and SST
- Explicit audited overrides, quarantine/block decisions, and developer explain output
npm config set registry http://localhost:4873
Hardened Node image
Anvil Node Base
anvil-registry/devcontainer-base/
A Node 22 devcontainer base image for safer installs. Safe mode disables lifecycle scripts; observed mode runs them deliberately while writing inspectable reports.
anvil-npm-ci-safe
The useful promise is narrow
Anvil does not claim that agents, heuristics, or abstractions remove engineering judgement. It gives reviewers better artefacts to judge.
Local facts first
Desktop workflows start from local checkouts, branch state, typed IPC boundaries, SQLite state, Git, PTYs, and explicit connector configuration.
Policy beats theatre
Registry decisions come from deterministic package metadata, static findings, provenance, popularity, overrides, and cached immutable identities.
Runtime contracts stay small
Cloud Cells and Agents use constrained contracts. Provider SDKs and infrastructure authoring belong in adapters, not app code.
Agents help, they do not govern
Codex and LLM workflows can plan, implement, review, and explain. The authority still comes from repo evidence, deterministic gates, and human review.
Docs are part of the product
The public site is markdown-first so architecture, setup, limits, and status can be reviewed in Git with the code.
Docs for builders
Start with the public docs, then follow the links into commands, architecture, status notes, contribution paths, and the repo boundaries that matter.
Start here
Choose Desktop, Registry, Node Base, or Cloud from the project and workflow you actually need.
Monorepo map
See which project directory owns which product surface, where to look first, and how the pieces fit together.
Desktop architecture
Follow the Electron main, preload, shared IPC, renderer, SQLite, and service-layer boundaries.
Desktop agent workflows
Run planning, implementation, review, security, documentation, BA, and handover sessions with evidence.
Registry quickstart
Run the gateway locally, route package manager traffic through it, and inspect package decisions.
Registry policy
Read how metadata, provenance, static findings, popularity, analysis, and overrides shape decisions.
Cloud Cell contract
Understand app, schema, query, mutation, endpoint, job, capability, and generated manifest shapes.
Cloud Agents
Define capability-bound agents, mount them in Cells, compile manifests, and run local stub or provider mode.
Agent Sandboxes
Read the contract and AWS Lambda MicroVM provider path for sandbox-required agent workspaces.
Cloud CLI
Use anvil-cloud new, dev, check, build, inspect, logs, db, and deploy preview with stable JSON output.
Node Base reports
Inspect safe and observed install reports, submit them to the registry, and wire them into CI gates.
Open source posture
The scope boundaries, alpha notes, and anti-vendor-sludge position behind the project.
Contributing
Development setup, commit style, and review expectations across the Anvil monorepo.