coder · david-fraley · Sep 12, 2025 · Sep 9, 2025 · Sep 9, 2025 · Sep 9, 2025
diff --git a/docs/tutorials/quickstart.md b/docs/tutorials/quickstart.md
@@ -1,17 +1,51 @@
-# Quickstart
+# Get Started
 
-Follow the steps in this guide to install Coder locally or on a cloud-hosting
-provider, set up a workspace, and connect to it from VS Code.
+**Keywords:** install, setup, get started, quickstart, templates, workspaces,
+tasks, users
 
-By the end of this guide, you'll have a remote development environment that you
-can connect to from any device anywhere, so you can work on the same files in a
-persistent environment from your main device, a tablet, or your phone.
+Follow the steps in this guide to get your first Coder development environment
+running in under 10 minutes. This guide covers the essential concepts and walks
+you through creating your first workspace and running VS Code from it. You can
+also get Claude Code up and running in the background!
 
-## Install and start Coder
+## What You'll Build
+
+In this quickstart, you'll:
+
+- ✅ Install Coder server
+- ✅ Create a **template** (blueprint for dev environments)
+- ✅ Launch a **workspace** (your actual dev environment)
+- ✅ Connect from your favorite IDE
+- ✅ Optionally setup a **task** running Claude Code
+
+## Understanding Coder: 30-Second Overview
+
+Before diving in, here are the four concepts that power Coder explained through
+a cooking analogy:
+
+| Component      | What It Is                                                                           | Real-World Analogy                       |
+|----------------|--------------------------------------------------------------------------------------|------------------------------------------|
+| **You**        | The engineer/developer/builder working                                               | The head chef cooking the meal           |
+| **Templates**  | A Terraform blueprint that defines your dev environment (OS, tools, resources)       | Recipe for a meal                        |
+| **Workspaces** | The actual running environment created from the template                             | The cooked meal                          |
+| **Tasks**      | AI-powered coding agents that run inside a workspace                                 | Your sous chef helping you cook the meal |
+| **Users**      | A developer who launches the workspace from a template and does their work inside it | The people eating the meal               |
+
+**First time here?** Coder separates how an environment is defined (Admin’s job)
+from where you do your day-to-day coding (Developer’s job). As a developer,
+you’ll use templates to launch workspaces, and as an admin, you’ll create and
+manage those templates for others.
+
+## Prerequisites
+
+- A machine with 2+ CPU cores and 4GB+ RAM
+- 10 minutes of your time
+
+## Step 1: Install Docker and Setup Permissions
 
 <div class="tabs">
 
-## Linux/macOS
+### Linux/macOS
 
 1. Install Docker:
 
@@ -20,7 +54,6 @@ persistent environment from your main device, a tablet, or your phone.
    ```
 
    For more details, visit:
-
    - [Linux instructions](https://docs.docker.com/desktop/install/linux-install/)
    - [Mac instructions](https://docs.docker.com/desktop/install/mac-install/)
 
@@ -39,6 +72,25 @@ persistent environment from your main device, a tablet, or your phone.
    You might need to log out and back in or restart the machine for changes to
    take effect.
 
+### Windows
+
+If you plan to use the built-in PostgreSQL database, ensure that the
+[Visual C++ Runtime](https://learn.microsoft.com/en-US/cpp/windows/latest-supported-vc-redist#latest-microsoft-visual-c-redistributable-version)
+is installed.
+
+1. [Install Docker](https://docs.docker.com/desktop/install/windows-install/).
+
+</div>
+
+## Step 2: Install & Start Coder
+
+The `coder` CLI is all you need to install. It let's you run both the Coder
+server as well as the client.
+
+<div class="tabs">
+
+### Linux/macOS
+
 1. Install Coder:
 
    ```shell
