Customizing VM Images

Release VM images are defined by Profile V2 payloads and built through capsem-admin image build. The TOML configs under guest/config/ remain a developer input for built-in profile generation and the current Docker templates; they are not the corporate release authority.

For corp/operator workflows, use Admin CLI and Custom Images Reference. This page is for developers editing the repo internals.

The config directory

guest/
    config/
        build.toml              Build settings (base image, compression, kernel branch)
        manifest.toml           Package metadata
        ai/
            anthropic.toml      Claude Code provider
            google.toml         Gemini CLI provider
            openai.toml         Codex provider
        packages/
            apt.toml            System packages (coreutils, git, curl, python3, ...)
            python.toml         Python packages (numpy, requests, pytest, ...)
        mcp/
            capsem.toml         Built-in MCP server
        security/
            web.toml            Domain allow/block policy
        vm/
            resources.toml      CPU, RAM, disk limits
            environment.toml    Shell config, bashrc, PATH, TLS
        kernel/
            defconfig.arm64     Kernel config (arm64)
            defconfig.x86_64    Kernel config (x86_64)
    artifacts/
        banner.txt              Login banner (ASCII art shown at session start)
        tips.txt                Random tips (one shown per login)
        capsem-bashrc           Shell configuration (PS1, aliases, banner/tips display)
        capsem-init             PID 1 init script
        capsem-doctor           In-VM diagnostic suite
        capsem-bench            In-VM benchmarks
        diagnostics/            Test scripts for capsem-doctor

Common changes

Add a system package

Edit guest/config/packages/apt.toml:

[apt]
packages = [
    # ... existing packages ...
    "your-package",
]

Add a Python package

Edit guest/config/packages/python.toml:

[python]
packages = ["numpy", "pandas", "requests", "pytest", "your-package"]

Add an AI provider

Create guest/config/ai/your-provider.toml:

[your_provider]
name = "Your Provider"
description = "Your LLM provider"
enabled = true

[your_provider.api_key]
name = "API Key"
env_vars = ["YOUR_PROVIDER_API_KEY"]
prefix = "sk-"
docs_url = "https://your-provider.com/keys"

[your_provider.network]
domains = ["api.your-provider.com"]
allow_get = true
allow_post = true

[your_provider.install]
manager = "npm"
prefix = "/opt/ai-clis"
packages = ["your-provider-cli"]

Change security controls

For release profiles, change the Profile V2 enforcement or detection pack and rebuild/verify the profile-owned assets with capsem-admin. Repo-local guest/config/security/web.toml is only a developer input for built-in profile generation.

[security.rules.http.allow_corp]
on = "http.request"
if = 'http.request.host.endsWith(".your-corp.com")'
decision = "allow"
priority = 10

Edit guest/artifacts/tips.txt — one tip per line, # lines are ignored. A random tip is shown each time a user opens a session:

pip install and uv pip install work out of the box.
npm install -g works -- packages go to your scratch disk.
Run capsem-doctor to verify sandbox integrity.
Your custom tip here.

Edit guest/artifacts/banner.txt — shown at the top of every new session, before the AI tool status and tips.

Change VM resources

Edit guest/config/vm/resources.toml:

[resources]
cpu_count = 8
ram_gb = 8
scratch_disk_size_gb = 32

Rebuild and test

After editing configs:

# 1. Validate your changes (fast, catches typos)
uv run capsem-builder validate guest/

# 2. Preview the profile-derived Dockerfile without building
uv run capsem-admin image build config/profiles/base/coding.profile.toml --dry-run --json

# 3. Rebuild the rootfs (kernel rebuild only needed if you changed defconfig)
just build-rootfs

# 4. Boot and verify
just run "capsem-doctor"

If you changed kernel config, rebuild everything:

just build-assets
just run "capsem-doctor"

What triggers a full rebuild?

What you changed	Rebuild command
`packages/*.toml`	`just build-rootfs`
`ai/*.toml`	`just build-rootfs`
`mcp/*.toml`	`just build-rootfs`
`security/web.toml`	No rebuild — applied at boot via settings
`vm/resources.toml`	No rebuild — applied at boot via settings
`vm/environment.toml`	No rebuild — applied at boot via settings
`kernel/defconfig.*`	`just build-kernel`
`build.toml`	`just build-assets` (full rebuild)
`guest/artifacts/tips.txt`	`just build-rootfs` (baked into rootfs)
`guest/artifacts/banner.txt`	`just build-rootfs` (baked into rootfs)
`guest/artifacts/capsem-bashrc`	`just build-rootfs` (baked into rootfs)
`guest/artifacts/capsem-init`	`just run` (repacks initrd automatically)

Profile/settings-only changes take effect through the service/profile resolver on the next VM create or reload path. They do not rely on a generated defaults.json runtime authority.

Builder CLI reference

uv run capsem-builder validate guest/           # lint all configs
uv run capsem-builder inspect guest/            # show resolved config summary
uv run capsem-admin image build config/profiles/base/coding.profile.toml --arch arm64
uv run capsem-admin image build config/profiles/base/coding.profile.toml --dry-run --json
uv run capsem-admin doctor --profile config/profiles/base/coding.profile.toml