hip-1339

HIP-1339: Environment — Codebase Pre-Flight Environments, Sandboxed Scripts & Scoped Secrets. Status Final. Hanzo architectural specification.

HIP-1339: Environment — Codebase Pre-Flight Environments, Sandboxed Scripts & Scoped Secrets

Abstract

Package environment (/v1/environment) defines the pre-flight execution contract for software repositories before autonomous coding agents and execution harnesses launch. It standardizes the installation commands, background daemon start commands, and repository-scoped secret references required to make a codebase build, test, and run.

This proposal specifies the separation between proposed setups and saved environments, and the strict isolation of repository secrets in Hanzo KMS.

Motivation

Autonomous coding agents (such as hanzo dev) operate inside ephemeral microVM sandboxes (hanzoai/kata, hanzoai/visor). When an agent clones a codebase, it requires specific dependency installations (e.g. npm install, cargo fetch) and background services (e.g. database daemons, mock servers).

Without a standardized environment contract, agents either repeatedly guess build configurations or require manual developer intervention for every session. Furthermore, hardcoding development secrets into repositories or committing .env files violates zero-trust principles. A unified, repo-scoped environment specification provides reproducible agent runs while ensuring sensitive credentials stay sealed in KMS.

Specification

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are to be interpreted as in RFC 2119.

1. The Environment Lifecycle

• Setup Run: When an unconfigured repository is initialized, a setup agent explores the repository tree, detects toolchains, tests build commands, and generates an Environment proposal (state = proposed).
• Saved Environment: A human administrator reviews and saves the environment (state = ready). Once saved, every subsequent agent run executes the defined scripts automatically.
• Script Limits: Install scripts and start commands MUST NOT exceed 16 KiB (scriptCap = 16 << 10).

2. Secret Custody & Injection

• Secrets associated with a codebase are stored as names only in the environment manifest.
• Plaintext secret values MUST be sealed directly in Hanzo KMS under canonical paths:

/orgs/<org>/environment/<repo>/<SECRET_NAME>

• The API endpoints (GET /v1/environment, GET /v1/environment/:repo) MUST NEVER return plaintext secret values. Values are injected directly into ephemeral sandbox memory at runtime via KMS grants.
• Secret values are capped at 64 KiB (valueCap = 64 << 10).

3. HTTP Endpoints

| Method | Path | Description | |:---|:---|:---| | GET | /v1/environment | List environments for all repositories in the organization | | GET | /v1/environment/:repo | Get environment configuration for a specific repository | | PUT | /v1/environment/:repo | Save install commands, start commands, and environment settings | | DELETE | /v1/environment/:repo | Remove repository environment and purge associated secrets | | PUT | /v1/environment/:repo/secrets/:name | Set or update a repository-scoped secret (sealed in KMS) | | DELETE | /v1/environment/:repo/secrets/:name | Revoke a repository-scoped secret |