@@ -55,14 +107,12 @@ persistent environment from your main device, a tablet, or your phone.
    coder server
    ```
 
-## Windows
+### Windows
 
 If you plan to use the built-in PostgreSQL database, ensure that the
 [Visual C++ Runtime](https://learn.microsoft.com/en-US/cpp/windows/latest-supported-vc-redist#latest-microsoft-visual-c-redistributable-version)
 is installed.
 
-1. [Install Docker](https://docs.docker.com/desktop/install/windows-install/).
-
 1. Use the
    [`winget`](https://learn.microsoft.com/en-us/windows/package-manager/winget/#use-winget)
    package manager to install Coder:
@@ -79,44 +129,61 @@ is installed.
 
 </div>
 
-## Configure Coder with a new Workspace
+Coder will attempt to open the setup page in your browser. If it doesn't open
+automatically, go to <http://localhost:3000>.
+
+- If you get a browser warning similar to `Secure Site Not Available`, you can
+  ignore the warning and continue to the setup page.
+
+If your Coder server is on a network or cloud device, or you are having trouble
+viewing the page, locate the web UI URL in Coder logs in your terminal. It looks
+like `https://<CUSTOM-STRING>.<TUNNEL>.try.coder.app`. It's one of the first
+lines of output, so you might have to scroll up to find it.
+
+## Step 3: Initial Setup
+
+1. **Create your admin account:**
+   - Username: `yourname` (lowercase, no spaces)
+   - Email: `[email protected]`
+   - Password: Choose a strong password
 
-1. Coder will attempt to open the setup page in your browser. If it doesn't open
-   automatically, go to <http://localhost:3000>.
+   You can also choose to **Continue with GitHub** instead of creating an admin
+   account. The first user that signs in is automatically granted admin
+   permissions.
 
-   - If you get a browser warning similar to `Secure Site Not Available`, you
-     can ignore the warning and continue to the setup page.
+   ![Welcome to Coder - Create admin user](../images/screenshots/welcome-create-admin-user.png)
 
-   If your Coder server is on a network or cloud device, or you are having
-   trouble viewing the page, locate the web UI URL in Coder logs in your
-   terminal. It looks like `https://<CUSTOM-STRING>.<TUNNEL>.try.coder.app`.
-   It's one of the first lines of output, so you might have to scroll up to find
-   it.
+## Step 4: Create your First Template and Workspace
 
-1. On the **Welcome to Coder** page, to use your GitHub account to log in,
-   select **Continue with GitHub**.
-   You can also enter an email and password to create a new admin account on
-   the Coder deployment:
+Templates define what's in your development environment. Let's start simple:
 
-   ![Welcome to Coder - Create admin user](../images/screenshots/welcome-create-admin-user.png)_Welcome
-   to Coder - Create admin user_
+1. Click **"Templates"** → **"New Template"**
 
-1. On the **Workspaces** page, select **Go to templates** to create a new
-   template.
+2. **Choose a starter template:**
 
-1. For this guide, use a Docker container. Locate **Docker Containers** and
-   select **Use template**.
+   | Starter                             | Best For                                                | Includes                                               |
+   |-------------------------------------|---------------------------------------------------------|--------------------------------------------------------|
+   | **Docker Containers** (Recommended) | Getting started quickly, local development, prototyping | Ubuntu container with common dev tools, Docker runtime |
+   | **Kubernetes (Deployment)**         | Cloud-native teams, scalable workspaces                 | Pod-based workspaces, Kubernetes orchestration         |
+   | **AWS EC2 (Linux)**                 | Teams needing full VMs, AWS-native infrastructure       | Full EC2 instances with AWS integration                |
 
-1. Give the template a **Name** that you'll recognize both in the Coder UI and
-   in command-line calls.
+3. Click **"Use template"** on **Docker Containers**
 
-   The rest of the template details are optional, but will be helpful when you
-   have more templates.
+4. **Name your template:**
+   - Name: `quickstart`
+   - Display name: `quickstart doc template`
+   - Description: `Provision Docker containers as Coder workspaces`
 
-   ![Create template](../images/screenshots/create-template.png)_Create
-   template_
+![Create template](../images/screenshots/create-template.png)
 
-1. Select **Save**.
+1. Click **"Save"**
+
+**What just happened?** You defined a template — a reusable blueprint for dev
+environments — in your Coder deployment. It's now stored in your organization's
+template list, where you and any teammates in the same org can create workspaces
+from it. Let's launch one.
+
+## Step 5: Launch your Workspace
 
 1. After the template is ready, select **Create Workspace**.
 
