# Extend templates

There are a variety of Coder-native features to extend the configuration of your development environments.
Many of the following features are defined in your templates using the [Coder Terraform provider](https://registry.terraform.io/providers/coder/coder/latest/docs).
The provider docs will provide code examples for usage.
Alternatively, you can view our [example templates](https://github.com/coder/coder/blob/main/examples/templates) to get started.

## Workspace agents

For users to connect to a workspace, the template must include a [`coder_agent`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent).
The associated agent will facilitate [workspace connections](/docs/@main/workspaces/workspace-access/) via SSH, port forwarding, and IDEs.
The agent can also display real-time [workspace metadata](/docs/@main/templates/extending-templates/agent-metadata/) like resource usage.

```tf
resource "coder_agent" "dev" {
  os   = "linux"
  arch = "amd64"
  dir  = "/workspace"
  display_apps {
    vscode = true
  }
}
```

You can also leverage [resource metadata](/docs/@main/templates/extending-templates/resource-metadata/) to display static resource information from your template.

Templates must include some computational resource to start the agent.
All processes on the workspace are then spawned from the agent.
It also provides all information displayed in the dashboard's workspace view.

![A healthy workspace agent](/docs/@main/images/templates/healthy-workspace-agent.png)

Multiple agents can be used in a single template or even a single resource.
Each agent can have its own apps, startup script, and metadata.
This can be used to associate multiple containers or VMs with a workspace.

## Resource persistence

The resources you define in a template can be *ephemeral* or *persistent*.
Persistent resources stay provisioned when workspaces are stopped, where as ephemeral resources are destroyed and recreated on restart.
All resources are destroyed when a workspace is deleted.

You can read more about how resource behavior and workspace state in the [workspace lifecycle documentation](/docs/@main/workspaces/workspace-lifecycle/).

Template resources follow the [behavior of Terraform resources](https://developer.hashicorp.com/terraform/language/resources/behavior#how-terraform-applies-a-configuration) and can be further configured  using the [lifecycle argument](https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle).

A common configuration is a template whose only persistent resource is the home directory.
This allows the developer to retain their work while making sure the rest of their environment is consistently up-to-date on each workspace restart.

When a workspace is deleted, the control plane essentially runs a [terraform destroy](https://www.terraform.io/cli/commands/destroy) to remove all resources associated with the workspace.

<Callout type="success" title="Tip">
  Terraform's [prevent-destroy](https://www.terraform.io/language/meta-arguments/lifecycle#prevent_destroy) and [ignore-changes](https://www.terraform.io/language/meta-arguments/lifecycle#ignore_changes) meta-arguments can be used to prevent accidental data loss.
</Callout>

## Coder apps

Additional IDEs, documentation, or services can be associated to your workspace using the [`coder_app`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app) resource.

![Coder Apps in the dashboard](/docs/@main/images/admin/templates/coder-apps-ui.png)

Note that some apps are associated to the agent by default as [`display_apps`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#nested-schema-for-display_apps) and can be hidden directly in the [`coder_agent`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent) resource.
You can arrange the display orientation of Coder apps in your template using [resource ordering](/docs/@main/templates/extending-templates/resource-ordering/).

### Coder app examples

You can use these examples to add new Coder apps:

<Tabs items="[&#x22;code-server&#x22;, &#x22;Filebrowser&#x22;, &#x22;Zed&#x22;]" groupId="coder-docs-tab:code-server-filebrowser-zed" persist="true">
  <Tab value="code-server" id="code-server">
    ```tf
    resource "coder_app" "code-server" {
      agent_id     = coder_agent.main.id
      slug         = "code-server"
      display_name = "code-server"
      url          = "http://localhost:13337/?folder=/home/${local.username}"
      icon         = "/icon/code.svg"
      subdomain    = false
      share        = "owner"
    }
    ```
  </Tab>

  <Tab value="Filebrowser" id="filebrowser">
    ```tf
    resource "coder_app" "filebrowser" {
      agent_id     = coder_agent.main.id
      display_name = "file browser"
      slug         = "filebrowser"
      url          = "http://localhost:13339"
      icon         = "/icon/database.svg"
      subdomain    = true
      share        = "owner"
    }
    ```
  </Tab>

  <Tab value="Zed" id="zed">
    ```tf
    resource "coder_app" "zed" {
        agent_id = coder_agent.main.id
        slug          = "slug"
        display_name  = "Zed"
        external = true
        url      = "zed://ssh/coder.${data.coder_workspace.me.name}"
        icon     = "/icon/zed.svg"
    }
    ```
  </Tab>
</Tabs>

Visit our [module registry](https://registry.coder.com/modules) for additional Coder apps from the team and our open source software (OSS) community.

### Session tokens in external app links

An external app's `url` can include the `$SESSION_TOKEN` placeholder so a desktop IDE can sign in to Coder.
The dashboard and `coder open app` replace the placeholder with the user's session token only when all of these are true:

* The link opens a Coder IDE extension, such as `vscode://coder.coder-remote/open` or `jetbrains://gateway/com.coder.toolbox`.
* The link's `url` parameter is this deployment's URL, with no path.
* The placeholder is the whole value of the link's `token` parameter.

When a link with the placeholder doesn't meet these conditions, Coder doesn't add a token.
`coder open app` prints the link with a warning instead of opening it.
The dashboard shows the app as disabled, except for `http` and `https` links, which open with the placeholder left in place.
Links without the placeholder open as written.
Dev container apps never receive a session token.
Refer to [Customizing dev containers](/docs/@main/workspaces/devcontainers/customizing-dev-containers/) for details.

## Environment variables

Use the [`coder_env`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/env) resource to inject environment variables into workspace agents.
Multiple resources can target the same variable using [merge strategies](/docs/@main/templates/extending-templates/environment-variables/) like `append` and `prepend`, which is useful for building up `PATH`-style variables across modules.

See [Environment variables](/docs/@main/templates/extending-templates/environment-variables/) for details.

<a id="running-scripts-on-workspace-lifecycle"></a>

## Run scripts on workspace lifecycle events

The [`coder_script`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/script) resource runs scripts during workspace lifecycle events like startup, stop, or on a scheduled basis.
It provides more control than the `startup_script` field in `coder_agent`.

### When to use coder\_script

* **Initialization tasks**:
  Install dependencies, clone repositories, configure services
* **Cleanup tasks**:
  Stop services gracefully on workspace stop
* **Scheduled maintenance**:
  Run periodic tasks via cron schedules
* **Blocking startup**:
  Wait for critical services before allowing user login

### Basic example

```tf
resource "coder_script" "install_dependencies" {
  agent_id           = coder_agent.main.id
  display_name       = "Install Dependencies"
  icon               = "/icon/terminal.svg"
  script             = <<-EOF
    #!/bin/sh
    set -e
    apt-get update
    apt-get install -y git curl
  EOF
  run_on_start       = true
  start_blocks_login = true
}
```

### Key features

* **Lifecycle control**:
  Run on start (`run_on_start`), stop (`run_on_stop`), or cron schedule (`cron`)
* **Login blocking**:
  Use `start_blocks_login = true` to make sure critical setup completes before user access
* **Timeouts**:
  Configure `timeout` for long-running scripts
* **Custom icons**:
  Display meaningful icons with the `icon` parameter
* **Log capture**:
  Script output is automatically captured and visible in the workspace UI

### Advanced patterns

Many [Coder modules](https://registry.coder.com/modules) use `coder_script` internally.
For example:

* [`git-clone`](https://registry.coder.com/modules/coder/git-clone): Clones repositories on startup
* [`dotfiles`](https://registry.coder.com/modules/coder/dotfiles): Applies user dotfiles
* [`code-server`](https://registry.coder.com/modules/coder/code-server): Installs and configures code-server (VS Code in the browser)

You can also reference external script files:

```tf
resource "coder_script" "init_docker" {
  agent_id     = coder_agent.main.id
  display_name = "Initialize Docker"
  script       = file("${path.module}/scripts/init-docker.sh")
  run_on_start = true
}
```

See the [Coder Terraform provider documentation](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/script) for complete reference.

<children></children>
