Runtime Home & Bootstrap¶
Introduction¶
Every mature engineering tool owns a runtime environment.
Examples include:
- Git (
.git) - Kubernetes (
~/.kube) - Google Cloud (
~/.config/gcloud) - Docker (
~/.docker) - Maven (
~/.m2) - Claude (
~/.claude)
These tools automatically create, manage, and maintain their runtime state.
Users are not expected to manually prepare the environment before using them.
An Engineering Runtime should follow the same principle.
It should own its runtime environment and prepare itself before executing any engineering operation.
What is a Runtime Home?¶
A Runtime Home is the local directory owned by the Engineering Runtime.
It stores runtime configuration rather than engineering artifacts.
For example:
~/.engineering-runtime/
config.yaml
policy-config.yaml
logs/
cache/
The Runtime Home becomes the single location where the runtime stores its operational state.
Why Does a Runtime Home Matter?¶
Imagine a new engineer installing an engineering runtime.
Should the engineer first execute:
mkdir ~/.engineering-runtime
Then create:
config.yaml
Then create:
policy-config.yaml
Then create:
logs/
Most modern engineering tools do not require these manual steps.
They prepare themselves automatically.
An Engineering Runtime should provide the same experience.
Runtime Ownership¶
The runtime should own everything inside its Runtime Home.
Examples include:
Configuration
config.yaml
Policy
policy-config.yaml
Execution Logs
logs/
Cache
cache/
The runtime manages these resources throughout its lifecycle.
Bootstrap¶
Bootstrap is the initialization process that prepares the runtime before any engineering operation begins.
Every public command should begin with Bootstrap.
Command
↓
Bootstrap
↓
Runtime Ready
↓
Execution
Bootstrap ensures the runtime is always ready before execution.
Responsibilities of Bootstrap¶
Bootstrap should perform lightweight validation and initialization.
Typical responsibilities include:
- Ensure Runtime Home exists
- Create missing directories
- Create default configuration
- Create default policy
- Validate configuration
- Load runtime settings
Bootstrap should complete quickly and deterministically.
What Bootstrap Should Not Do¶
Bootstrap should not perform expensive or external operations.
Examples include:
- Download software
- Refresh remote packages
- Authenticate users
- Execute engineering commands
These belong to dedicated runtime capabilities.
Bootstrap prepares the runtime.
It does not perform engineering work.
Runtime Initialization¶
Every engineering operation follows the same lifecycle.
User
↓
Engineering Runtime
↓
Bootstrap
↓
Authentication
↓
Context
↓
Policy
↓
Execution
↓
Audit
The runtime initializes itself before interacting with engineering platforms.
Runtime Home vs Project Files¶
A Runtime Home stores runtime state.
Project directories store engineering artifacts.
Runtime Home
~/.engineering-runtime/
config.yaml
policy-config.yaml
Project
terraform/
.github/
README.md
Keeping these concerns separate improves maintainability and portability.
Configuration¶
Runtime configuration belongs inside the Runtime Home.
Examples include:
- Authentication providers
- Default capability package source
- Runtime preferences
- Provider endpoints
These settings describe how the runtime behaves.
They are not part of engineering projects.
Design Principle¶
The runtime owns its environment. Users should never manually prepare it.
The runtime is responsible for ensuring its environment exists and is valid before execution begins.
Benefits¶
A Runtime Home provides:
- Consistent runtime initialization
- Reduced manual setup
- Predictable execution
- Centralized configuration
- Simplified troubleshooting
Bootstrap ensures these benefits are available before every engineering operation.
Looking Ahead¶
Once the runtime has initialized itself, another question arises:
How does an AI agent discover what the runtime is capable of?
The next article introduces Capability Packages, a mechanism for publishing engineering capabilities separately from the runtime itself.
Conclusion¶
A mature engineering runtime should behave like every other mature engineering platform.
It should own its runtime environment.
It should initialize itself automatically.
It should remove manual operational steps.
Runtime Home and Bootstrap provide the foundation that allows every engineering operation to begin from a known, deterministic state.
Design Principle¶
Prepare first. Execute second.
Bootstrap is responsible for preparing the runtime.
Engineering capabilities are responsible for performing work.
Next Article¶
Capability Packages and Registry