HomeAdministrationTemplatesExtending Templates

Extending Templates

On this page

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. The provider docs will provide code examples for usage; alternatively, you can view our example templates to get started.

Workspace agents

For users to connect to a workspace, the template must include a coder_agent. The associated agent will facilitate workspace connections via SSH, port forwarding, and IDEs. The agent may also display real-time workspace metadata like resource usage.

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

You can also leverage 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

Multiple agents may be used in a single template or even a single resource. Each agent may 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 may 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.

Template resources follow the behavior of Terraform resources and can be further configured using the lifecycle argument.

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

When a workspace is deleted, the Coder server essentially runs a terraform destroy to remove all resources associated with the workspace.

Tip

Terraform's prevent-destroy and ignore-changes meta-arguments can be used to prevent accidental data loss.

Coder apps

Additional IDEs, documentation, or services can be associated to your workspace using the coder_app resource.

Coder Apps in the dashboard

Note that some apps are associated to the agent by default as display_apps and can be hidden directly in the coder_agent resource. You can arrange the display orientation of Coder apps in your template using resource ordering.

Coder app examples

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"
}

Check out our module registry for additional Coder apps from the team and our OSS community.

Environment variables

Use the coder_env resource to inject environment variables into workspace agents. Multiple resources can target the same variable using merge strategies like append and prepend, which is useful for building up PATH-style variables across modules.

See Environment variables for details.

Running scripts on workspace lifecycle

The coder_script resource runs scripts during workspace lifecycle events like startup, stop, or on a scheduled basis. It provides more control than the deprecated 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

resource "coder_script" "install_dependencies" {
  agent_id           = coder_agent.main.id
  display_name       = "Install Dependencies"
  icon               = "/icon/package.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 ensure 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 use coder_script internally. For example:

git-clone: Clones repositories on startup
dotfiles: Applies user dotfiles
code-server: Installs and configures code-server (VS Code in the browser)

You can also reference external script files:

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 for complete reference.

Agent Metadata

Display real-time metrics from the workspace agent, such as CPU, memory, and disk usage.

Build Parameters

Use build parameters to prompt users and customize each workspace when it is created.

Dynamic Parameters

Build conditional, identity-aware template forms with Coder's dynamic parameters.

Prebuilt workspaces

Pre-provision a ready-to-deploy workspace with a defined set of parameters

Icons

Customize your Coder templates and resources with built-in or custom icons.

Resource Metadata