cleveragents-core/docs/reference/devcontainer_resources.md

Devcontainer Resources

Devcontainer resources integrate the Development Containers Specification into the CleverAgents resource model. Two resource types and an auto-discovery mechanism allow CleverAgents to detect, register, and use devcontainer environments automatically.

Resource Types

devcontainer-instance

A container execution environment defined by a .devcontainer/devcontainer.json configuration file. Inherits from container-instance (see ADR-042 for resource type inheritance).

Property	Value
Kind	physical
Sandbox strategy	snapshot
User-addable	yes
Parent types	git-checkout, fs-directory
Child types	devcontainer-file
Handler	DevcontainerHandler

CLI arguments:

• --path (path, required): Path to the directory containing .devcontainer/devcontainer.json.

devcontainer-file

A single-file resource pointing to the devcontainer.json configuration file itself. Created automatically as a child of devcontainer-instance during auto-discovery.

Property	Value
Kind	physical
Sandbox strategy	copy_on_write
User-addable	no
Parent types	devcontainer-instance
Child types	(none)
Handler	DevcontainerHandler

container-instance

The base container resource type from which devcontainer-instance inherits. Represents a generic container execution environment.

Property	Value
Kind	physical
Sandbox strategy	snapshot
User-addable	yes
Parent types	git-checkout, fs-directory
Child types	(none)
Handler	DevcontainerHandler

Auto-Discovery

When a git-checkout or fs-directory resource is linked to a project, the auto-discovery hook scans for devcontainer configurations in the following locations (relative to the resource root):

1. .devcontainer/devcontainer.json
2. .devcontainer.json (root-level)

Discovery Process

1. Trigger: Linking a git-checkout or fs-directory resource.
2. Scan: The discovery module checks for configuration files at the well-known paths listed above.
3. Validate: Each discovered file is parsed as JSON. Invalid files are skipped with a warning.
4. Register: For each valid configuration:
   • A devcontainer-instance child resource is created under the parent resource.
   • A devcontainer-file child resource is created under the devcontainer instance, pointing to the JSON file.

Lazy Activation

Devcontainers use lazy activation: the container is only built and started when first needed by a plan execution. The discovery phase only registers the resource metadata.

CLI Usage

# Manually add a devcontainer instance
agents resource add devcontainer-instance local/my-dc --path /home/user/project

# Add a container instance
agents resource add container-instance local/my-ctr --image ubuntu:latest

# List all devcontainer resources
agents resource list --type devcontainer-instance

# Show devcontainer details
agents resource show local/my-dc

# View resource tree (shows devcontainer children)
agents resource tree local/my-repo

# Inspect resource with tree view
agents resource inspect local/my-repo --tree

Architecture

The devcontainer integration follows ADR-043 and builds on the resource type inheritance model defined in ADR-042.

Handler

DevcontainerHandler extends BaseResourceHandler and uses the snapshot sandbox strategy. It handles both devcontainer-instance and devcontainer-file resource types through the common base class resolve logic.

Discovery Module

The cleveragents.resource.handlers.discovery module provides:

• discover_devcontainers(location, type): Scans a path for devcontainer configs.
• is_trigger_type(type): Checks if a resource type triggers auto-discovery.
• DevcontainerDiscoveryResult: Data class holding discovery results.

See Also

• ADR-042: Resource Type Inheritance
• ADR-043: Devcontainer Integration
• Resource Types (Built-in)
• Resource Handlers