Browse all docs

Anvil Cloud / Overview

Anvil Cloud

Anvil Cloud is the project in anvil-cloud: a local-first TypeScript platform for small app units called Anvil Cells.

A Cell declares app behavior, data shape, and required capabilities. Anvil runs it locally through the same request boundary used by deployment adapters, then emits manifests, generated client metadata, and deploy artifacts that can be inspected before anything reaches a provider.

The goal is not to make AWS easier to spray around. The goal is to give developers and coding agents a smaller app contract that is easier to understand, test, review, and deploy through controlled adapters.

Current package layout

Package Role
@anvil-cloud/runtime Cell DSL, Agent definitions, provider-neutral agent runtime contracts, RuntimeRequest, RuntimeResponse, RuntimeHost, RuntimeContext, and handleRuntimeRequest.
@anvil-cloud/builder Config loading, import policy, typecheck, server/client bundle, manifest extraction, build metadata, and generated client files.
@anvil-cloud/local Local runtime server, JSON database adapter, local files, auth, logs, events, jobs, and inspection state.
@anvil-cloud/client Browser client and framework hook helpers for generated query and mutation metadata.
@anvil-cloud/auth Provider-neutral token verification: OIDC discovery/JWKS verification plus a local identity provider that signs real JWTs.
@anvilstack/cloud-cli anvil cloud new, dev, check, review, build, agents, inspect, logs, usage, db, auth, workflows, services, lens, deploy --preview, and rollback/destroy preview commands.
@anvil-cloud/control-plane The ControlPlaneApi contract behind Anvil Lens, implemented over the local runtime routes today and swappable for a hosted plane later.
@anvil-cloud/aws AWS preview adapter, CloudFormation synthesis, Lambda runtime bridge, AWS-backed host adapters, Bedrock inference provider, agent compatibility checks, artifact packaging, provisioning, remote inspect, remote logs, and preview cleanup.

Core terms

  • Anvil Cloud: the toolchain and docs for building Anvil Cells.
  • Anvil Cell: a deployable app unit with server functions, client UI, schema, endpoints, jobs, files, auth assumptions, environment needs, and declared capabilities.
  • Anvil Runtime: shared execution layer for local, test, and adapter-backed execution.
  • Anvil Builder: compiler and bundler that emits server bundle, client bundle, manifest, generated client output, and build metadata.
  • Anvil Local: local runtime server and state adapters.
  • Anvil Guard: import policy, capability checks, and safety validation.
  • Anvil Lens: inspection surface for manifest, runtime status, local auth, logs, database state, workflows, services, and diagnostics.
  • Anvil Agent: a portable, inspectable runtime unit with explicit capabilities, approval-gated actions, model configuration, and a provider-neutral manifest.
  • Agent Sandbox: an isolated, sessionful, inspectable workspace for agents that need sandboxed tool execution. On AWS, @anvil-cloud/aws provides a Lambda MicroVM-backed sandbox provider.

What works now

The alpha implementation includes:

  • object-based Cell DSL for app, query, mutation, endpoint, job, workflow, service, table, and field builders
  • contract-first Anvil Agents: defineAgent, provider-neutral agent manifests, mounted Cell Agents, local stub inference, provider registry, approval gates, tool capability checks, and AWS Bedrock provider support
  • Agent Sandbox contract and AWS Lambda MicroVM provider for sandbox-required agent workspaces
  • shared runtime request handling for query, mutation, endpoint, job, and workflow triggers
  • real authentication: declarative per-handler access control enforced by the runtime, a local identity provider signing real JWTs, and OIDC verification for any compliant provider via configuration
  • durable workflows: ordered typed steps with retries and timeouts, state persisted per transition, resumable after interruption
  • supervised services: long-running handlers with restart policies and clean shutdown
  • Anvil Lens: a local management UI over manifest, logs, database, auth users, workflow runs, and services
  • in-memory and local runtime host adapters
  • local HTTP runtime routes for queries, mutations, endpoints, mounted agents, auth, workflows, services, health, manifest, and inspection
  • local JSON database, files, events, jobs, and NDJSON logs
  • builder checks for config, forbidden imports, direct process.env, undeclared fetch, scheduled jobs, and capability use (database, files, outboundFetch, events, workflows, services)
  • typecheck, bundle, manifest extraction, generated client output, and build metadata
  • CLI commands with JSON output for automation, including anvil cloud agents validate, anvil cloud agents manifest, anvil cloud agents invoke, and anvil cloud auth token for agent-friendly authenticated sessions
  • AWS preview plan and CloudFormation synthesis
  • AWS-backed runtime host adapters for DynamoDB, S3, SQS, EventBridge events and scheduled jobs, Lambda env, OIDC token verification, workflow Step Functions starts when configured, and structured logs
  • optional AWS provisioning when required environment variables are configured
  • remote inspect and logs through deployment metadata and CloudWatch Logs
  • preview destroy that empties stack-owned buckets and removes deployment metadata when configured

Alpha boundaries

Current alpha limits include:

  • AWS is the first adapter, not the application contract.
  • Workflows execute end-to-end locally and map to Step Functions in AWS preview, but remote workflow run inspection is still maturing.
  • Services execute fully locally; AWS preview blocks service-bearing deploys until the Fargate runner executes the exact Cell service handler.
  • Outbound fetch policy is checked by Guard and enforced by the AWS Lambda runtime allow-list guard.
  • Production use needs wider operational validation beyond the preview verifier.
  • Agents are a contract/runtime foundation, not a hosted agent platform. Project-agent discovery and deterministic Guardian review exist; AWS Lambda MicroVM-backed Agent Sandboxes cover sandbox-required agents when configured. Production approval UI, durable multi-step orchestration, hosted memory, streamed sandbox tools, workspace snapshots, and sandbox-aware Lens views are future work.
  • Auth token verification is real locally and on AWS, but session/refresh lifecycle and login UI belong to your provider.
  • Anvil Lens is local-first; there is no hosted control plane, marketplace, or multi-region deployment.
  • No arbitrary provider-resource authoring or raw container/Kubernetes definitions in Cell code.
  • Safety comes from capability scoping, import restrictions, runtime adapters, generated provider policy, and deployment isolation, not a perfect JavaScript sandbox.

Read next

Anvil CLIQuickstart