| name | run-keystone |
| description | How to install and run the Keystone CLI to generate devcontainers |
| advertise | true |
Running Keystone
Keystone generates a working .devcontainer/ configuration for any git repository. It creates a devcontainer.json, Dockerfile, and run_all_tests.sh by running a coding agent inside a Modal sandbox.
Installation
pip install imbue-keystone
uvx imbue-keystone --help
Both install the keystone CLI command.
Prerequisites
- Modal account — sign up here, then
modal token set
$ANTHROPIC_API_KEY — set in your environment (used by the agent inside the sandbox)$DOCKER_REGISTRY_MIRROR — URL of a Docker Hub pull-through cache (e.g. https://mirror.gcr.io), required when running in Modal
Basic usage
git clone https://github.com/psf/requests
keystone \
--project_root ./requests \
--provider claude \
--model claude-opus-4-6 \
--claude_reasoning_level medium \
--max_budget_usd 1.0 \
--test_artifacts_dir /tmp/test_artifacts
CLI options
| Flag | Default | Description |
|---|
--project_root | (required) | Path to the git repo |
--test_artifacts_dir | (required) | Directory for JUnit XML test reports |
--provider | claude | LLM provider: claude, codex, or opencode |
--model | (required) | Model identifier (see below) |
--max_budget_usd | 1.0 | Cost cap for agent inference |
--agent_time_limit_seconds | 3600 | Agent timeout |
--image_build_timeout_seconds | 1800 | Docker build timeout |
--test_timeout_seconds | 1800 | Test suite timeout |
--agent_in_modal / --run_agent_locally_with_dangerously_skip_permissions | Modal | Run in Modal sandbox (default) or locally |
--claude_reasoning_level | (required for claude) | low, medium, or high |
--codex_reasoning_level | (required for codex) | low, medium, or high |
--guardrail / --no_guardrail | enabled | Structural checks on agent output |
--use_agents_md / --no_use_agents_md | disabled | Use AGENTS.md + short prompt instead of full inline prompt |
--log_db | ~/.imbue_keystone/log.sqlite | SQLite or PostgreSQL URL for caching/logging |
Available models
| Provider | Model ID | Enum |
|---|
| claude | claude-opus-4-6 | LLMModel.OPUS |
| claude | claude-haiku-4-5-20251001 | LLMModel.HAIKU |
| codex | gpt-5.1-codex-mini | LLMModel.CODEX_MINI |
| codex | gpt-5.2-codex | LLMModel.CODEX |
| codex | gpt-5.3-codex | LLMModel.CODEX_53 |
| codex | gpt-5.4 | LLMModel.GPT_54 |
| opencode | anthropic/claude-opus-4-6 | LLMModel.OPENCODE_OPUS |
| opencode | anthropic/claude-haiku-4-5 | LLMModel.OPENCODE_HAIKU |
| opencode | openai/gpt-5.1-codex-mini | LLMModel.OPENCODE_CODEX_MINI |
| opencode | openai/gpt-5.2-codex | LLMModel.OPENCODE_CODEX |
| opencode | openai/gpt-5.4 | LLMModel.OPENCODE_GPT_54 |
Output
Keystone writes a BootstrapResult JSON to stdout (or --output_file) containing:
success — whether the devcontainer was built and tests passedagent — execution details (duration, cost, tokens, status messages)verification — image build time, test execution time, pass/fail countsgenerated_files — contents of the generated devcontainer.json, Dockerfile, and run_all_tests.sherror_message — what went wrong (if anything)
The generated .devcontainer/ directory is also written directly into --project_root.
Examples
keystone --project_root ./myrepo --provider claude --model claude-opus-4-6 \
--claude_reasoning_level high --max_budget_usd 5.0 \
--test_artifacts_dir /tmp/artifacts
keystone --project_root ./myrepo --provider codex --model gpt-5.3-codex \
--codex_reasoning_level medium --max_budget_usd 5.0 \
--test_artifacts_dir /tmp/artifacts
keystone --project_root ./myrepo --provider opencode \
--model anthropic/claude-opus-4-6 --max_budget_usd 0 \
--test_artifacts_dir /tmp/artifacts
keystone --project_root ./myrepo --provider claude --model claude-opus-4-6 \
--claude_reasoning_level medium --max_budget_usd 1.0 \
--run_agent_locally_with_dangerously_skip_permissions \
--test_artifacts_dir /tmp/artifacts
uv run keystone --project_root ./myrepo --provider claude --model claude-opus-4-6 \
--claude_reasoning_level medium --max_budget_usd 1.0 \
--test_artifacts_dir /tmp/artifacts
