# Reuse template code

To reuse code across different Coder templates, such as common scripts or resource definitions, we suggest using [Terraform Modules](https://developer.hashicorp.com/terraform/language/modules).

You can store these modules externally from your Coder deployment, like in a git repository or a Terraform registry.
This example shows how to reference a module from your template:

```tf
data "coder_workspace" "me" {}

module "coder-base" {
  source = "github.com/my-organization/coder-base"

  # Modules take in variables and can provision infrastructure
  vpc_name            = "devex-3"
  subnet_tags         = { "name": data.coder_workspace.me.name }
  code_server_version = "4.14.1"
}

resource "coder_agent" "dev" {
  # Modules can provide outputs, such as helper scripts
  startup_script=<<EOF
  #!/bin/sh
  ${module.coder-base.code_server_install_command}
  EOF
}
```

Learn more about [creating modules](https://developer.hashicorp.com/terraform/language/modules) and [module sources](https://developer.hashicorp.com/terraform/language/modules/sources) in the Terraform documentation.

## Coder modules

Coder publishes plenty of modules that can be used to simplify some common tasks across templates.
Some of the modules we publish are,

1. [`code-server`](https://registry.coder.com/modules/coder/code-server) and [`vscode-web`](https://registry.coder.com/modules/coder/vscode-web)
2. [`git-clone`](https://registry.coder.com/modules/coder/git-clone)
3. [`dotfiles`](https://registry.coder.com/modules/coder/dotfiles)
4. [`jetbrains`](https://registry.coder.com/modules/coder/jetbrains)
5. [`jfrog-oauth`](https://registry.coder.com/modules/coder/jfrog-oauth) and [`jfrog-token`](https://registry.coder.com/modules/coder/jfrog-token)
6. [`vault-github`](https://registry.coder.com/modules/coder/vault-github)

For a full list of available modules, check [Coder module registry](https://registry.coder.com/modules).

## AI agent modules

A template can install a terminal-based coding agent, such as Claude Code or Codex, in every workspace it creates.
In the [template builder](/docs/@main/templates/creating-templates/#template-builder), filter the **Select modules** step by the **AI Agent** category and select the agent.
To add an agent to a template you edit by hand, add the agent's module to the template's Terraform:

```tf
module "claude-code" {
  source   = "registry.coder.com/coder/claude-code/coder"
  version  = "~> 5.2"
  agent_id = coder_agent.main.id
}
```

Each agent module accepts its own authentication and configuration variables.
Visit the module's page in the [Coder Registry](https://registry.coder.com/modules) for the full list.
To let developers use a Claude subscription with Claude Code, refer to [Sign in to Claude Code with a Claude subscription](/docs/@main/workspaces/workspace-access/claude-code-subscription/).

To delegate work to an agent that runs in the Coder control plane instead of in the workspace, use [Coder Agents](/docs/@main/coder-agents/).

## Module caching

Module caching is enabled by default for all templates.
When you publish a new template version, Coder runs `terraform init` to resolve every module the template references, then archives the resulting `.terraform/modules` directory and stores it alongside that template version.
On every subsequent workspace build, Coder provisioners reuse this cached archive instead of re-fetching modules from their original sources (a git repository, the Coder registry, or another Terraform registry).
This avoids redundant network and disk I/O on each build and prevents build failures caused by a module source being slow or temporarily unavailable.

Coder limits cached module archives to 20 MB per template version.
If your modules exceed this limit, some are skipped and unavailable for [parameter](/docs/@main/templates/extending-templates/parameters/troubleshooting/#module-not-loaded-errors) evaluation, though builds still fetch the skipped modules directly.
Template versions published before Coder started archiving modules have no cache at all, which produces the same ["Module not loaded"](/docs/@main/templates/extending-templates/parameters/troubleshooting/#module-not-loaded-errors) warnings for every module in the workspace creation form.
Publishing a new template version fixes this.

To force Coder to re-download modules on every workspace build instead of using the cached archive, select **Disable Terraform module caching** in a template's **Settings** > **General** page, or set `disable_module_cache` to `true` with the [templates API](/docs/@main/reference/api/templates/#update-template-settings-by-id).

<Callout type="warn" title="Warning">
  Disabling module caching makes workspace builds slower and less predictable, since Terraform re-resolves and downloads every module on each build.
  Builds also stop reusing the [provider lock file](/docs/@main/workspaces/speed-up-templates/#template-lock-file) that Coder keeps when you publish the template version.
  This isn't recommended for production templates.
</Callout>

## Offline installations

In offline and restricted deployments, there are three ways to fetch modules.

1. Artifactory Remote Terraform Repository (Recommended)
2. Artifactory Local Repository (manual publishing)
3. Private git repository

### Artifactory Remote Terraform Repository (Recommended)

Configure Artifactory as a **Remote Terraform Repository** that proxies and caches the Coder registry.
This approach provides automatic updates and requires no manual synchronization.

See [Mirror the Coder Registry with JFrog Artifactory](/docs/@main/install/prepare/registry-mirror/) for complete setup instructions.

### Artifactory Local Repository

Air-gapped users can clone the [coder/registry](https://github.com/coder/registry/) repo and publish a [local terraform module repository](https://jfrog.com/help/r/jfrog-artifactory-documentation/terraform-opentofu-and-terraform-backend-repositories) to resolve modules via [Artifactory](https://jfrog.com/artifactory/).

1. Create a local-terraform-repository with name `coder-modules-local`

2. Create a virtual repository with name `tf`

3. Follow the below instructions to publish coder modules to Artifactory

   ```sh
   git clone https://github.com/coder/registry
   cd registry/registry/coder/modules
   jf tfc
   jf tf p --namespace="coder" --provider="coder" --tag="1.0.0"
   ```

4. Generate a token with access to the `tf` repo and set an `ENV` variable `TF_TOKEN_example.jfrog.io="XXXXXXXXXXXXXXX"` on the Coder provisioner.

5. Create a file `.terraformrc` with following content and mount at `/home/coder/.terraformrc` within the Coder provisioner.

   ```tf
   provider_installation {
     direct {
         exclude = ["registry.terraform.io/*/*"]
     }
     network_mirror {
         url = "https://example.jfrog.io/artifactory/api/terraform/tf/providers/"
     }
   }
   ```

6. Update module source as:

   ```tf
   module "module-name" {
     source = "example.jfrog.io/tf__coder/module-name/coder"
     version = "1.0.0"
     agent_id = coder_agent.example.id
     ...
   }
   ```

   Replace `example.jfrog.io` with your Artifactory URL

Based on the instructions [here](https://jfrog.com/blog/tour-terraform-registries-in-artifactory/).

#### Example template

We have an example template [here](https://github.com/coder/coder/blob/main/examples/jfrog/remote/main.tf) that uses our [JFrog Docker](https://github.com/coder/coder/blob/main/examples/jfrog/docker/main.tf) template as the underlying module.

### Private git repository

If you are importing a module from a private git repository, the control plane or [provisioner](/docs/@main/install/operate/provisioners/) needs git credentials.
Since this token will only be used for cloning your repositories with modules, it is best to create a token with access limited to the repository and no extra permissions.
In GitHub, you can generate a [fine-grained token](https://docs.github.com/en/rest/overview/permissions-required-for-fine-grained-personal-access-tokens?apiVersion=2022-11-28) with read only access to the necessary repos.

If you are running Coder on a VM, make sure that you have `git` installed and the `coder` user has access to the following files:

```sh
# /home/coder/.gitconfig
[credential]
  helper = store
```

```sh
# /home/coder/.git-credentials

# GitHub example:
https://your-github-username:your-github-pat@github.com
```

If you are running Coder on Docker or Kubernetes, `git` is pre-installed in the Coder image.
However, you still need to mount credentials.
This can be done via a Docker volume mount or Kubernetes secrets.

#### Pass git credentials in Kubernetes

First, create a `.gitconfig` and `.git-credentials` file on your local machine.
You might want to do this in a temporary directory to avoid conflicting with your own git credentials.

Next, create the secret in Kubernetes.
Be sure to do this in the same namespace that Coder is installed in.

```sh
export NAMESPACE=coder
kubectl apply -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: git-secrets
  namespace: $NAMESPACE
type: Opaque
data:
  .gitconfig: $(cat .gitconfig | base64 | tr -d '\n')
  .git-credentials: $(cat .git-credentials | base64 | tr -d '\n')
EOF
```

Then, modify Coder's Helm values to mount the secret.

```yaml
coder:
  volumes:
    - name: git-secrets
      secret:
        secretName: git-secrets
  volumeMounts:
    - name: git-secrets
      mountPath: "/home/coder/.gitconfig"
      subPath: .gitconfig
      readOnly: true
    - name: git-secrets
      mountPath: "/home/coder/.git-credentials"
      subPath: .git-credentials
      readOnly: true
```

### Next steps

* JFrog's [Terraform Registry support](https://jfrog.com/help/r/jfrog-artifactory-documentation/terraform-opentofu-and-terraform-backend-repositories)
* [Configuring the JFrog toolchain inside a workspace](/docs/@main/admin/integrations/jfrog-artifactory/)
* [Coder Module Registry](https://registry.coder.com/modules)
