Templates

Node.js

The node template installs the current Node.js LTS release through nvm:

weave create node-dev --template node

Python

The python template installs Python through uv:

weave create py-dev --template python

Custom Lima YAML

Pass a path to your own Lima YAML file:

weave create custom-dev --template ./templates/custom.yaml

Relative paths are resolved from the directory where you run Weave.

Coding agent templates

The following examples create Ubuntu VMs with a coding agent installed. Save the YAML you want as a template file, render your API key into a separate file, and pass that rendered file to Weave.

API keys are stored in the VM

Rendering one of these examples places the key in the rendered YAML and in the VM environment. Restrict the rendered file to your user, do not commit it, and delete it when you no longer need it.

Codex CLI

Save this as codex.yaml.tmpl:

minimumLimaVersion: 2.2.0

base:
  - template:default

env:
  OPENAI_API_KEY: "${OPENAI_API_KEY}"

provision:
  - mode: system
    script: |
      #!/bin/bash
      set -eux -o pipefail
      export DEBIAN_FRONTEND=noninteractive
      apt-get update
      apt-get install -y ca-certificates curl git

  - mode: user
    script: |
      #!/bin/bash
      set -eu -o pipefail
      export PATH="${HOME}/.local/bin:${PATH}"

      curl -fsSL https://chatgpt.com/codex/install.sh | sh
      printenv OPENAI_API_KEY | codex login --with-api-key

      if ! grep -Fq 'export PATH="$HOME/.local/bin:$PATH"' "${HOME}/.profile" 2>/dev/null; then
        printf '\nexport PATH="$HOME/.local/bin:$PATH"\n' >>"${HOME}/.profile"
      fi

probes:
  - script: |
      #!/bin/bash
      export PATH="${HOME}/.local/bin:${PATH}"
      codex --version
      codex login status
    hint: Codex CLI could not be installed or authenticated.

Export your key, render only that variable, and create the VM:

: "${OPENAI_API_KEY:?Set OPENAI_API_KEY first}"
envsubst '$OPENAI_API_KEY' <codex.yaml.tmpl >codex.yaml
chmod 600 codex.yaml
weave create codex-dev --template ./codex.yaml

Codex requires an explicit API-key login. The provisioning step pipes OPENAI_API_KEY to the supported login command without printing the key. See the Codex CLI documentation for other installation and sign-in options.

Claude Code

Save this as claude-code.yaml.tmpl:

minimumLimaVersion: 2.2.0

base:
  - template:default

env:
  ANTHROPIC_API_KEY: "${ANTHROPIC_API_KEY}"

provision:
  - mode: system
    script: |
      #!/bin/bash
      set -eux -o pipefail
      export DEBIAN_FRONTEND=noninteractive
      apt-get update
      apt-get install -y ca-certificates curl git

  - mode: user
    script: |
      #!/bin/bash
      set -eu -o pipefail

      curl -fsSL https://claude.ai/install.sh | bash

      if ! grep -Fq 'export PATH="$HOME/.local/bin:$PATH"' "${HOME}/.profile" 2>/dev/null; then
        printf '\nexport PATH="$HOME/.local/bin:$PATH"\n' >>"${HOME}/.profile"
      fi

probes:
  - script: |
      #!/bin/bash
      export PATH="${HOME}/.local/bin:${PATH}"
      claude --version
    hint: Claude Code could not be installed.

Export your key, render only that variable, and create the VM:

: "${ANTHROPIC_API_KEY:?Set ANTHROPIC_API_KEY first}"
envsubst '$ANTHROPIC_API_KEY' <claude-code.yaml.tmpl >claude-code.yaml
chmod 600 claude-code.yaml
weave create claude-dev --template ./claude-code.yaml

Claude Code detects ANTHROPIC_API_KEY when it starts and asks you to approve the key instead of showing the normal login prompt. See the Claude Code documentation for other installation and authentication options.

envsubst is provided by the gettext package on Linux and by brew install gettext on macOS.

Cached bases

Weave prepares reusable bases for the default environment and the built-in node and python templates. The first create provisions and stops an internal base; later creates clone it, which avoids repeating package and container-tooling installation.

A base remains fresh for three days. Weave creates a new base when that window expires or when its template, Weave version, Lima version, architecture, virtualization backend, or relevant VM configuration changes. Internal bases do not appear in weave ls.

Bypass the cache for one new VM with --fresh:

weave create node-dev --template node --fresh

--fresh provisions that VM from scratch without deleting or updating the cached base. Custom Lima YAML files are not cached and always follow the same cold-provisioning path.

Cold creates show progress

Weave reports image downloads, package index and dependency downloads, and container-tooling setup while Lima provisions a base or fresh VM. Progress recognizes output from APT, DNF/YUM, APK, and Pacman-based guests.

New VMs only

Choose a template or --fresh when you first create a VM. Weave rejects template changes when restarting an existing VM and ignores cache selection for restarts.