Skip to content
CengridCengridCengrid Docs

The deployment directory

A Cengrid deployment is a committed, portable directory. The cengrid CLI is the only interpreter of that directory. It validates the same inputs it uses to render containers, task definitions, secret routing and the agent-computer layer.

Layout

Section titled “Layout”
  • cengrid.config.jsonc
  • package.json pins the CLI version that scaffolded the directory
  • package-lock.json
  • deployment.md runbook an agent can follow
  • Directory.codex/skills/deploy-cengrid/ the same runbook as a skill
    • …
  • AGENTS.md guidance for coding agents working in the directory
  • .env.example secret names and descriptions, no values
  • .env local values, never committed
  • slack-app-manifest.yml
  • slack-sso-manifest.yml only with Slack OpenID
  • Directorysandbox/
    • Dockerfile optional
    • Directorytools/
      • Directorytool-id/
        • tool.json
    • Directoryskills/
      • Directoryskill-id/
        • SKILL.md
  • Directoryplugins/ extra services, one Dockerfile each
    • …
  • Directoryinfra/ AWS only: the reference Terraform module
    • …

contract: 1 is the compatibility floor. Unknown contract majors fail closed, and a new incompatible directory shape increments the major. cengrid init never overwrites an existing config.

Required configuration

Section titled “Required configuration”

The root object requires:

Field Meaning
contract Must be 1.
orgId Short identifier. App and container names derive from it.
publicUrl The one public address. The CLI derives the core, Slack, web, admin and portal URL environment from it. On AWS a real harness requires HTTPS.
target docker, fly or aws. Fixed at init. Changing provider means a new directory.
services Must include core. First-party options: slack, web-ui, admin, portal, auth. The auth broker needs portal.

Common optional fields include botName, orgName, modelProvider, model, plugins, skills, per-service env, image overrides, sandbox and securityScreen. See configuration.

Sandbox tools and skills

Section titled “Sandbox tools and skills”

sandbox/ adds tools and skills to agent computers. Only a tool’s id is required; the other fields buy runtime guarantees:

Field Guarantee
label Human-readable name in resident-login status.
advertise Added to the agent computer’s installed-CLI list.
hints Added to the model’s guidance about deployment tools.
auth.check, auth.reauth Merged into the resident-login connector registry.
auth.credentialPaths $HOME-relative { path, kind } entries, each a file or directory. Absolute paths and traversal are rejected.
egress Validated as host names and checked for dangerous wildcards. Runtime enforcement is not claimed in v1.
approvals Appended to the command-policy floor. May deny or require approval for the tool’s own commands, never loosen policy.
install.binary Must be present in the layer or installed by the Dockerfile. The image build checks PATH.

Skills need name and description frontmatter. Skill assets delivered through the layer are text in v1, so binaries belong in the sandbox image.

When sandbox/ exists, every cengrid up sends the descriptors and text skill trees to core. Core validates them again, stores them in Postgres, versions them by a SHA-256 content hash and records an audit event.

The normal lifecycle

Section titled “The normal lifecycle”
  1. cengrid check: validates the config, computed secret names, tools, skills and plugins without building anything. It also verifies provider credentials whose values are present locally.
  2. cengrid doctor: read-only external checks.
  3. Build the substrate image: sandbox publish on Docker and Fly, infra build-image on AWS.
  4. cengrid plan: render without mutating.
  5. cengrid up: deploy. Build service images from your checkout with --build-from <path-to-checkout>. AWS mutation requires --yes; the Docker and Fly targets do not accept it.
  6. cengrid check --live: verify the running deployment.

On AWS, up is mutually excluded by a DynamoDB lease, takes a manual RDS snapshot before its first mutation, registers digest-pinned task definitions, enables the ECS circuit breaker, updates services and waits until they are stable. rollback restores the previous deployment manifest as one unit and prints the pre-deploy database snapshot to restore, because rollback restores code and configuration, never data.