@@ -127,10 +194,10 @@ is installed.
    ![getting-started-workspace is running](../images/screenshots/workspace-running-with-topbar.png)_Workspace
    is running_
 
-1. Select **VS Code Desktop** to install the Coder extension and connect to your
-   Coder workspace.
+## Step 6: Connect your IDE
 
-## Work on some code
+Select **VS Code Desktop** to install the Coder extension and connect to your
+Coder workspace.
 
 After VS Code loads the remote environment, you can select **Open Folder** to
 explore directories in the Docker container or work on something new.
@@ -154,19 +221,90 @@ To clone an existing repository:
 
 1. You are now using VS Code in your Coder environment!
 
-## What's next?
+## Success! You're Coding in Coder
+
+You now have:
+
+- **Coder server** running locally
+- **A template** defining your environment
+- **A workspace** running that environment
+- **IDE access** to code remotely
+
+### What's Next?
+
+Now that you have your own workspace running, you can start exploring more
+advanced capabilities that Coder offers.
 
-Now that you have your own workspace, use the same template to set one up for a
-teammate.
+- [Learn more about running Coder Tasks and our recommended Best Practices](https://coder.com/docs/ai-coder/best-practices)
 
-Go to **Templates** and select **Create Workspace** and continue from Step 7 in
-[Configure Coder with a new workspace](#configure-coder-with-a-new-workspace).
+- [Read about managing Workspaces for your team](https://coder.com/docs/user-guides/workspace-management)
 
-After that, you can try to:
+- [Read about implementing monitoring tools for your Coder Deployment](https://coder.com/docs/admin/monitoring)
+
+### Get Coder Tasks Running
+
+Coder Tasks is an interface that allows you to run and manage coding agents like
+Claude Code. Tasks become available when a template has the `coder_ai_task`
+resource and `coder_parameter` named `AI Prompt` defined in its source code.
+Subsequently, any existing template can become a Task template by adding in that
+resource and parameter.
+
+Let's try turning the **Docker Containers** template into a Task template
+running Claude Code:
+
+1. Head to **Templates**
+1. Click into the template, and then click **Source Code** -> **Edit**
+1. Add the following code snippit to the bottom of the terraform. This defines
+   the `coder_ai_task` resource and `coder_parameter`
+
+```hcl
+# Claude API Key variable (filled in during template build)
+variable "claude_api_key" {
+  type        = string
+  description = "Your Anthropic API key for Claude AI"
+  sensitive   = true
+}
+
+# AI Prompt parameter
+data "coder_parameter" "ai_prompt" {
+  name         = "AI Prompt"
+  display_name = "AI Prompt"
+  description  = "Optional AI prompt to customize behavior"
+  type         = "string"
+  default      = ""
+}
+
+# Claude app
+resource "coder_app" "claude-code" {
+  agent_id     = coder_agent.main.id
+  slug         = "claude"
+  display_name = "Claude"
+  url          = "https://claude.ai"
+  icon         = "https://claude.ai/favicon.ico"
+  external     = true
+}
+
+# Claude AI task
+resource "coder_ai_task" "claude-code" {
+  count = data.coder_parameter.ai_prompt.value != "" ? 1 : 0
+
+  sidebar_app {
+    id = coder_app.claude-code.id
+  }
+}
+
+```
 
-- [Customize templates](../admin/templates/extending-templates/index.md)
-- [Enable Prometheus metrics](../admin/integrations/prometheus.md)
-- [Deploy to Google Cloud Platform (GCP)](../install/cloud/compute-engine.md)
+1. **Build the Template**: Click "Build version". This will process your
+   template updates. After it finishes building successfully:
+1. **Activate the Template**: Click "Promote Version" on the new version to make
+   it the active template version.
+1. **Create a Task**: Click "Create Task".
+1. Once your workspace is running, navigate to the **Tasks** tab in the upper
+   left hand corner. Type in a message or coding request like "Help me write a
+   HelloWorld application in Python". Click **Run Task** to start the task
+1. The task will open VS Code with Claude Code running in the left sidebar. You
+   are now successfully using Coder Tasks with Claude Code!
 
 ## Troubleshooting