fix: remove a sensitive field from an agent log line (#20968) (#20970)

Backport of #20968

Co-authored-by: Sas Swart <sas.swart.cdk@gmail.com>

.claude/docs/DATABASE.md

@@ -0,0 +1,218 @@
+# Database Development Patterns
+
+## Database Work Overview
+
+### Database Generation Process
+
+1. Modify SQL files in `coderd/database/queries/`
+2. Run `make gen`
+3. If errors about audit table, update `enterprise/audit/table.go`
+4. Run `make gen` again
+5. Run `make lint` to catch any remaining issues
+
+## Migration Guidelines
+
+### Creating Migration Files
+
+**Location**: `coderd/database/migrations/`
+**Format**: `{number}_{description}.{up|down}.sql`
+
+- Number must be unique and sequential
+- Always include both up and down migrations
+
+### Helper Scripts
+
+| Script                                                              | Purpose                                 |
+|---------------------------------------------------------------------|-----------------------------------------|
+| `./coderd/database/migrations/create_migration.sh "migration name"` | Creates new migration files             |
+| `./coderd/database/migrations/fix_migration_numbers.sh`             | Renumbers migrations to avoid conflicts |
+| `./coderd/database/migrations/create_fixture.sh "fixture name"`     | Creates test fixtures for migrations    |
+
+### Database Query Organization
+
+- **MUST DO**: Any changes to database - adding queries, modifying queries should be done in the `coderd/database/queries/*.sql` files
+- **MUST DO**: Queries are grouped in files relating to context - e.g. `prebuilds.sql`, `users.sql`, `oauth2.sql`
+- After making changes to any `coderd/database/queries/*.sql` files you must run `make gen` to generate respective ORM changes
+
+## Handling Nullable Fields
+
+Use `sql.NullString`, `sql.NullBool`, etc. for optional database fields:
+
+```go
+CodeChallenge: sql.NullString{
+    String: params.codeChallenge,
+    Valid:  params.codeChallenge != "",
+}
+```
+
+Set `.Valid = true` when providing values.
+
+## Audit Table Updates
+
+If adding fields to auditable types:
+
+1. Update `enterprise/audit/table.go`
+2. Add each new field with appropriate action:
+   - `ActionTrack`: Field should be tracked in audit logs
+   - `ActionIgnore`: Field should be ignored in audit logs
+   - `ActionSecret`: Field contains sensitive data
+3. Run `make gen` to verify no audit errors
+
+## Database Architecture
+
+### Core Components
+
+- **PostgreSQL 13+** recommended for production
+- **Migrations** managed with `migrate`
+- **Database authorization** through `dbauthz` package
+
+### Authorization Patterns
+
+```go
+// Public endpoints needing system access (OAuth2 registration)
+app, err := api.Database.GetOAuth2ProviderAppByClientID(dbauthz.AsSystemRestricted(ctx), clientID)
+
+// Authenticated endpoints with user context
+app, err := api.Database.GetOAuth2ProviderAppByClientID(ctx, clientID)
+
+// System operations in middleware
+roles, err := db.GetAuthorizationUserRoles(dbauthz.AsSystemRestricted(ctx), userID)
+```
+
+## Common Database Issues
+
+### Migration Issues
+
+1. **Migration conflicts**: Use `fix_migration_numbers.sh` to renumber
+2. **Missing down migration**: Always create both up and down files
+3. **Schema inconsistencies**: Verify against existing schema
+
+### Field Handling Issues
+
+1. **Nullable field errors**: Use `sql.Null*` types consistently
+2. **Missing audit entries**: Update `enterprise/audit/table.go`
+
+### Query Issues
+
+1. **Query organization**: Group related queries in appropriate files
+2. **Generated code errors**: Run `make gen` after query changes
+3. **Performance issues**: Add appropriate indexes in migrations
+
+## Database Testing
+
+### Test Database Setup
+
+```go
+func TestDatabaseFunction(t *testing.T) {
+    db := dbtestutil.NewDB(t)
+
+    // Test with real database
+    result, err := db.GetSomething(ctx, param)
+    require.NoError(t, err)
+    require.Equal(t, expected, result)
+}
+```
+
+## Best Practices
+
+### Schema Design
+
+1. **Use appropriate data types**: VARCHAR for strings, TIMESTAMP for times
+2. **Add constraints**: NOT NULL, UNIQUE, FOREIGN KEY as appropriate
+3. **Create indexes**: For frequently queried columns
+4. **Consider performance**: Normalize appropriately but avoid over-normalization
+
+### Query Writing
+
+1. **Use parameterized queries**: Prevent SQL injection
+2. **Handle errors appropriately**: Check for specific error types
+3. **Use transactions**: For related operations that must succeed together
+4. **Optimize queries**: Use EXPLAIN to understand query performance
+
+### Migration Writing
+
+1. **Make migrations reversible**: Always include down migration
+2. **Test migrations**: On copy of production data if possible
+3. **Keep migrations small**: One logical change per migration
+4. **Document complex changes**: Add comments explaining rationale
+
+## Advanced Patterns
+
+### Complex Queries
+
+```sql
+-- Example: Complex join with aggregation
+SELECT
+    u.id,
+    u.username,
+    COUNT(w.id) as workspace_count
+FROM users u
+LEFT JOIN workspaces w ON u.id = w.owner_id
+WHERE u.created_at > $1
+GROUP BY u.id, u.username
+ORDER BY workspace_count DESC;
+```
+
+### Conditional Queries
+
+```sql
+-- Example: Dynamic filtering
+SELECT * FROM oauth2_provider_apps
+WHERE
+    ($1::text IS NULL OR name ILIKE '%' || $1 || '%')
+    AND ($2::uuid IS NULL OR organization_id = $2)
+ORDER BY created_at DESC;
+```
+
+### Audit Patterns
+
+```go
+// Example: Auditable database operation
+func (q *sqlQuerier) UpdateUser(ctx context.Context, arg UpdateUserParams) (User, error) {
+    // Implementation here
+
+    // Audit the change
+    if auditor := audit.FromContext(ctx); auditor != nil {
+        auditor.Record(audit.UserUpdate{
+            UserID: arg.ID,
+            Old:    oldUser,
+            New:    newUser,
+        })
+    }
+
+    return newUser, nil
+}
+```
+
+## Debugging Database Issues
+
+### Common Debug Commands
+
+```bash
+# Check database connection
+make test-postgres
+
+# Run specific database tests
+go test ./coderd/database/... -run TestSpecificFunction
+
+# Check query generation
+make gen
+
+# Verify audit table
+make lint
+```
+
+### Debug Techniques
+
+1. **Enable query logging**: Set appropriate log levels
+2. **Use database tools**: pgAdmin, psql for direct inspection
+3. **Check constraints**: UNIQUE, FOREIGN KEY violations
+4. **Analyze performance**: Use EXPLAIN ANALYZE for slow queries
+
+### Troubleshooting Checklist
+
+- [ ] Migration files exist (both up and down)
+- [ ] `make gen` run after query changes
+- [ ] Audit table updated for new fields
+- [ ] Nullable fields use `sql.Null*` types
+- [ ] Authorization context appropriate for endpoint type

.claude/docs/OAUTH2.md

@@ -0,0 +1,157 @@
+# OAuth2 Development Guide
+
+## RFC Compliance Development
+
+### Implementing Standard Protocols
+
+When implementing standard protocols (OAuth2, OpenID Connect, etc.):
+
+1. **Fetch and Analyze Official RFCs**:
+   - Always read the actual RFC specifications before implementation
+   - Use WebFetch tool to get current RFC content for compliance verification
+   - Document RFC requirements in code comments
+
+2. **Default Values Matter**:
+   - Pay close attention to RFC-specified default values
+   - Example: RFC 7591 specifies `client_secret_basic` as default, not `client_secret_post`
+   - Ensure consistency between database migrations and application code
+
+3. **Security Requirements**:
+   - Follow RFC security considerations precisely
+   - Example: RFC 7592 prohibits returning registration access tokens in GET responses
+   - Implement proper error responses per protocol specifications
+
+4. **Validation Compliance**:
+   - Implement comprehensive validation per RFC requirements
+   - Support protocol-specific features (e.g., custom schemes for native OAuth2 apps)
+   - Test edge cases defined in specifications
+
+## OAuth2 Provider Implementation
+
+### OAuth2 Spec Compliance
+
+1. **Follow RFC 6749 for token responses**
+   - Use `expires_in` (seconds) not `expiry` (timestamp) in token responses
+   - Return proper OAuth2 error format: `{"error": "code", "error_description": "details"}`
+
+2. **Error Response Format**
+   - Create OAuth2-compliant error responses for token endpoint
+   - Use standard error codes: `invalid_client`, `invalid_grant`, `invalid_request`
+   - Avoid generic error responses for OAuth2 endpoints
+
+### PKCE Implementation
+
+- Support both with and without PKCE for backward compatibility
+- Use S256 method for code challenge
+- Properly validate code_verifier against stored code_challenge
+
+### UI Authorization Flow
+
+- Use POST requests for consent, not GET with links
+- Avoid dependency on referer headers for security decisions
+- Support proper state parameter validation
+
+### RFC 8707 Resource Indicators
+
+- Store resource parameters in database for server-side validation (opaque tokens)
+- Validate resource consistency between authorization and token requests
+- Support audience validation in refresh token flows
+- Resource parameter is optional but must be consistent when provided
+
+## OAuth2 Error Handling Pattern
+
+```go
+// Define specific OAuth2 errors
+var (
+    errInvalidPKCE = xerrors.New("invalid code_verifier")
+)
+
+// Use OAuth2-compliant error responses
+type OAuth2Error struct {
+    Error            string `json:"error"`
+    ErrorDescription string `json:"error_description,omitempty"`
+}
+
+// Return proper OAuth2 errors
+if errors.Is(err, errInvalidPKCE) {
+    writeOAuth2Error(ctx, rw, http.StatusBadRequest, "invalid_grant", "The PKCE code verifier is invalid")
+    return
+}
+```
+
+## Testing OAuth2 Features
+
+### Test Scripts
+
+Located in `./scripts/oauth2/`:
+
+- `test-mcp-oauth2.sh` - Full automated test suite
+- `setup-test-app.sh` - Create test OAuth2 app
+- `cleanup-test-app.sh` - Remove test app
+- `generate-pkce.sh` - Generate PKCE parameters
+- `test-manual-flow.sh` - Manual browser testing
+
+Always run the full test suite after OAuth2 changes:
+
+```bash
+./scripts/oauth2/test-mcp-oauth2.sh
+```
+
+### RFC Protocol Testing
+
+1. **Compliance Test Coverage**:
+   - Test all RFC-defined error codes and responses
+   - Validate proper HTTP status codes for different scenarios
+   - Test protocol-specific edge cases (URI formats, token formats, etc.)
+
+2. **Security Boundary Testing**:
+   - Test client isolation and privilege separation
+   - Verify information disclosure protections
+   - Test token security and proper invalidation
+
+## Common OAuth2 Issues
+
+1. **OAuth2 endpoints returning wrong error format** - Ensure OAuth2 endpoints return RFC 6749 compliant errors
+2. **Resource indicator validation failing** - Ensure database stores and retrieves resource parameters correctly
+3. **PKCE tests failing** - Verify both authorization code storage and token exchange handle PKCE fields
+4. **RFC compliance failures** - Verify against actual RFC specifications, not assumptions
+5. **Authorization context errors in public endpoints** - Use `dbauthz.AsSystemRestricted(ctx)` pattern
+6. **Default value mismatches** - Ensure database migrations match application code defaults
+7. **Bearer token authentication issues** - Check token extraction precedence and format validation
+8. **URI validation failures** - Support both standard schemes and custom schemes per protocol requirements
+
+## Authorization Context Patterns
+
+```go
+// Public endpoints needing system access (OAuth2 registration)
+app, err := api.Database.GetOAuth2ProviderAppByClientID(dbauthz.AsSystemRestricted(ctx), clientID)
+
+// Authenticated endpoints with user context
+app, err := api.Database.GetOAuth2ProviderAppByClientID(ctx, clientID)
+
+// System operations in middleware
+roles, err := db.GetAuthorizationUserRoles(dbauthz.AsSystemRestricted(ctx), userID)
+```
+
+## OAuth2/Authentication Work Patterns
+
+- Types go in `codersdk/oauth2.go` or similar
+- Handlers go in `coderd/oauth2.go` or `coderd/identityprovider/`
+- Database fields need migration + audit table updates
+- Always support backward compatibility
+
+## Protocol Implementation Checklist
+
+Before completing OAuth2 or authentication feature work:
+
+- [ ] Verify RFC compliance by reading actual specifications
+- [ ] Implement proper error response formats per protocol
+- [ ] Add comprehensive validation for all protocol fields
+- [ ] Test security boundaries and token handling
+- [ ] Update RBAC permissions for new resources
+- [ ] Add audit logging support if applicable
+- [ ] Create database migrations with proper defaults
+- [ ] Add comprehensive test coverage including edge cases
+- [ ] Verify linting compliance
+- [ ] Test both positive and negative scenarios
+- [ ] Document protocol-specific patterns and requirements

.claude/docs/TESTING.md

@@ -0,0 +1,212 @@
+# Testing Patterns and Best Practices
+
+## Testing Best Practices
+
+### Avoiding Race Conditions
+
+1. **Unique Test Identifiers**:
+   - Never use hardcoded names in concurrent tests
+   - Use `time.Now().UnixNano()` or similar for unique identifiers
+   - Example: `fmt.Sprintf("test-client-%s-%d", t.Name(), time.Now().UnixNano())`
+
+2. **Database Constraint Awareness**:
+   - Understand unique constraints that can cause test conflicts
+   - Generate unique values for all constrained fields
+   - Test name isolation prevents cross-test interference
+
+### Testing Patterns
+
+- Use table-driven tests for comprehensive coverage
+- Mock external dependencies
+- Test both positive and negative cases
+- Use `testutil.WaitLong` for timeouts in tests
+
+### Test Package Naming
+
+- **Test packages**: Use `package_test` naming (e.g., `identityprovider_test`) for black-box testing
+
+## RFC Protocol Testing
+
+### Compliance Test Coverage
+
+1. **Test all RFC-defined error codes and responses**
+2. **Validate proper HTTP status codes for different scenarios**
+3. **Test protocol-specific edge cases** (URI formats, token formats, etc.)
+
+### Security Boundary Testing
+
+1. **Test client isolation and privilege separation**
+2. **Verify information disclosure protections**
+3. **Test token security and proper invalidation**
+
+## Test Organization
+
+### Test File Structure
+
+```
+coderd/
+├── oauth2.go                    # Implementation
+├── oauth2_test.go              # Main tests
+├── oauth2_test_helpers.go      # Test utilities
+└── oauth2_validation.go        # Validation logic
+```
+
+### Test Categories
+
+1. **Unit Tests**: Test individual functions in isolation
+2. **Integration Tests**: Test API endpoints with database
+3. **End-to-End Tests**: Full workflow testing
+4. **Race Tests**: Concurrent access testing
+
+## Test Commands
+
+### Running Tests
+
+| Command | Purpose |
+|---------|---------|
+| `make test` | Run all Go tests |
+| `make test RUN=TestFunctionName` | Run specific test |
+| `go test -v ./path/to/package -run TestFunctionName` | Run test with verbose output |
+| `make test-postgres` | Run tests with Postgres database |
+| `make test-race` | Run tests with Go race detector |
+| `make test-e2e` | Run end-to-end tests |
+
+### Frontend Testing
+
+| Command | Purpose |
+|---------|---------|
+| `pnpm test` | Run frontend tests |
+| `pnpm check` | Run code checks |
+
+## Common Testing Issues
+
+### Database-Related
+
+1. **SQL type errors** - Use `sql.Null*` types for nullable fields
+2. **Race conditions in tests** - Use unique identifiers instead of hardcoded names
+
+### OAuth2 Testing
+
+1. **PKCE tests failing** - Verify both authorization code storage and token exchange handle PKCE fields
+2. **Resource indicator validation failing** - Ensure database stores and retrieves resource parameters correctly
+
+### General Issues
+
+1. **Missing newlines** - Ensure files end with newline character
+2. **Package naming errors** - Use `package_test` naming for test files
+3. **Log message formatting errors** - Use lowercase, descriptive messages without special characters
+
+## Systematic Testing Approach
+
+### Multi-Issue Problem Solving
+
+When facing multiple failing tests or complex integration issues:
+
+1. **Identify Root Causes**:
+   - Run failing tests individually to isolate issues
+   - Use LSP tools to trace through call chains
+   - Check both compilation and runtime errors
+
+2. **Fix in Logical Order**:
+   - Address compilation issues first (imports, syntax)
+   - Fix authorization and RBAC issues next
+   - Resolve business logic and validation issues
+   - Handle edge cases and race conditions last
+
+3. **Verification Strategy**:
+   - Test each fix individually before moving to next issue
+   - Use `make lint` and `make gen` after database changes
+   - Verify RFC compliance with actual specifications
+   - Run comprehensive test suites before considering complete
+
+## Test Data Management
+
+### Unique Test Data
+
+```go
+// Good: Unique identifiers prevent conflicts
+clientName := fmt.Sprintf("test-client-%s-%d", t.Name(), time.Now().UnixNano())
+
+// Bad: Hardcoded names cause race conditions
+clientName := "test-client"
+```
+
+### Test Cleanup
+
+```go
+func TestSomething(t *testing.T) {
+    // Setup
+    client := coderdtest.New(t, nil)
+
+    // Test code here
+
+    // Cleanup happens automatically via t.Cleanup() in coderdtest
+}
+```
+
+## Test Utilities
+
+### Common Test Patterns
+
+```go
+// Table-driven tests
+tests := []struct {
+    name     string
+    input    InputType
+    expected OutputType
+    wantErr  bool
+}{
+    {
+        name:     "valid input",
+        input:    validInput,
+        expected: expectedOutput,
+        wantErr:  false,
+    },
+    // ... more test cases
+}
+
+for _, tt := range tests {
+    t.Run(tt.name, func(t *testing.T) {
+        result, err := functionUnderTest(tt.input)
+        if tt.wantErr {
+            require.Error(t, err)
+            return
+        }
+        require.NoError(t, err)
+        require.Equal(t, tt.expected, result)
+    })
+}
+```
+
+### Test Assertions
+
+```go
+// Use testify/require for assertions
+require.NoError(t, err)
+require.Equal(t, expected, actual)
+require.NotNil(t, result)
+require.True(t, condition)
+```
+
+## Performance Testing
+
+### Load Testing
+
+- Use `scaletest/` directory for load testing scenarios
+- Run `./scaletest/scaletest.sh` for performance testing
+
+### Benchmarking
+
+```go
+func BenchmarkFunction(b *testing.B) {
+    for i := 0; i < b.N; i++ {
+        // Function call to benchmark
+        _ = functionUnderTest(input)
+    }
+}
+```
+
+Run benchmarks with:
+```bash
+go test -bench=. -benchmem ./package/path
+```

.claude/docs/TROUBLESHOOTING.md

@@ -0,0 +1,231 @@
+# Troubleshooting Guide
+
+## Common Issues
+
+### Database Issues
+
+1. **"Audit table entry missing action"**
+   - **Solution**: Update `enterprise/audit/table.go`
+   - Add each new field with appropriate action (ActionTrack, ActionIgnore, ActionSecret)
+   - Run `make gen` to verify no audit errors
+
+2. **SQL type errors**
+   - **Solution**: Use `sql.Null*` types for nullable fields
+   - Set `.Valid = true` when providing values
+   - Example:
+
+     ```go
+     CodeChallenge: sql.NullString{
+         String: params.codeChallenge,
+         Valid:  params.codeChallenge != "",
+     }
+     ```
+
+### Testing Issues
+
+3. **"package should be X_test"**
+   - **Solution**: Use `package_test` naming for test files
+   - Example: `identityprovider_test` for black-box testing
+
+4. **Race conditions in tests**
+   - **Solution**: Use unique identifiers instead of hardcoded names
+   - Example: `fmt.Sprintf("test-client-%s-%d", t.Name(), time.Now().UnixNano())`
+   - Never use hardcoded names in concurrent tests
+
+5. **Missing newlines**
+   - **Solution**: Ensure files end with newline character
+   - Most editors can be configured to add this automatically
+
+### OAuth2 Issues
+
+6. **OAuth2 endpoints returning wrong error format**
+   - **Solution**: Ensure OAuth2 endpoints return RFC 6749 compliant errors
+   - Use standard error codes: `invalid_client`, `invalid_grant`, `invalid_request`
+   - Format: `{"error": "code", "error_description": "details"}`
+
+7. **Resource indicator validation failing**
+   - **Solution**: Ensure database stores and retrieves resource parameters correctly
+   - Check both authorization code storage and token exchange handling
+
+8. **PKCE tests failing**
+    - **Solution**: Verify both authorization code storage and token exchange handle PKCE fields
+    - Check `CodeChallenge` and `CodeChallengeMethod` field handling
+
+### RFC Compliance Issues
+
+9. **RFC compliance failures**
+    - **Solution**: Verify against actual RFC specifications, not assumptions
+    - Use WebFetch tool to get current RFC content for compliance verification
+    - Read the actual RFC specifications before implementation
+
+10. **Default value mismatches**
+    - **Solution**: Ensure database migrations match application code defaults
+    - Example: RFC 7591 specifies `client_secret_basic` as default, not `client_secret_post`
+
+### Authorization Issues
+
+11. **Authorization context errors in public endpoints**
+    - **Solution**: Use `dbauthz.AsSystemRestricted(ctx)` pattern
+    - Example:
+
+      ```go
+      // Public endpoints needing system access
+      app, err := api.Database.GetOAuth2ProviderAppByClientID(dbauthz.AsSystemRestricted(ctx), clientID)
+      ```
+
+### Authentication Issues
+
+12. **Bearer token authentication issues**
+    - **Solution**: Check token extraction precedence and format validation
+    - Ensure proper RFC 6750 Bearer Token Support implementation
+
+13. **URI validation failures**
+    - **Solution**: Support both standard schemes and custom schemes per protocol requirements
+    - Native OAuth2 apps may use custom schemes
+
+### General Development Issues
+
+14. **Log message formatting errors**
+    - **Solution**: Use lowercase, descriptive messages without special characters
+    - Follow Go logging conventions
+
+## Systematic Debugging Approach
+
+### Multi-Issue Problem Solving
+
+When facing multiple failing tests or complex integration issues:
+
+1. **Identify Root Causes**:
+   - Run failing tests individually to isolate issues
+   - Use LSP tools to trace through call chains
+   - Check both compilation and runtime errors
+
+2. **Fix in Logical Order**:
+   - Address compilation issues first (imports, syntax)
+   - Fix authorization and RBAC issues next
+   - Resolve business logic and validation issues
+   - Handle edge cases and race conditions last
+
+3. **Verification Strategy**:
+   - Test each fix individually before moving to next issue
+   - Use `make lint` and `make gen` after database changes
+   - Verify RFC compliance with actual specifications
+   - Run comprehensive test suites before considering complete
+
+## Debug Commands
+
+### Useful Debug Commands
+
+| Command                                      | Purpose                               |
+|----------------------------------------------|---------------------------------------|
+| `make lint`                                  | Run all linters                       |
+| `make gen`                                   | Generate mocks, database queries      |
+| `go test -v ./path/to/package -run TestName` | Run specific test with verbose output |
+| `go test -race ./...`                        | Run tests with race detector          |
+
+### LSP Debugging
+
+#### Go LSP (Backend)
+
+| Command                                            | Purpose                      |
+|----------------------------------------------------|------------------------------|
+| `mcp__go-language-server__definition symbolName`   | Find function definition     |
+| `mcp__go-language-server__references symbolName`   | Find all references          |
+| `mcp__go-language-server__diagnostics filePath`    | Check for compilation errors |
+| `mcp__go-language-server__hover filePath line col` | Get type information         |
+
+#### TypeScript LSP (Frontend)
+
+| Command                                                                    | Purpose                            |
+|----------------------------------------------------------------------------|------------------------------------|
+| `mcp__typescript-language-server__definition symbolName`                   | Find component/function definition |
+| `mcp__typescript-language-server__references symbolName`                   | Find all component/type usages     |
+| `mcp__typescript-language-server__diagnostics filePath`                    | Check for TypeScript errors        |
+| `mcp__typescript-language-server__hover filePath line col`                 | Get type information               |
+| `mcp__typescript-language-server__rename_symbol filePath line col newName` | Rename across codebase             |
+
+## Common Error Messages
+
+### Database Errors
+
+**Error**: `pq: relation "oauth2_provider_app_codes" does not exist`
+
+- **Cause**: Missing database migration
+- **Solution**: Run database migrations, check migration files
+
+**Error**: `audit table entry missing action for field X`
+
+- **Cause**: New field added without audit table update
+- **Solution**: Update `enterprise/audit/table.go`
+
+### Go Compilation Errors
+
+**Error**: `package should be identityprovider_test`
+
+- **Cause**: Test package naming convention violation
+- **Solution**: Use `package_test` naming for black-box tests
+
+**Error**: `cannot use X (type Y) as type Z`
+
+- **Cause**: Type mismatch, often with nullable fields
+- **Solution**: Use appropriate `sql.Null*` types
+
+### OAuth2 Errors
+
+**Error**: `invalid_client` but client exists
+
+- **Cause**: Authorization context issue
+- **Solution**: Use `dbauthz.AsSystemRestricted(ctx)` for public endpoints
+
+**Error**: PKCE validation failing
+
+- **Cause**: Missing PKCE fields in database operations
+- **Solution**: Ensure `CodeChallenge` and `CodeChallengeMethod` are handled
+
+## Prevention Strategies
+
+### Before Making Changes
+
+1. **Read the relevant documentation**
+2. **Check if similar patterns exist in codebase**
+3. **Understand the authorization context requirements**
+4. **Plan database changes carefully**
+
+### During Development
+
+1. **Run tests frequently**: `make test`
+2. **Use LSP tools for navigation**: Avoid manual searching
+3. **Follow RFC specifications precisely**
+4. **Update audit tables when adding database fields**
+
+### Before Committing
+
+1. **Run full test suite**: `make test`
+2. **Check linting**: `make lint`
+3. **Test with race detector**: `make test-race`
+
+## Getting Help
+
+### Internal Resources
+
+- Check existing similar implementations in codebase
+- Use LSP tools to understand code relationships
+  - For Go code: Use `mcp__go-language-server__*` commands
+  - For TypeScript/React code: Use `mcp__typescript-language-server__*` commands
+- Read related test files for expected behavior
+
+### External Resources
+
+- Official RFC specifications for protocol compliance
+- Go documentation for language features
+- PostgreSQL documentation for database issues
+
+### Debug Information Collection
+
+When reporting issues, include:
+
+1. **Exact error message**
+2. **Steps to reproduce**
+3. **Relevant code snippets**
+4. **Test output (if applicable)**
+5. **Environment information** (OS, Go version, etc.)

.claude/docs/WORKFLOWS.md

@@ -0,0 +1,223 @@
+# Development Workflows and Guidelines
+
+## Quick Start Checklist for New Features
+
+### Before Starting
+
+- [ ] Run `git pull` to ensure you're on latest code
+- [ ] Check if feature touches database - you'll need migrations
+- [ ] Check if feature touches audit logs - update `enterprise/audit/table.go`
+
+## Development Server
+
+### Starting Development Mode
+
+- **Use `./scripts/develop.sh` to start Coder in development mode**
+- This automatically builds and runs with `--dev` flag and proper access URL
+- **⚠️ Do NOT manually run `make build && ./coder server --dev` - use the script instead**
+
+### Development Workflow
+
+1. **Always start with the development script**: `./scripts/develop.sh`
+2. **Make changes** to your code
+3. **The script will automatically rebuild** and restart as needed
+4. **Access the development server** at the URL provided by the script
+
+## Code Style Guidelines
+
+### Go Style
+
+- Follow [Effective Go](https://go.dev/doc/effective_go) and [Go's Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments)
+- Create packages when used during implementation
+- Validate abstractions against implementations
+- **Test packages**: Use `package_test` naming (e.g., `identityprovider_test`) for black-box testing
+
+### Error Handling
+
+- Use descriptive error messages
+- Wrap errors with context
+- Propagate errors appropriately
+- Use proper error types
+- Pattern: `xerrors.Errorf("failed to X: %w", err)`
+
+### Naming Conventions
+
+- Use clear, descriptive names
+- Abbreviate only when obvious
+- Follow Go and TypeScript naming conventions
+
+### Comments
+
+- Document exported functions, types, and non-obvious logic
+- Follow JSDoc format for TypeScript
+- Use godoc format for Go code
+
+## Database Migration Workflows
+
+### Migration Guidelines
+
+1. **Create migration files**:
+   - Location: `coderd/database/migrations/`
+   - Format: `{number}_{description}.{up|down}.sql`
+   - Number must be unique and sequential
+   - Always include both up and down migrations
+
+2. **Use helper scripts**:
+   - `./coderd/database/migrations/create_migration.sh "migration name"` - Creates new migration files
+   - `./coderd/database/migrations/fix_migration_numbers.sh` - Renumbers migrations to avoid conflicts
+   - `./coderd/database/migrations/create_fixture.sh "fixture name"` - Creates test fixtures for migrations
+
+3. **Update database queries**:
+   - **MUST DO**: Any changes to database - adding queries, modifying queries should be done in the `coderd/database/queries/*.sql` files
+   - **MUST DO**: Queries are grouped in files relating to context - e.g. `prebuilds.sql`, `users.sql`, `oauth2.sql`
+   - After making changes to any `coderd/database/queries/*.sql` files you must run `make gen` to generate respective ORM changes
+
+4. **Handle nullable fields**:
+   - Use `sql.NullString`, `sql.NullBool`, etc. for optional database fields
+   - Set `.Valid = true` when providing values
+
+5. **Audit table updates**:
+   - If adding fields to auditable types, update `enterprise/audit/table.go`
+   - Add each new field with appropriate action (ActionTrack, ActionIgnore, ActionSecret)
+   - Run `make gen` to verify no audit errors
+
+### Database Generation Process
+
+1. Modify SQL files in `coderd/database/queries/`
+2. Run `make gen`
+3. If errors about audit table, update `enterprise/audit/table.go`
+4. Run `make gen` again
+5. Run `make lint` to catch any remaining issues
+
+## API Development Workflow
+
+### Adding New API Endpoints
+
+1. **Define types** in `codersdk/` package
+2. **Add handler** in appropriate `coderd/` file
+3. **Register route** in `coderd/coderd.go`
+4. **Add tests** in `coderd/*_test.go` files
+5. **Update OpenAPI** by running `make gen`
+
+## Testing Workflows
+
+### Test Execution
+
+- Run full test suite: `make test`
+- Run specific test: `make test RUN=TestFunctionName`
+- Run with Postgres: `make test-postgres`
+- Run with race detector: `make test-race`
+- Run end-to-end tests: `make test-e2e`
+
+### Test Development
+
+- Use table-driven tests for comprehensive coverage
+- Mock external dependencies
+- Test both positive and negative cases
+- Use `testutil.WaitLong` for timeouts in tests
+- Always use `t.Parallel()` in tests
+
+## Commit Style
+
+- Follow [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)
+- Format: `type(scope): message`
+- Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
+- Keep message titles concise (~70 characters)
+- Use imperative, present tense in commit titles
+
+## Code Navigation and Investigation
+
+### Using LSP Tools (STRONGLY RECOMMENDED)
+
+**IMPORTANT**: Always use LSP tools for code navigation and understanding. These tools provide accurate, real-time analysis of the codebase and should be your first choice for code investigation.
+
+#### Go LSP Tools (for backend code)
+
+1. **Find function definitions** (USE THIS FREQUENTLY):
+   - `mcp__go-language-server__definition symbolName`
+   - Example: `mcp__go-language-server__definition getOAuth2ProviderAppAuthorize`
+   - Quickly jump to function implementations across packages
+
+2. **Find symbol references** (ESSENTIAL FOR UNDERSTANDING IMPACT):
+   - `mcp__go-language-server__references symbolName`
+   - Locate all usages of functions, types, or variables
+   - Critical for refactoring and understanding data flow
+
+3. **Get symbol information**:
+   - `mcp__go-language-server__hover filePath line column`
+   - Get type information and documentation at specific positions
+
+#### TypeScript LSP Tools (for frontend code in site/)
+
+1. **Find component/function definitions** (USE THIS FREQUENTLY):
+   - `mcp__typescript-language-server__definition symbolName`
+   - Example: `mcp__typescript-language-server__definition LoginPage`
+   - Quickly navigate to React components, hooks, and utility functions
+
+2. **Find symbol references** (ESSENTIAL FOR UNDERSTANDING IMPACT):
+   - `mcp__typescript-language-server__references symbolName`
+   - Locate all usages of components, types, or functions
+   - Critical for refactoring React components and understanding prop usage
+
+3. **Get type information**:
+   - `mcp__typescript-language-server__hover filePath line column`
+   - Get TypeScript type information and JSDoc documentation
+
+4. **Rename symbols safely**:
+   - `mcp__typescript-language-server__rename_symbol filePath line column newName`
+   - Rename components, props, or functions across the entire codebase
+
+5. **Check for TypeScript errors**:
+   - `mcp__typescript-language-server__diagnostics filePath`
+   - Get compilation errors and warnings for a specific file
+
+### Investigation Strategy (LSP-First Approach)
+
+#### Backend Investigation (Go)
+
+1. **Start with route registration** in `coderd/coderd.go` to understand API endpoints
+2. **Use Go LSP `definition` lookup** to trace from route handlers to actual implementations
+3. **Use Go LSP `references`** to understand how functions are called throughout the codebase
+4. **Follow the middleware chain** using LSP tools to understand request processing flow
+5. **Check test files** for expected behavior and error patterns
+
+#### Frontend Investigation (TypeScript/React)
+
+1. **Start with route definitions** in `site/src/App.tsx` or router configuration
+2. **Use TypeScript LSP `definition`** to navigate to React components and hooks
+3. **Use TypeScript LSP `references`** to find all component usages and prop drilling
+4. **Follow the component hierarchy** using LSP tools to understand data flow
+5. **Check for TypeScript errors** with `diagnostics` before making changes
+6. **Examine test files** (`.test.tsx`) for component behavior and expected props
+
+## Troubleshooting Development Issues
+
+### Common Issues
+
+1. **Development server won't start** - Use `./scripts/develop.sh` instead of manual commands
+2. **Database migration errors** - Check migration file format and use helper scripts
+3. **Audit table errors** - Update `enterprise/audit/table.go` with new fields
+4. **OAuth2 compliance issues** - Ensure RFC-compliant error responses
+
+### Debug Commands
+
+- Check linting: `make lint`
+- Generate code: `make gen`
+- Clean build: `make clean`
+
+## Development Environment Setup
+
+### Prerequisites
+
+- Go (version specified in go.mod)
+- Node.js and pnpm for frontend development
+- PostgreSQL for database testing
+- Docker for containerized testing
+
+### First Time Setup
+
+1. Clone the repository
+2. Run `./scripts/develop.sh` to start development server
+3. Access the development URL provided
+4. Create admin user as prompted
+5. Begin development

.claude/scripts/format.sh

@@ -0,0 +1,133 @@
+#!/bin/bash
+
+# Claude Code hook script for file formatting
+# This script integrates with the centralized Makefile formatting targets
+# and supports the Claude Code hooks system for automatic file formatting.
+
+set -euo pipefail
+
+# A variable to memoize the command for canonicalizing paths.
+_CANONICALIZE_CMD=""
+
+# canonicalize_path resolves a path to its absolute, canonical form.
+# It tries 'realpath' and 'readlink -f' in order.
+# The chosen command is memoized to avoid repeated checks.
+# If none of these are available, it returns an empty string.
+canonicalize_path() {
+	local path_to_resolve="$1"
+
+	# If we haven't determined a command yet, find one.
+	if [[ -z "$_CANONICALIZE_CMD" ]]; then
+		if command -v realpath >/dev/null 2>&1; then
+			_CANONICALIZE_CMD="realpath"
+		elif command -v readlink >/dev/null 2>&1 && readlink -f . >/dev/null 2>&1; then
+			_CANONICALIZE_CMD="readlink"
+		else
+			# No command found, so we can't resolve.
+			# We set a "none" value to prevent re-checking.
+			_CANONICALIZE_CMD="none"
+		fi
+	fi
+
+	# Now, execute the command.
+	case "$_CANONICALIZE_CMD" in
+	realpath)
+		realpath "$path_to_resolve" 2>/dev/null
+		;;
+	readlink)
+		readlink -f "$path_to_resolve" 2>/dev/null
+		;;
+	*)
+		# This handles the "none" case or any unexpected error.
+		echo ""
+		;;
+	esac
+}
+
+# Read JSON input from stdin
+input=$(cat)
+
+# Extract the file path from the JSON input
+# Expected format: {"tool_input": {"file_path": "/absolute/path/to/file"}} or {"tool_response": {"filePath": "/absolute/path/to/file"}}
+file_path=$(echo "$input" | jq -r '.tool_input.file_path // .tool_response.filePath // empty')
+
+# Secure path canonicalization to prevent path traversal attacks
+# Resolve repo root to an absolute, canonical path.
+repo_root_raw="$(cd "$(dirname "$0")/../.." && pwd)"
+repo_root="$(canonicalize_path "$repo_root_raw")"
+if [[ -z "$repo_root" ]]; then
+	# Fallback if canonicalization fails
+	repo_root="$repo_root_raw"
+fi
+
+# Resolve the input path to an absolute path
+if [[ "$file_path" = /* ]]; then
+	# Already absolute
+	abs_file_path="$file_path"
+else
+	# Make relative paths absolute from repo root
+	abs_file_path="$repo_root/$file_path"
+fi
+
+# Canonicalize the path (resolve symlinks and ".." segments)
+canonical_file_path="$(canonicalize_path "$abs_file_path")"
+
+# Check if canonicalization failed or if the resolved path is outside the repo
+if [[ -z "$canonical_file_path" ]] || { [[ "$canonical_file_path" != "$repo_root" ]] && [[ "$canonical_file_path" != "$repo_root"/* ]]; }; then
+	echo "Error: File path is outside repository or invalid: $file_path" >&2
+	exit 1
+fi
+
+# Handle the case where the file path is the repository root itself.
+if [[ "$canonical_file_path" == "$repo_root" ]]; then
+	echo "Warning: Formatting the repository root is not a supported operation. Skipping." >&2
+	exit 0
+fi
+
+# Convert back to relative path from repo root for consistency
+file_path="${canonical_file_path#"$repo_root"/}"
+
+if [[ -z "$file_path" ]]; then
+	echo "Error: No file path provided in input" >&2
+	exit 1
+fi
+
+# Check if file exists
+if [[ ! -f "$file_path" ]]; then
+	echo "Error: File does not exist: $file_path" >&2
+	exit 1
+fi
+
+# Get the file extension to determine the appropriate formatter
+file_ext="${file_path##*.}"
+
+# Change to the project root directory (where the Makefile is located)
+cd "$(dirname "$0")/../.."
+
+# Call the appropriate Makefile target based on file extension
+case "$file_ext" in
+go)
+	make fmt/go FILE="$file_path"
+	echo "✓ Formatted Go file: $file_path"
+	;;
+js | jsx | ts | tsx)
+	make fmt/ts FILE="$file_path"
+	echo "✓ Formatted TypeScript/JavaScript file: $file_path"
+	;;
+tf | tfvars)
+	make fmt/terraform FILE="$file_path"
+	echo "✓ Formatted Terraform file: $file_path"
+	;;
+sh)
+	make fmt/shfmt FILE="$file_path"
+	echo "✓ Formatted shell script: $file_path"
+	;;
+md)
+	make fmt/markdown FILE="$file_path"
+	echo "✓ Formatted Markdown file: $file_path"
+	;;
+*)
+	echo "No formatter available for file extension: $file_ext"
+	exit 0
+	;;
+esac

.claude/settings.json

@@ -0,0 +1,15 @@
+{
+	"hooks": {
+		"PostToolUse": [
+			{
+				"matcher": "Edit|Write|MultiEdit",
+				"hooks": [
+					{
+						"type": "command",
+						"command": ".claude/scripts/format.sh"
+					}
+				]
+			}
+		]
+	}
+}

.devcontainer/devcontainer.json

@@ -1,11 +1,16 @@
 {
 	"name": "Development environments on your infrastructure",
 	"image": "codercom/oss-dogfood:latest",
-
 	"features": {
-		// See all possible options here https://github.com/devcontainers/features/tree/main/src/docker-in-docker
 		"ghcr.io/devcontainers/features/docker-in-docker:2": {
 			"moby": "false"
+		},
+		"ghcr.io/coder/devcontainer-features/code-server:1": {
+			"auth": "none",
+			"port": 13337
+		},
+		"./filebrowser": {
+			"folder": "${containerWorkspaceFolder}"
 		}
 	},
 	// SYS_PTRACE to enable go debugging
@@ -13,6 +18,65 @@
 	"customizations": {
 		"vscode": {
 			"extensions": ["biomejs.biome"]
+		},
+		"coder": {
+			"apps": [
+				{
+					"slug": "cursor",
+					"displayName": "Cursor Desktop",
+					"url": "cursor://coder.coder-remote/openDevContainer?owner=${localEnv:CODER_WORKSPACE_OWNER_NAME}&workspace=${localEnv:CODER_WORKSPACE_NAME}&agent=${localEnv:CODER_WORKSPACE_PARENT_AGENT_NAME}&url=${localEnv:CODER_URL}&token=$SESSION_TOKEN&devContainerName=${localEnv:CONTAINER_ID}&devContainerFolder=${containerWorkspaceFolder}&localWorkspaceFolder=${localWorkspaceFolder}",
+					"external": true,
+					"icon": "/icon/cursor.svg",
+					"order": 1
+				},
+				{
+					"slug": "windsurf",
+					"displayName": "Windsurf Editor",
+					"url": "windsurf://coder.coder-remote/openDevContainer?owner=${localEnv:CODER_WORKSPACE_OWNER_NAME}&workspace=${localEnv:CODER_WORKSPACE_NAME}&agent=${localEnv:CODER_WORKSPACE_PARENT_AGENT_NAME}&url=${localEnv:CODER_URL}&token=$SESSION_TOKEN&devContainerName=${localEnv:CONTAINER_ID}&devContainerFolder=${containerWorkspaceFolder}&localWorkspaceFolder=${localWorkspaceFolder}",
+					"external": true,
+					"icon": "/icon/windsurf.svg",
+					"order": 4
+				},
+				{
+					"slug": "zed",
+					"displayName": "Zed Editor",
+					"url": "zed://ssh/${localEnv:CODER_WORKSPACE_AGENT_NAME}.${localEnv:CODER_WORKSPACE_NAME}.${localEnv:CODER_WORKSPACE_OWNER_NAME}.coder${containerWorkspaceFolder}",
+					"external": true,
+					"icon": "/icon/zed.svg",
+					"order": 5
+				},
+				// Reproduce `code-server` app here from the code-server
+				// feature so that we can set the correct folder and order.
+				// Currently, the order cannot be specified via option because
+				// we parse it as a number whereas variable interpolation
+				// results in a string. Additionally we set health check which
+				// is not yet set in the feature.
+				{
+					"slug": "code-server",
+					"displayName": "code-server",
+					"url": "http://${localEnv:FEATURE_CODE_SERVER_OPTION_HOST:127.0.0.1}:${localEnv:FEATURE_CODE_SERVER_OPTION_PORT:8080}/?folder=${containerWorkspaceFolder}",
+					"openIn": "${localEnv:FEATURE_CODE_SERVER_OPTION_APPOPENIN:slim-window}",
+					"share": "${localEnv:FEATURE_CODE_SERVER_OPTION_APPSHARE:owner}",
+					"icon": "/icon/code.svg",
+					"group": "${localEnv:FEATURE_CODE_SERVER_OPTION_APPGROUP:Web Editors}",
+					"order": 3,
+					"healthCheck": {
+						"url": "http://${localEnv:FEATURE_CODE_SERVER_OPTION_HOST:127.0.0.1}:${localEnv:FEATURE_CODE_SERVER_OPTION_PORT:8080}/healthz",
+						"interval": 5,
+						"threshold": 2
+					}
+				}
+			]
 		}
-	}
+	},
+	"mounts": [
+		// Add a volume for the Coder home directory to persist shell history,
+		// and speed up dotfiles init and/or personalization.
+		"source=coder-coder-devcontainer-home,target=/home/coder,type=volume",
+		// Mount the entire home because conditional mounts are not supported.
+		// See: https://github.com/devcontainers/spec/issues/132
+		"source=${localEnv:HOME},target=/mnt/home/coder,type=bind,readonly"
+	],
+	"postCreateCommand": ["./.devcontainer/scripts/post_create.sh"],
+	"postStartCommand": ["./.devcontainer/scripts/post_start.sh"]
 }

.devcontainer/filebrowser/devcontainer-feature.json

@@ -0,0 +1,46 @@
+{
+	"id": "filebrowser",
+	"version": "0.0.1",
+	"name": "File Browser",
+	"description": "A web-based file browser for your development container",
+	"options": {
+		"port": {
+			"type": "string",
+			"default": "13339",
+			"description": "The port to run filebrowser on"
+		},
+		"folder": {
+			"type": "string",
+			"default": "",
+			"description": "The root directory for filebrowser to serve"
+		},
+		"baseUrl": {
+			"type": "string",
+			"default": "",
+			"description": "The base URL for filebrowser (e.g., /filebrowser)"
+		}
+	},
+	"entrypoint": "/usr/local/bin/filebrowser-entrypoint",
+	"dependsOn": {
+		"ghcr.io/devcontainers/features/common-utils:2": {}
+	},
+	"customizations": {
+		"coder": {
+			"apps": [
+				{
+					"slug": "filebrowser",
+					"displayName": "File Browser",
+					"url": "http://localhost:${localEnv:FEATURE_FILEBROWSER_OPTION_PORT:13339}",
+					"icon": "/icon/filebrowser.svg",
+					"order": 3,
+					"subdomain": true,
+					"healthcheck": {
+						"url": "http://localhost:${localEnv:FEATURE_FILEBROWSER_OPTION_PORT:13339}/health",
+						"interval": 5,
+						"threshold": 2
+					}
+				}
+			]
+		}
+	}
+}

.devcontainer/filebrowser/install.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+BOLD='\033[0;1m'
+
+printf "%sInstalling filebrowser\n\n" "${BOLD}"
+
+# Check if filebrowser is installed.
+if ! command -v filebrowser &>/dev/null; then
+	VERSION="v2.42.1"
+	EXPECTED_HASH="7d83c0f077df10a8ec9bfd9bf6e745da5d172c3c768a322b0e50583a6bc1d3cc"
+
+	curl -fsSL "https://github.com/filebrowser/filebrowser/releases/download/${VERSION}/linux-amd64-filebrowser.tar.gz" -o /tmp/filebrowser.tar.gz
+	echo "${EXPECTED_HASH} /tmp/filebrowser.tar.gz" | sha256sum -c
+	tar -xzf /tmp/filebrowser.tar.gz -C /tmp
+	sudo mv /tmp/filebrowser /usr/local/bin/
+	sudo chmod +x /usr/local/bin/filebrowser
+	rm /tmp/filebrowser.tar.gz
+fi
+
+# Create entrypoint.
+cat >/usr/local/bin/filebrowser-entrypoint <<EOF
+#!/usr/bin/env bash
+
+PORT="${PORT}"
+FOLDER="${FOLDER:-}"
+FOLDER="\${FOLDER:-\$(pwd)}"
+BASEURL="${BASEURL:-}"
+LOG_PATH=/tmp/filebrowser.log
+export FB_DATABASE="\${HOME}/.filebrowser.db"
+
+printf "🛠️ Configuring filebrowser\n\n"
+
+# Check if filebrowser db exists.
+if [[ ! -f "\${FB_DATABASE}" ]]; then
+	filebrowser config init >>\${LOG_PATH} 2>&1
+	filebrowser users add admin "" --perm.admin=true --viewMode=mosaic >>\${LOG_PATH} 2>&1
+fi
+
+filebrowser config set --baseurl=\${BASEURL} --port=\${PORT} --auth.method=noauth --root=\${FOLDER} >>\${LOG_PATH} 2>&1
+
+printf "👷 Starting filebrowser...\n\n"
+
+printf "📂 Serving \${FOLDER} at http://localhost:\${PORT}\n\n"
+
+filebrowser >>\${LOG_PATH} 2>&1 &
+
+printf "📝 Logs at \${LOG_PATH}\n\n"
+EOF
+
+chmod +x /usr/local/bin/filebrowser-entrypoint
+
+printf "🥳 Installation complete!\n\n"

.devcontainer/scripts/post_create.sh

@@ -0,0 +1,59 @@
+#!/bin/sh
+
+install_devcontainer_cli() {
+	npm install -g @devcontainers/cli@0.80.0 --integrity=sha512-w2EaxgjyeVGyzfA/KUEZBhyXqu/5PyWNXcnrXsZOBrt3aN2zyGiHrXoG54TF6K0b5DSCF01Rt5fnIyrCeFzFKw==
+}
+
+install_ssh_config() {
+	echo "🔑 Installing SSH configuration..."
+	rsync -a /mnt/home/coder/.ssh/ ~/.ssh/
+	chmod 0700 ~/.ssh
+}
+
+install_git_config() {
+	echo "📂 Installing Git configuration..."
+	if [ -f /mnt/home/coder/git/config ]; then
+		rsync -a /mnt/home/coder/git/ ~/.config/git/
+	elif [ -d /mnt/home/coder/.gitconfig ]; then
+		rsync -a /mnt/home/coder/.gitconfig ~/.gitconfig
+	else
+		echo "⚠️ Git configuration directory not found."
+	fi
+}
+
+install_dotfiles() {
+	if [ ! -d /mnt/home/coder/.config/coderv2/dotfiles ]; then
+		echo "⚠️ Dotfiles directory not found."
+		return
+	fi
+
+	cd /mnt/home/coder/.config/coderv2/dotfiles || return
+	for script in install.sh install bootstrap.sh bootstrap script/bootstrap setup.sh setup script/setup; do
+		if [ -x $script ]; then
+			echo "📦 Installing dotfiles..."
+			./$script || {
+				echo "❌ Error running $script. Please check the script for issues."
+				return
+			}
+			echo "✅ Dotfiles installed successfully."
+			return
+		fi
+	done
+	echo "⚠️ No install script found in dotfiles directory."
+}
+
+personalize() {
+	# Allow script to continue as Coder dogfood utilizes a hack to
+	# synchronize startup script execution.
+	touch /tmp/.coder-startup-script.done
+
+	if [ -x /mnt/home/coder/personalize ]; then
+		echo "🎨 Personalizing environment..."
+		/mnt/home/coder/personalize
+	fi
+}
+
+install_devcontainer_cli
+install_ssh_config
+install_dotfiles
+personalize

.devcontainer/scripts/post_start.sh

@@ -0,0 +1,4 @@
+#!/bin/sh
+
+# Start Docker service if not already running.
+sudo service docker start

.editorconfig

@@ -7,7 +7,7 @@ trim_trailing_whitespace = true
 insert_final_newline = true
 indent_style = tab
 
-[*.{yaml,yml,tf,tfvars,nix}]
+[*.{yaml,yml,tf,tftpl,tfvars,nix}]
 indent_style = space
 indent_size = 2
 
@@ -18,3 +18,11 @@ indent_size = 2
 [coderd/database/dump.sql]
 indent_style = space
 indent_size = 4
+
+[coderd/database/queries/*.sql]
+indent_style = tab
+indent_size = 4
+
+[coderd/database/migrations/*.sql]
+indent_style = tab
+indent_size = 4

.gitattributes

@@ -15,6 +15,8 @@ provisionersdk/proto/*.go linguist-generated=true
 *.tfstate.json linguist-generated=true
 *.tfstate.dot linguist-generated=true
 *.tfplan.dot linguist-generated=true
+site/e2e/google/protobuf/timestampGenerated.ts
 site/e2e/provisionerGenerated.ts linguist-generated=true
+site/src/api/countriesGenerated.tsx linguist-generated=true
+site/src/api/rbacresourcesGenerated.tsx linguist-generated=true
 site/src/api/typesGenerated.ts linguist-generated=true
-site/src/pages/SetupPage/countries.tsx linguist-generated=true

.github/.linkspector.yml

@@ -25,5 +25,6 @@ ignorePatterns:
   - pattern: "docs.github.com"
   - pattern: "claude.ai"
   - pattern: "splunk.com"
+  - pattern: "stackoverflow.com/questions"
 aliveStatusCodes:
   - 200

.github/actions/embedded-pg-cache/download/action.yml

@@ -0,0 +1,49 @@
+name: "Download Embedded Postgres Cache"
+description: |
+  Downloads the embedded postgres cache and outputs today's cache key.
+  A PR job can use a cache if it was created by its base branch, its current
+  branch, or the default branch.
+  https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows#restrictions-for-accessing-a-cache
+outputs:
+  cache-key:
+    description: "Today's cache key"
+    value: ${{ steps.vars.outputs.cache-key }}
+inputs:
+  key-prefix:
+    description: "Prefix for the cache key"
+    required: true
+  cache-path:
+    description: "Path to the cache directory"
+    required: true
+runs:
+  using: "composite"
+  steps:
+    - name: Get date values and cache key
+      id: vars
+      shell: bash
+      run: |
+        export YEAR_MONTH=$(date +'%Y-%m')
+        export PREV_YEAR_MONTH=$(date -d 'last month' +'%Y-%m')
+        export DAY=$(date +'%d')
+        echo "year-month=$YEAR_MONTH" >> "$GITHUB_OUTPUT"
+        echo "prev-year-month=$PREV_YEAR_MONTH" >> "$GITHUB_OUTPUT"
+        echo "cache-key=${INPUTS_KEY_PREFIX}-${YEAR_MONTH}-${DAY}" >> "$GITHUB_OUTPUT"
+      env:
+        INPUTS_KEY_PREFIX: ${{ inputs.key-prefix }}
+
+    # By default, depot keeps caches for 14 days. This is plenty for embedded
+    # postgres, which changes infrequently.
+    # https://depot.dev/docs/github-actions/overview#cache-retention-policy
+    - name: Download embedded Postgres cache
+      uses: actions/cache/restore@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3
+      with:
+        path: ${{ inputs.cache-path }}
+        key: ${{ steps.vars.outputs.cache-key }}
+        # > If there are multiple partial matches for a restore key, the action returns the most recently created cache.
+        # https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows#matching-a-cache-key
+        # The second restore key allows non-main branches to use the cache from the previous month.
+        # This prevents PRs from rebuilding the cache on the first day of the month.
+        # It also makes sure that once a month, the cache is fully reset.
+        restore-keys: |
+          ${{ inputs.key-prefix }}-${{ steps.vars.outputs.year-month }}-
+          ${{ github.ref != 'refs/heads/main' && format('{0}-{1}-', inputs.key-prefix, steps.vars.outputs.prev-year-month) || '' }}

.github/actions/embedded-pg-cache/upload/action.yml

@@ -0,0 +1,18 @@
+name: "Upload Embedded Postgres Cache"
+description: Uploads the embedded Postgres cache. This only runs on the main branch.
+inputs:
+  cache-key:
+    description: "Cache key"
+    required: true
+  cache-path:
+    description: "Path to the cache directory"
+    required: true
+runs:
+  using: "composite"
+  steps:
+    - name: Upload Embedded Postgres cache
+      if: ${{ github.ref == 'refs/heads/main' }}
+      uses: actions/cache/save@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3
+      with:
+        path: ${{ inputs.cache-path }}
+        key: ${{ inputs.cache-key }}

.github/actions/setup-embedded-pg-cache-paths/action.yml

@@ -0,0 +1,33 @@
+name: "Setup Embedded Postgres Cache Paths"
+description: Sets up a path for cached embedded postgres binaries.
+outputs:
+  embedded-pg-cache:
+    description: "Value of EMBEDDED_PG_CACHE_DIR"
+    value: ${{ steps.paths.outputs.embedded-pg-cache }}
+  cached-dirs:
+    description: "directories that should be cached between CI runs"
+    value: ${{ steps.paths.outputs.cached-dirs }}
+runs:
+  using: "composite"
+  steps:
+    - name: Override Go paths
+      id: paths
+      uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
+      with:
+        script: |
+          const path = require('path');
+
+          // RUNNER_TEMP should be backed by a RAM disk on Windows if
+          // coder/setup-ramdisk-action was used
+          const runnerTemp = process.env.RUNNER_TEMP;
+          const embeddedPgCacheDir = path.join(runnerTemp, 'embedded-pg-cache');
+          core.exportVariable('EMBEDDED_PG_CACHE_DIR', embeddedPgCacheDir);
+          core.setOutput('embedded-pg-cache', embeddedPgCacheDir);
+          const cachedDirs = `${embeddedPgCacheDir}`;
+          core.setOutput('cached-dirs', cachedDirs);
+
+    - name: Create directories
+      shell: bash
+      run: |
+        set -e
+        mkdir -p "$EMBEDDED_PG_CACHE_DIR"

.github/actions/setup-go/action.yaml

@@ -4,7 +4,7 @@ description: |
 inputs:
   version:
     description: "The Go version to use."
-    default: "1.24.4"
+    default: "1.24.10"
   use-preinstalled-go:
     description: "Whether to use preinstalled Go."
     default: "false"

.github/actions/setup-node/action.yaml

@@ -16,7 +16,7 @@ runs:
     - name: Setup Node
       uses: actions/setup-node@0a44ba7841725637a19e28fa30b79a866c81b0a6 # v4.0.4
       with:
-        node-version: 20.16.0
+        node-version: 20.19.4
         # See https://github.com/actions/setup-node#caching-global-packages-data
         cache: "pnpm"
         cache-dependency-path: ${{ inputs.directory }}/pnpm-lock.yaml

.github/actions/setup-tf/action.yaml

@@ -7,5 +7,5 @@ runs:
     - name: Install Terraform
       uses: hashicorp/setup-terraform@b9cd54a3c349d3f38e8881555d616ced269862dd # v3.1.2
       with:
-        terraform_version: 1.12.2
+        terraform_version: 1.13.0
         terraform_wrapper: false

.github/actions/test-cache/download/action.yml

@@ -27,9 +27,11 @@ runs:
         export YEAR_MONTH=$(date +'%Y-%m')
         export PREV_YEAR_MONTH=$(date -d 'last month' +'%Y-%m')
         export DAY=$(date +'%d')
-        echo "year-month=$YEAR_MONTH" >> $GITHUB_OUTPUT
-        echo "prev-year-month=$PREV_YEAR_MONTH" >> $GITHUB_OUTPUT
-        echo "cache-key=${{ inputs.key-prefix }}-${YEAR_MONTH}-${DAY}" >> $GITHUB_OUTPUT
+        echo "year-month=$YEAR_MONTH" >> "$GITHUB_OUTPUT"
+        echo "prev-year-month=$PREV_YEAR_MONTH" >> "$GITHUB_OUTPUT"
+        echo "cache-key=${INPUTS_KEY_PREFIX}-${YEAR_MONTH}-${DAY}" >> "$GITHUB_OUTPUT"
+      env:
+        INPUTS_KEY_PREFIX: ${{ inputs.key-prefix }}
 
     # TODO: As a cost optimization, we could remove caches that are older than
     # a day or two. By default, depot keeps caches for 14 days, which isn't

.github/actions/upload-datadog/action.yaml

@@ -12,13 +12,12 @@ runs:
       run: |
         set -e
 
-        owner=${{ github.repository_owner	 }}
-        echo "owner: $owner"
-        if [[  $owner != "coder" ]]; then
+        echo "owner: $REPO_OWNER"
+        if [[ "$REPO_OWNER" != "coder" ]]; then
           echo "Not a pull request from the main repo, skipping..."
           exit 0
         fi
-        if [[ -z "${{ inputs.api-key }}" ]]; then
+        if [[ -z "${DATADOG_API_KEY}" ]]; then
           # This can happen for dependabot.
           echo "No API key provided, skipping..."
           exit 0
@@ -31,37 +30,38 @@ runs:
 
         TMP_DIR=$(mktemp -d)
 
-        if [[ "${{ runner.os }}" == "Windows" ]]; then
+        if [[ "${RUNNER_OS}" == "Windows" ]]; then
           BINARY_PATH="${TMP_DIR}/datadog-ci.exe"
           BINARY_URL="https://github.com/DataDog/datadog-ci/releases/download/${BINARY_VERSION}/datadog-ci_win-x64"
-        elif [[ "${{ runner.os }}" == "macOS" ]]; then
+        elif [[ "${RUNNER_OS}" == "macOS" ]]; then
           BINARY_PATH="${TMP_DIR}/datadog-ci"
           BINARY_URL="https://github.com/DataDog/datadog-ci/releases/download/${BINARY_VERSION}/datadog-ci_darwin-arm64"
-        elif [[ "${{ runner.os }}" == "Linux" ]]; then
+        elif [[ "${RUNNER_OS}" == "Linux" ]]; then
           BINARY_PATH="${TMP_DIR}/datadog-ci"
           BINARY_URL="https://github.com/DataDog/datadog-ci/releases/download/${BINARY_VERSION}/datadog-ci_linux-x64"
         else
-          echo "Unsupported OS: ${{ runner.os }}"
+          echo "Unsupported OS: $RUNNER_OS"
           exit 1
         fi
 
-        echo "Downloading DataDog CI binary version ${BINARY_VERSION} for ${{ runner.os }}..."
+        echo "Downloading DataDog CI binary version ${BINARY_VERSION} for $RUNNER_OS..."
         curl -sSL "$BINARY_URL" -o "$BINARY_PATH"
 
-        if [[ "${{ runner.os }}" == "Windows" ]]; then
+        if [[ "${RUNNER_OS}" == "Windows" ]]; then
           echo "$BINARY_HASH_WINDOWS  $BINARY_PATH" | sha256sum --check
-        elif [[ "${{ runner.os }}" == "macOS" ]]; then
+        elif [[ "${RUNNER_OS}" == "macOS" ]]; then
           echo "$BINARY_HASH_MACOS  $BINARY_PATH" | shasum -a 256 --check
-        elif [[ "${{ runner.os }}" == "Linux" ]]; then
+        elif [[ "${RUNNER_OS}" == "Linux" ]]; then
           echo "$BINARY_HASH_LINUX  $BINARY_PATH" | sha256sum --check
         fi
 
         # Make binary executable (not needed for Windows)
-        if [[ "${{ runner.os }}" != "Windows" ]]; then
+        if [[ "${RUNNER_OS}" != "Windows" ]]; then
           chmod +x "$BINARY_PATH"
         fi
 
         "$BINARY_PATH" junit upload --service coder ./gotests.xml \
-          --tags os:${{runner.os}} --tags runner_name:${{runner.name}}
+          --tags "os:${RUNNER_OS}" --tags "runner_name:${RUNNER_NAME}"
       env:
+        REPO_OWNER: ${{ github.repository_owner }}
         DATADOG_API_KEY: ${{ inputs.api-key }}

.github/dependabot.yaml

@@ -33,6 +33,7 @@ updates:
       - dependency-name: "*"
         update-types:
           - version-update:semver-patch
+      - dependency-name: "github.com/mark3labs/mcp-go"
 
   # Update our Dockerfile.
   - package-ecosystem: "docker"

.github/pull_request_template.md

@@ -0,0 +1 @@
+If you have used AI to produce some or all of this PR, please ensure you have read our [AI Contribution guidelines](https://coder.com/docs/about/contributing/AI_CONTRIBUTING) before submitting.

.github/workflows/contrib.yaml

@@ -3,6 +3,7 @@ name: contrib
 on:
   issue_comment:
     types: [created, edited]
+  # zizmor: ignore[dangerous-triggers] We explicitly want to run on pull_request_target.
   pull_request_target:
     types:
       - opened

.github/workflows/dependabot.yaml

@@ -15,7 +15,7 @@ jobs:
       github.event_name == 'pull_request' &&
       github.event.action == 'opened' &&
       github.event.pull_request.user.login == 'dependabot[bot]' &&
-      github.actor_id == 49699333 &&
+      github.event.pull_request.user.id == 49699333 &&
       github.repository == 'coder/coder'
     permissions:
       pull-requests: write
@@ -44,10 +44,6 @@ jobs:
           GH_TOKEN: ${{secrets.GITHUB_TOKEN}}
 
       - name: Send Slack notification
-        env:
-          PR_URL: ${{github.event.pull_request.html_url}}
-          PR_TITLE: ${{github.event.pull_request.title}}
-          PR_NUMBER: ${{github.event.pull_request.number}}
         run: |
           curl -X POST -H 'Content-type: application/json' \
           --data '{
@@ -58,7 +54,7 @@ jobs:
                 "type": "header",
                 "text": {
                   "type": "plain_text",
-                  "text": ":pr-merged: Auto merge enabled for Dependabot PR #${{ env.PR_NUMBER }}",
+                  "text": ":pr-merged: Auto merge enabled for Dependabot PR #'"${PR_NUMBER}"'",
                   "emoji": true
                 }
               },
@@ -67,7 +63,7 @@ jobs:
                 "fields": [
                   {
                     "type": "mrkdwn",
-                    "text": "${{ env.PR_TITLE }}"
+                    "text": "'"${PR_TITLE}"'"
                   }
                 ]
               },
@@ -80,9 +76,14 @@ jobs:
                       "type": "plain_text",
                       "text": "View PR"
                     },
-                    "url": "${{ env.PR_URL }}"
+                    "url": "'"${PR_URL}"'"
                   }
                 ]
               }
             ]
-          }' ${{ secrets.DEPENDABOT_PRS_SLACK_WEBHOOK }}
+          }' "${{ secrets.DEPENDABOT_PRS_SLACK_WEBHOOK }}"
+        env:
+          SLACK_WEBHOOK: ${{ secrets.DEPENDABOT_PRS_SLACK_WEBHOOK }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          PR_URL: ${{ github.event.pull_request.html_url }}

.github/workflows/docker-base.yaml

@@ -38,15 +38,17 @@ jobs:
     if: github.repository_owner == 'coder'
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          persist-credentials: false
 
       - name: Docker login
-        uses: docker/login-action@74a5d142397b4f367a81961eba4e8cd7edddf772 # v3.4.0
+        uses: docker/login-action@184bdaa0721073962dff0199f1fb9940f07167d1 # v3.5.0
         with:
           registry: ghcr.io
           username: ${{ github.actor }}

.github/workflows/docs-ci.yaml

@@ -23,12 +23,14 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          persist-credentials: false
 
       - name: Setup Node
         uses: ./.github/actions/setup-node
 
-      - uses: tj-actions/changed-files@666c9d29007687c52e3c7aa2aac6c0ffcadeadc3 # v45.0.7
+      - uses: tj-actions/changed-files@f963b3f3562b00b6d2dd25efc390eb04e51ef6c6 # v45.0.7
         id: changed-files
         with:
           files: |
@@ -39,10 +41,16 @@ jobs:
       - name: lint
         if: steps.changed-files.outputs.any_changed == 'true'
         run: |
-          pnpm exec markdownlint-cli2 ${{ steps.changed-files.outputs.all_changed_files }}
+          # shellcheck disable=SC2086
+          pnpm exec markdownlint-cli2 $ALL_CHANGED_FILES
+        env:
+          ALL_CHANGED_FILES: ${{ steps.changed-files.outputs.all_changed_files }}
 
       - name: fmt
         if: steps.changed-files.outputs.any_changed == 'true'
         run: |
           # markdown-table-formatter requires a space separated list of files
-          echo ${{ steps.changed-files.outputs.all_changed_files }} | tr ',' '\n' | pnpm exec markdown-table-formatter --check
+          # shellcheck disable=SC2086
+          echo $ALL_CHANGED_FILES | tr ',' '\n' | pnpm exec markdown-table-formatter --check
+        env:
+          ALL_CHANGED_FILES: ${{ steps.changed-files.outputs.all_changed_files }}

.github/workflows/dogfood.yaml

@@ -18,8 +18,7 @@ on:
   workflow_dispatch:
 
 permissions:
-  # Necessary for GCP authentication (https://github.com/google-github-actions/setup-gcloud#usage)
-  id-token: write
+  contents: read
 
 jobs:
   build_image:
@@ -27,15 +26,21 @@ jobs:
     runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-4' || 'ubuntu-latest' }}
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          persist-credentials: false
 
       - name: Setup Nix
-        uses: nixbuild/nix-quick-install-action@889f3180bb5f064ee9e3201428d04ae9e41d54ad # v31
+        uses: nixbuild/nix-quick-install-action@63ca48f939ee3b8d835f4126562537df0fee5b91 # v32
+        with:
+          # Pinning to 2.28 here, as Nix gets a "error: [json.exception.type_error.302] type must be array, but is string"
+          # on version 2.29 and above.
+          nix_version: "2.28.4"
 
       - uses: nix-community/cache-nix-action@135667ec418502fa5a3598af6fb9eb733888ce6a # v6.1.3
         with:
@@ -58,15 +63,16 @@ jobs:
 
       - name: Get branch name
         id: branch-name
-        uses: tj-actions/branch-names@dde14ac574a8b9b1cedc59a1cf312788af43d8d8 # v8.2.1
+        uses: tj-actions/branch-names@5250492686b253f06fa55861556d1027b067aeb5 # v9.0.2
 
       - name: "Branch name to Docker tag name"
         id: docker-tag-name
         run: |
-          tag=${{ steps.branch-name.outputs.current_branch }}
           # Replace / with --, e.g. user/feature => user--feature.
-          tag=${tag//\//--}
-          echo "tag=${tag}" >> $GITHUB_OUTPUT
+          tag=${BRANCH_NAME//\//--}
+          echo "tag=${tag}" >> "$GITHUB_OUTPUT"
+        env:
+          BRANCH_NAME: ${{ steps.branch-name.outputs.current_branch }}
 
       - name: Set up Depot CLI
         uses: depot/setup-action@b0b1ea4f69e92ebf5dea3f8713a1b0c37b2126a5 # v1.6.0
@@ -76,7 +82,7 @@ jobs:
 
       - name: Login to DockerHub
         if: github.ref == 'refs/heads/main'
-        uses: docker/login-action@74a5d142397b4f367a81961eba4e8cd7edddf772 # v3.4.0
+        uses: docker/login-action@184bdaa0721073962dff0199f1fb9940f07167d1 # v3.5.0
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_PASSWORD }}
@@ -103,32 +109,39 @@ jobs:
 
           CURRENT_SYSTEM=$(nix eval --impure --raw --expr 'builtins.currentSystem')
 
-          docker image tag codercom/oss-dogfood-nix:latest-$CURRENT_SYSTEM codercom/oss-dogfood-nix:${{ steps.docker-tag-name.outputs.tag }}
-          docker image push codercom/oss-dogfood-nix:${{ steps.docker-tag-name.outputs.tag }}
+          docker image tag "codercom/oss-dogfood-nix:latest-$CURRENT_SYSTEM" "codercom/oss-dogfood-nix:${DOCKER_TAG}"
+          docker image push "codercom/oss-dogfood-nix:${DOCKER_TAG}"
 
-          docker image tag codercom/oss-dogfood-nix:latest-$CURRENT_SYSTEM codercom/oss-dogfood-nix:latest
-          docker image push codercom/oss-dogfood-nix:latest
+          docker image tag "codercom/oss-dogfood-nix:latest-$CURRENT_SYSTEM" "codercom/oss-dogfood-nix:latest"
+          docker image push "codercom/oss-dogfood-nix:latest"
+        env:
+          DOCKER_TAG: ${{ steps.docker-tag-name.outputs.tag }}
 
   deploy_template:
     needs: build_image
     runs-on: ubuntu-latest
+    permissions:
+      # Necessary for GCP authentication (https://github.com/google-github-actions/setup-gcloud#usage)
+      id-token: write
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          persist-credentials: false
 
       - name: Setup Terraform
         uses: ./.github/actions/setup-tf
 
       - name: Authenticate to Google Cloud
-        uses: google-github-actions/auth@ba79af03959ebeac9769e648f473a284504d9193 # v2.1.10
+        uses: google-github-actions/auth@b7593ed2efd1c1617e1b0254da33b86225adb2a5 # v2.1.12
         with:
-          workload_identity_provider: projects/573722524737/locations/global/workloadIdentityPools/github/providers/github
-          service_account: coder-ci@coder-dogfood.iam.gserviceaccount.com
+          workload_identity_provider: ${{ vars.GCP_WORKLOAD_ID_PROVIDER }}
+          service_account: ${{ vars.GCP_SERVICE_ACCOUNT }}
 
       - name: Terraform init and validate
         run: |
@@ -148,12 +161,12 @@ jobs:
       - name: Get short commit SHA
         if: github.ref == 'refs/heads/main'
         id: vars
-        run: echo "sha_short=$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT
+        run: echo "sha_short=$(git rev-parse --short HEAD)" >> "$GITHUB_OUTPUT"
 
       - name: Get latest commit title
         if: github.ref == 'refs/heads/main'
         id: message
-        run: echo "pr_title=$(git log --format=%s -n 1 ${{ github.sha }})" >> $GITHUB_OUTPUT
+        run: echo "pr_title=$(git log --format=%s -n 1 ${{ github.sha }})" >> "$GITHUB_OUTPUT"
 
       - name: "Push template"
         if: github.ref == 'refs/heads/main'
@@ -165,6 +178,7 @@ jobs:
           CODER_URL: https://dev.coder.com
           CODER_SESSION_TOKEN: ${{ secrets.CODER_SESSION_TOKEN }}
           # Template source & details
+          TF_VAR_CODER_DOGFOOD_ANTHROPIC_API_KEY: ${{ secrets.CODER_DOGFOOD_ANTHROPIC_API_KEY }}
           TF_VAR_CODER_TEMPLATE_NAME: ${{ secrets.CODER_TEMPLATE_NAME }}
           TF_VAR_CODER_TEMPLATE_VERSION: ${{ steps.vars.outputs.sha_short }}
           TF_VAR_CODER_TEMPLATE_DIR: ./coder

.github/workflows/nightly-gauntlet.yaml

@@ -0,0 +1,219 @@
+# The nightly-gauntlet runs tests that are either too flaky or too slow to block
+# every PR.
+name: nightly-gauntlet
+on:
+  schedule:
+    # Every day at 4AM
+    - cron: "0 4 * * 1-5"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test-go-pg:
+    # make sure to adjust NUM_PARALLEL_PACKAGES and NUM_PARALLEL_TESTS below
+    # when changing runner sizes
+    runs-on: ${{ matrix.os == 'macos-latest' && github.repository_owner == 'coder' && 'depot-macos-latest' || matrix.os == 'windows-2022' && github.repository_owner == 'coder' && 'depot-windows-2022-16' || matrix.os }}
+    # This timeout must be greater than the timeout set by `go test` in
+    # `make test-postgres` to ensure we receive a trace of running
+    # goroutines. Setting this to the timeout +5m should work quite well
+    # even if some of the preceding steps are slow.
+    timeout-minutes: 25
+    strategy:
+      matrix:
+        os:
+          - macos-latest
+          - windows-2022
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        with:
+          egress-policy: audit
+
+      # macOS indexes all new files in the background. Our Postgres tests
+      # create and destroy thousands of databases on disk, and Spotlight
+      # tries to index all of them, seriously slowing down the tests.
+      - name: Disable Spotlight Indexing
+        if: runner.os == 'macOS'
+        run: |
+          enabled=$(sudo mdutil -a -s | { grep -Fc "Indexing enabled" || true; })
+          if [ "$enabled" -eq 0 ]; then
+            echo "Spotlight indexing is already disabled"
+            exit 0
+          fi
+          sudo mdutil -a -i off
+          sudo mdutil -X /
+          sudo launchctl bootout system /System/Library/LaunchDaemons/com.apple.metadata.mds.plist
+
+      # Set up RAM disks to speed up the rest of the job. This action is in
+      # a separate repository to allow its use before actions/checkout.
+      - name: Setup RAM Disks
+        if: runner.os == 'Windows'
+        uses: coder/setup-ramdisk-action@e1100847ab2d7bcd9d14bcda8f2d1b0f07b36f1b # v0.1.0
+
+      - name: Checkout
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          fetch-depth: 1
+          persist-credentials: false
+
+      - name: Setup Go
+        uses: ./.github/actions/setup-go
+        with:
+          # Runners have Go baked-in and Go will automatically
+          # download the toolchain configured in go.mod, so we don't
+          # need to reinstall it. It's faster on Windows runners.
+          use-preinstalled-go: ${{ runner.os == 'Windows' }}
+
+      - name: Setup Terraform
+        uses: ./.github/actions/setup-tf
+
+      - name: Setup Embedded Postgres Cache Paths
+        id: embedded-pg-cache
+        uses: ./.github/actions/setup-embedded-pg-cache-paths
+
+      - name: Download Embedded Postgres Cache
+        id: download-embedded-pg-cache
+        uses: ./.github/actions/embedded-pg-cache/download
+        with:
+          key-prefix: embedded-pg-${{ runner.os }}-${{ runner.arch }}
+          cache-path: ${{ steps.embedded-pg-cache.outputs.cached-dirs }}
+
+      - name: Test with PostgreSQL Database
+        env:
+          POSTGRES_VERSION: "13"
+          TS_DEBUG_DISCO: "true"
+          LC_CTYPE: "en_US.UTF-8"
+          LC_ALL: "en_US.UTF-8"
+        shell: bash
+        run: |
+          set -o errexit
+          set -o pipefail
+
+          if [ "${{ runner.os }}" == "Windows" ]; then
+            # Create a temp dir on the R: ramdisk drive for Windows. The default
+            # C: drive is extremely slow: https://github.com/actions/runner-images/issues/8755
+            mkdir -p "R:/temp/embedded-pg"
+            go run scripts/embedded-pg/main.go -path "R:/temp/embedded-pg" -cache "${EMBEDDED_PG_CACHE_DIR}"
+          elif [ "${{ runner.os }}" == "macOS" ]; then
+            # Postgres runs faster on a ramdisk on macOS too
+            mkdir -p /tmp/tmpfs
+            sudo mount_tmpfs -o noowners -s 8g /tmp/tmpfs
+            go run scripts/embedded-pg/main.go -path /tmp/tmpfs/embedded-pg -cache "${EMBEDDED_PG_CACHE_DIR}"
+          elif [ "${{ runner.os }}" == "Linux" ]; then
+            make test-postgres-docker
+          fi
+
+          # if macOS, install google-chrome for scaletests
+          # As another concern, should we really have this kind of external dependency
+          # requirement on standard CI?
+          if [ "${{ matrix.os }}" == "macos-latest" ]; then
+            brew install google-chrome
+          fi
+
+          # macOS will output "The default interactive shell is now zsh"
+          # intermittently in CI...
+          if [ "${{ matrix.os }}" == "macos-latest" ]; then
+            touch ~/.bash_profile && echo "export BASH_SILENCE_DEPRECATION_WARNING=1" >> ~/.bash_profile
+          fi
+
+          if [ "${{ runner.os }}" == "Windows" ]; then
+            # Our Windows runners have 16 cores.
+            # On Windows Postgres chokes up when we have 16x16=256 tests
+            # running in parallel, and dbtestutil.NewDB starts to take more than
+            # 10s to complete sometimes causing test timeouts. With 16x8=128 tests
+            # Postgres tends not to choke.
+            NUM_PARALLEL_PACKAGES=8
+            NUM_PARALLEL_TESTS=16
+          elif [ "${{ runner.os }}" == "macOS" ]; then
+            # Our macOS runners have 8 cores. We set NUM_PARALLEL_TESTS to 16
+            # because the tests complete faster and Postgres doesn't choke. It seems
+            # that macOS's tmpfs is faster than the one on Windows.
+            NUM_PARALLEL_PACKAGES=8
+            NUM_PARALLEL_TESTS=16
+          elif [ "${{ runner.os }}" == "Linux" ]; then
+            # Our Linux runners have 8 cores.
+            NUM_PARALLEL_PACKAGES=8
+            NUM_PARALLEL_TESTS=8
+          fi
+
+          # run tests without cache
+          TESTCOUNT="-count=1"
+
+          DB=ci gotestsum \
+            --format standard-quiet --packages "./..." \
+            -- -timeout=20m -v -p $NUM_PARALLEL_PACKAGES -parallel=$NUM_PARALLEL_TESTS $TESTCOUNT
+
+      - name: Upload Embedded Postgres Cache
+        uses: ./.github/actions/embedded-pg-cache/upload
+        # We only use the embedded Postgres cache on macOS and Windows runners.
+        if: runner.OS == 'macOS' || runner.OS == 'Windows'
+        with:
+          cache-key: ${{ steps.download-embedded-pg-cache.outputs.cache-key }}
+          cache-path: "${{ steps.embedded-pg-cache.outputs.embedded-pg-cache }}"
+
+      - name: Upload test stats to Datadog
+        timeout-minutes: 1
+        continue-on-error: true
+        uses: ./.github/actions/upload-datadog
+        if: success() || failure()
+        with:
+          api-key: ${{ secrets.DATADOG_API_KEY }}
+
+  notify-slack-on-failure:
+    needs:
+      - test-go-pg
+    runs-on: ubuntu-latest
+    if: failure() && github.ref == 'refs/heads/main'
+
+    steps:
+      - name: Send Slack notification
+        run: |
+          curl -X POST -H 'Content-type: application/json' \
+          --data '{
+            "blocks": [
+              {
+                "type": "header",
+                "text": {
+                  "type": "plain_text",
+                  "text": "❌ Nightly gauntlet failed",
+                  "emoji": true
+                }
+              },
+              {
+                "type": "section",
+                "fields": [
+                  {
+                    "type": "mrkdwn",
+                    "text": "*Workflow:*\n'"${GITHUB_WORKFLOW}"'"
+                  },
+                  {
+                    "type": "mrkdwn",
+                    "text": "*Committer:*\n'"${GITHUB_ACTOR}"'"
+                  },
+                  {
+                    "type": "mrkdwn",
+                    "text": "*Commit:*\n'"${GITHUB_SHA}"'"
+                  }
+                ]
+              },
+              {
+                "type": "section",
+                "text": {
+                  "type": "mrkdwn",
+                  "text": "*View failure:* <'"${RUN_URL}"'|Click here>"
+                }
+              },
+              {
+                "type": "section",
+                "text": {
+                  "type": "mrkdwn",
+                  "text": "<@U08TJ4YNCA3> investigate this CI failure. Check logs, search for existing issues, use git blame to find who last modified failing tests, create issue in coder/internal (not public repo), use title format \"flake: TestName\" for flaky tests, and assign to the person from git blame."
+                }
+              }
+            ]
+          }' "${SLACK_WEBHOOK}"
+        env:
+          SLACK_WEBHOOK: ${{ secrets.CI_FAILURE_SLACK_WEBHOOK }}
+          RUN_URL: "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"

.github/workflows/pr-auto-assign.yaml

@@ -3,6 +3,7 @@
 name: PR Auto Assign
 
 on:
+  # zizmor: ignore[dangerous-triggers] We explicitly want to run on pull_request_target.
   pull_request_target:
     types: [opened]
 
@@ -14,7 +15,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
         with:
           egress-policy: audit
 

.github/workflows/pr-cleanup.yaml

@@ -19,7 +19,7 @@ jobs:
       packages: write
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
         with:
           egress-policy: audit
 
@@ -27,10 +27,12 @@ jobs:
         id: pr_number
         run: |
           if [ -n "${{ github.event.pull_request.number }}" ]; then
-            echo "PR_NUMBER=${{ github.event.pull_request.number }}" >> $GITHUB_OUTPUT
+            echo "PR_NUMBER=${{ github.event.pull_request.number }}" >> "$GITHUB_OUTPUT"
           else
-            echo "PR_NUMBER=${{ github.event.inputs.pr_number }}" >> $GITHUB_OUTPUT
+            echo "PR_NUMBER=${PR_NUMBER}" >> "$GITHUB_OUTPUT"
           fi
+        env:
+          PR_NUMBER: ${{ github.event.inputs.pr_number }}
 
       - name: Delete image
         continue-on-error: true
@@ -51,17 +53,21 @@ jobs:
       - name: Delete helm release
         run: |
           set -euo pipefail
-          helm delete --namespace "pr${{ steps.pr_number.outputs.PR_NUMBER }}" "pr${{ steps.pr_number.outputs.PR_NUMBER }}" || echo "helm release not found"
+          helm delete --namespace "pr${PR_NUMBER}" "pr${PR_NUMBER}" || echo "helm release not found"
+        env:
+          PR_NUMBER: ${{ steps.pr_number.outputs.PR_NUMBER }}
 
       - name: "Remove PR namespace"
         run: |
-          kubectl delete namespace "pr${{ steps.pr_number.outputs.PR_NUMBER }}" || echo "namespace not found"
+          kubectl delete namespace "pr${PR_NUMBER}" || echo "namespace not found"
+        env:
+          PR_NUMBER: ${{ steps.pr_number.outputs.PR_NUMBER }}
 
       - name: "Remove DNS records"
         run: |
           set -euo pipefail
           # Get identifier for the record
-          record_id=$(curl -X GET "https://api.cloudflare.com/client/v4/zones/${{ secrets.PR_DEPLOYMENTS_ZONE_ID }}/dns_records?name=%2A.pr${{ steps.pr_number.outputs.PR_NUMBER }}.${{ secrets.PR_DEPLOYMENTS_DOMAIN }}" \
+          record_id=$(curl -X GET "https://api.cloudflare.com/client/v4/zones/${{ secrets.PR_DEPLOYMENTS_ZONE_ID }}/dns_records?name=%2A.pr${PR_NUMBER}.${{ secrets.PR_DEPLOYMENTS_DOMAIN }}" \
           -H "Authorization: Bearer ${{ secrets.PR_DEPLOYMENTS_CLOUDFLARE_API_TOKEN }}" \
           -H "Content-Type:application/json" | jq -r '.result[0].id') || echo "DNS record not found"
 
@@ -73,9 +79,13 @@ jobs:
             -H "Authorization: Bearer ${{ secrets.PR_DEPLOYMENTS_CLOUDFLARE_API_TOKEN }}" \
             -H "Content-Type:application/json" | jq -r '.success'
           ) || echo "DNS record not found"
+        env:
+          PR_NUMBER: ${{ steps.pr_number.outputs.PR_NUMBER }}
 
       - name: "Delete certificate"
         if: ${{ github.event.pull_request.merged == true }}
         run: |
           set -euxo pipefail
-          kubectl delete certificate "pr${{ steps.pr_number.outputs.PR_NUMBER }}-tls" -n pr-deployment-certs || echo "certificate not found"
+          kubectl delete certificate "pr${PR_NUMBER}-tls" -n pr-deployment-certs || echo "certificate not found"
+        env:
+          PR_NUMBER: ${{ steps.pr_number.outputs.PR_NUMBER }}

.github/workflows/pr-deploy.yaml

@@ -39,12 +39,14 @@ jobs:
       PR_OPEN: ${{ steps.check_pr.outputs.pr_open }}
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          persist-credentials: false
 
       - name: Check if PR is open
         id: check_pr
@@ -55,7 +57,7 @@ jobs:
             echo "PR doesn't exist or is closed."
             pr_open=false
           fi
-          echo "pr_open=$pr_open" >> $GITHUB_OUTPUT
+          echo "pr_open=$pr_open" >> "$GITHUB_OUTPUT"
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
@@ -74,14 +76,15 @@ jobs:
     runs-on: "ubuntu-latest"
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
         with:
           fetch-depth: 0
+          persist-credentials: false
 
       - name: Get PR number, title, and branch name
         id: pr_info
@@ -90,9 +93,11 @@ jobs:
           PR_NUMBER=$(gh pr view --json number | jq -r '.number')
           PR_TITLE=$(gh pr view --json title | jq -r '.title')
           PR_URL=$(gh pr view --json url | jq -r '.url')
-          echo "PR_URL=$PR_URL" >> $GITHUB_OUTPUT
-          echo "PR_NUMBER=$PR_NUMBER" >> $GITHUB_OUTPUT
-          echo "PR_TITLE=$PR_TITLE" >> $GITHUB_OUTPUT
+          {
+            echo "PR_URL=$PR_URL"
+            echo "PR_NUMBER=$PR_NUMBER"
+            echo "PR_TITLE=$PR_TITLE"
+          } >> "$GITHUB_OUTPUT"
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
@@ -100,8 +105,8 @@ jobs:
         id: set_tags
         run: |
           set -euo pipefail
-          echo "CODER_BASE_IMAGE_TAG=$CODER_BASE_IMAGE_TAG" >> $GITHUB_OUTPUT
-          echo "CODER_IMAGE_TAG=$CODER_IMAGE_TAG" >> $GITHUB_OUTPUT
+          echo "CODER_BASE_IMAGE_TAG=$CODER_BASE_IMAGE_TAG" >> "$GITHUB_OUTPUT"
+          echo "CODER_IMAGE_TAG=$CODER_IMAGE_TAG" >> "$GITHUB_OUTPUT"
         env:
           CODER_BASE_IMAGE_TAG: ghcr.io/coder/coder-preview-base:pr${{ steps.pr_info.outputs.PR_NUMBER }}
           CODER_IMAGE_TAG: ghcr.io/coder/coder-preview:pr${{ steps.pr_info.outputs.PR_NUMBER }}
@@ -118,14 +123,16 @@ jobs:
         id: check_deployment
         run: |
           set -euo pipefail
-          if helm status "pr${{ steps.pr_info.outputs.PR_NUMBER }}" --namespace "pr${{ steps.pr_info.outputs.PR_NUMBER }}" > /dev/null 2>&1; then
+          if helm status "pr${PR_NUMBER}" --namespace "pr${PR_NUMBER}" > /dev/null 2>&1; then
             echo "Deployment already exists. Skipping deployment."
             NEW=false
           else
             echo "Deployment doesn't exist."
             NEW=true
           fi
-          echo "NEW=$NEW" >> $GITHUB_OUTPUT
+          echo "NEW=$NEW" >> "$GITHUB_OUTPUT"
+        env:
+          PR_NUMBER: ${{ steps.pr_info.outputs.PR_NUMBER }}
 
       - name: Check changed files
         uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
@@ -154,17 +161,20 @@ jobs:
       - name: Print number of changed files
         run: |
           set -euo pipefail
-          echo "Total number of changed files: ${{ steps.filter.outputs.all_count }}"
-          echo "Number of ignored files: ${{ steps.filter.outputs.ignored_count }}"
+          echo "Total number of changed files: ${ALL_COUNT}"
+          echo "Number of ignored files: ${IGNORED_COUNT}"
+        env:
+          ALL_COUNT: ${{ steps.filter.outputs.all_count }}
+          IGNORED_COUNT: ${{ steps.filter.outputs.ignored_count }}
 
       - name: Build conditionals
         id: build_conditionals
         run: |
           set -euo pipefail
           # build if the workflow is manually triggered and the deployment doesn't exist (first build or force rebuild)
-          echo "first_or_force_build=${{ (github.event_name == 'workflow_dispatch' && steps.check_deployment.outputs.NEW == 'true') || github.event.inputs.build == 'true' }}" >> $GITHUB_OUTPUT
+          echo "first_or_force_build=${{ (github.event_name == 'workflow_dispatch' && steps.check_deployment.outputs.NEW == 'true') || github.event.inputs.build == 'true' }}" >> "$GITHUB_OUTPUT"
           # build if the deployment already exist and there are changes in the files that we care about (automatic updates)
-          echo "automatic_rebuild=${{ steps.check_deployment.outputs.NEW == 'false' && steps.filter.outputs.all_count > steps.filter.outputs.ignored_count }}" >> $GITHUB_OUTPUT
+          echo "automatic_rebuild=${{ steps.check_deployment.outputs.NEW == 'false' && steps.filter.outputs.all_count > steps.filter.outputs.ignored_count }}" >> "$GITHUB_OUTPUT"
 
   comment-pr:
     needs: get_info
@@ -174,7 +184,7 @@ jobs:
       pull-requests: write # needed for commenting on PRs
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
         with:
           egress-policy: audit
 
@@ -218,14 +228,15 @@ jobs:
       CODER_IMAGE_TAG: ${{ needs.get_info.outputs.CODER_IMAGE_TAG }}
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
         with:
           fetch-depth: 0
+          persist-credentials: false
 
       - name: Setup Node
         uses: ./.github/actions/setup-node
@@ -237,7 +248,7 @@ jobs:
         uses: ./.github/actions/setup-sqlc
 
       - name: GHCR Login
-        uses: docker/login-action@74a5d142397b4f367a81961eba4e8cd7edddf772 # v3.4.0
+        uses: docker/login-action@184bdaa0721073962dff0199f1fb9940f07167d1 # v3.5.0
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
@@ -250,12 +261,13 @@ jobs:
           make gen/mark-fresh
           export DOCKER_IMAGE_NO_PREREQUISITES=true
           version="$(./scripts/version.sh)"
-          export CODER_IMAGE_BUILD_BASE_TAG="$(CODER_IMAGE_BASE=coder-base ./scripts/image_tag.sh --version "$version")"
+          CODER_IMAGE_BUILD_BASE_TAG="$(CODER_IMAGE_BASE=coder-base ./scripts/image_tag.sh --version "$version")"
+          export CODER_IMAGE_BUILD_BASE_TAG
           make -j build/coder_linux_amd64
           ./scripts/build_docker.sh \
             --arch amd64 \
-            --target ${{ env.CODER_IMAGE_TAG }} \
-            --version $version \
+            --target "${CODER_IMAGE_TAG}" \
+            --version "$version" \
             --push \
             build/coder_linux_amd64
 
@@ -276,7 +288,7 @@ jobs:
       PR_HOSTNAME: "pr${{ needs.get_info.outputs.PR_NUMBER }}.${{ secrets.PR_DEPLOYMENTS_DOMAIN }}"
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
         with:
           egress-policy: audit
 
@@ -293,13 +305,13 @@ jobs:
           set -euo pipefail
           foundTag=$(
             gh api /orgs/coder/packages/container/coder-preview/versions |
-            jq -r --arg tag "pr${{ env.PR_NUMBER }}" '.[] |
+            jq -r --arg tag "pr${PR_NUMBER}" '.[] |
             select(.metadata.container.tags == [$tag]) |
             .metadata.container.tags[0]'
           )
           if [ -z "$foundTag" ]; then
             echo "Image not found"
-            echo "${{ env.CODER_IMAGE_TAG }} not found in ghcr.io/coder/coder-preview"
+            echo "${CODER_IMAGE_TAG} not found in ghcr.io/coder/coder-preview"
             exit 1
           else
             echo "Image found"
@@ -314,40 +326,42 @@ jobs:
           curl -X POST "https://api.cloudflare.com/client/v4/zones/${{ secrets.PR_DEPLOYMENTS_ZONE_ID }}/dns_records" \
             -H "Authorization: Bearer ${{ secrets.PR_DEPLOYMENTS_CLOUDFLARE_API_TOKEN }}" \
             -H "Content-Type:application/json" \
-            --data '{"type":"CNAME","name":"*.${{ env.PR_HOSTNAME }}","content":"${{ env.PR_HOSTNAME }}","ttl":1,"proxied":false}'
+            --data '{"type":"CNAME","name":"*.'"${PR_HOSTNAME}"'","content":"'"${PR_HOSTNAME}"'","ttl":1,"proxied":false}'
 
       - name: Create PR namespace
         if: needs.get_info.outputs.NEW == 'true' || github.event.inputs.deploy == 'true'
         run: |
           set -euo pipefail
           # try to delete the namespace, but don't fail if it doesn't exist
-          kubectl delete namespace "pr${{ env.PR_NUMBER }}" || true
-          kubectl create namespace "pr${{ env.PR_NUMBER }}"
+          kubectl delete namespace "pr${PR_NUMBER}" || true
+          kubectl create namespace "pr${PR_NUMBER}"
 
       - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          persist-credentials: false
 
       - name: Check and Create Certificate
         if: needs.get_info.outputs.NEW == 'true' || github.event.inputs.deploy == 'true'
         run: |
           # Using kubectl to check if a Certificate resource already exists
           # we are doing this to avoid letsenrypt rate limits
-          if ! kubectl get certificate pr${{ env.PR_NUMBER }}-tls -n pr-deployment-certs > /dev/null 2>&1; then
+          if ! kubectl get certificate "pr${PR_NUMBER}-tls" -n pr-deployment-certs > /dev/null 2>&1; then
             echo "Certificate doesn't exist. Creating a new one."
             envsubst < ./.github/pr-deployments/certificate.yaml | kubectl apply -f -
           else
             echo "Certificate exists. Skipping certificate creation."
           fi
-          echo "Copy certificate from pr-deployment-certs to pr${{ env.PR_NUMBER }} namespace"
-          until kubectl get secret pr${{ env.PR_NUMBER }}-tls -n pr-deployment-certs &> /dev/null
+          echo "Copy certificate from pr-deployment-certs to pr${PR_NUMBER} namespace"
+          until kubectl get secret "pr${PR_NUMBER}-tls" -n pr-deployment-certs &> /dev/null
           do
-            echo "Waiting for secret pr${{ env.PR_NUMBER }}-tls to be created..."
+            echo "Waiting for secret pr${PR_NUMBER}-tls to be created..."
             sleep 5
           done
           (
-            kubectl get secret pr${{ env.PR_NUMBER }}-tls -n pr-deployment-certs -o json |
+            kubectl get secret "pr${PR_NUMBER}-tls" -n pr-deployment-certs -o json |
             jq 'del(.metadata.namespace,.metadata.creationTimestamp,.metadata.resourceVersion,.metadata.selfLink,.metadata.uid,.metadata.managedFields)' |
-            kubectl -n pr${{ env.PR_NUMBER }} apply -f -
+            kubectl -n "pr${PR_NUMBER}" apply -f -
           )
 
       - name: Set up PostgreSQL database
@@ -355,13 +369,13 @@ jobs:
         run: |
           helm repo add bitnami https://charts.bitnami.com/bitnami
           helm install coder-db bitnami/postgresql \
-            --namespace pr${{ env.PR_NUMBER }} \
+            --namespace "pr${PR_NUMBER}" \
             --set auth.username=coder \
             --set auth.password=coder \
             --set auth.database=coder \
             --set persistence.size=10Gi
-          kubectl create secret generic coder-db-url -n pr${{ env.PR_NUMBER }} \
-            --from-literal=url="postgres://coder:coder@coder-db-postgresql.pr${{ env.PR_NUMBER }}.svc.cluster.local:5432/coder?sslmode=disable"
+          kubectl create secret generic coder-db-url -n "pr${PR_NUMBER}" \
+            --from-literal=url="postgres://coder:coder@coder-db-postgresql.pr${PR_NUMBER}.svc.cluster.local:5432/coder?sslmode=disable"
 
       - name: Create a service account, role, and rolebinding for the PR namespace
         if: needs.get_info.outputs.NEW == 'true' || github.event.inputs.deploy == 'true'
@@ -383,8 +397,8 @@ jobs:
         run: |
           set -euo pipefail
           helm dependency update --skip-refresh ./helm/coder
-          helm upgrade --install "pr${{ env.PR_NUMBER }}" ./helm/coder \
-          --namespace "pr${{ env.PR_NUMBER }}" \
+          helm upgrade --install "pr${PR_NUMBER}" ./helm/coder \
+          --namespace "pr${PR_NUMBER}" \
           --values ./pr-deploy-values.yaml \
           --force
 
@@ -393,8 +407,8 @@ jobs:
         run: |
           helm repo add coder-logstream-kube https://helm.coder.com/logstream-kube
           helm upgrade --install coder-logstream-kube coder-logstream-kube/coder-logstream-kube \
-            --namespace "pr${{ env.PR_NUMBER }}" \
-            --set url="https://${{ env.PR_HOSTNAME }}"
+            --namespace "pr${PR_NUMBER}" \
+            --set url="https://${PR_HOSTNAME}"
 
       - name: Get Coder binary
         if: needs.get_info.outputs.NEW == 'true' || github.event.inputs.deploy == 'true'
@@ -402,16 +416,16 @@ jobs:
           set -euo pipefail
 
           DEST="${HOME}/coder"
-          URL="https://${{ env.PR_HOSTNAME }}/bin/coder-linux-amd64"
+          URL="https://${PR_HOSTNAME}/bin/coder-linux-amd64"
 
-          mkdir -p "$(dirname ${DEST})"
+          mkdir -p "$(dirname "$DEST")"
 
           COUNT=0
-          until $(curl --output /dev/null --silent --head --fail "$URL"); do
+          until curl --output /dev/null --silent --head --fail "$URL"; do
               printf '.'
               sleep 5
               COUNT=$((COUNT+1))
-              if [ $COUNT -ge 60 ]; then
+              if [ "$COUNT" -ge 60 ]; then
                 echo "Timed out waiting for URL to be available"
                 exit 1
               fi
@@ -420,7 +434,7 @@ jobs:
           curl -fsSL "$URL" -o "${DEST}"
           chmod +x "${DEST}"
           "${DEST}" version
-          mv "${DEST}" /usr/local/bin/coder
+          sudo mv "${DEST}" /usr/local/bin/coder
 
       - name: Create first user
         if: needs.get_info.outputs.NEW == 'true' || github.event.inputs.deploy == 'true'
@@ -435,24 +449,24 @@ jobs:
 
           # add mask so that the password is not printed to the logs
           echo "::add-mask::$password"
-          echo "password=$password" >> $GITHUB_OUTPUT
+          echo "password=$password" >> "$GITHUB_OUTPUT"
 
           coder login \
-            --first-user-username pr${{ env.PR_NUMBER }}-admin \
-            --first-user-email pr${{ env.PR_NUMBER }}@coder.com \
-            --first-user-password $password \
+            --first-user-username "pr${PR_NUMBER}-admin" \
+            --first-user-email "pr${PR_NUMBER}@coder.com" \
+            --first-user-password "$password" \
             --first-user-trial=false \
             --use-token-as-session \
-            https://${{ env.PR_HOSTNAME }}
+            "https://${PR_HOSTNAME}"
 
           # Create a user for the github.actor
           # TODO: update once https://github.com/coder/coder/issues/15466 is resolved
           # coder users create \
-          #   --username ${{ github.actor }} \
+          #   --username ${GITHUB_ACTOR} \
           #   --login-type github
 
           # promote the user to admin role
-          # coder org members edit-role ${{ github.actor }} organization-admin
+          # coder org members edit-role ${GITHUB_ACTOR} organization-admin
           # TODO: update once https://github.com/coder/internal/issues/207 is resolved
 
       - name: Send Slack notification
@@ -461,17 +475,19 @@ jobs:
           curl -s -o /dev/null -X POST -H 'Content-type: application/json' \
             -d \
             '{
-              "pr_number": "'"${{ env.PR_NUMBER }}"'",
-              "pr_url": "'"${{ env.PR_URL }}"'",
-              "pr_title": "'"${{ env.PR_TITLE }}"'",
-              "pr_access_url": "'"https://${{ env.PR_HOSTNAME }}"'",
-              "pr_username": "'"pr${{ env.PR_NUMBER }}-admin"'",
-              "pr_email": "'"pr${{ env.PR_NUMBER }}@coder.com"'",
-              "pr_password": "'"${{ steps.setup_deployment.outputs.password }}"'",
-              "pr_actor": "'"${{ github.actor }}"'"
+              "pr_number": "'"${PR_NUMBER}"'",
+              "pr_url": "'"${PR_URL}"'",
+              "pr_title": "'"${PR_TITLE}"'",
+              "pr_access_url": "'"https://${PR_HOSTNAME}"'",
+              "pr_username": "'"pr${PR_NUMBER}-admin"'",
+              "pr_email": "'"pr${PR_NUMBER}@coder.com"'",
+              "pr_password": "'"${PASSWORD}"'",
+              "pr_actor": "'"${GITHUB_ACTOR}"'"
             }' \
             ${{ secrets.PR_DEPLOYMENTS_SLACK_WEBHOOK }}
           echo "Slack notification sent"
+        env:
+          PASSWORD: ${{ steps.setup_deployment.outputs.password }}
 
       - name: Find Comment
         uses: peter-evans/find-comment@3eae4d37986fb5a8592848f6a574fdf654e61f9e # v3.1.0
@@ -504,7 +520,7 @@ jobs:
         run: |
           set -euo pipefail
           cd .github/pr-deployments/template
-          coder templates push -y --variable namespace=pr${{ env.PR_NUMBER }} kubernetes
+          coder templates push -y --variable "namespace=pr${PR_NUMBER}" kubernetes
 
           # Create workspace
           coder create --template="kubernetes" kube --parameter cpu=2 --parameter memory=4 --parameter home_disk_size=2 -y

.github/workflows/release-validation.yaml

@@ -14,7 +14,7 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
         with:
           egress-policy: audit
 

.github/workflows/release.yaml

@@ -32,15 +32,43 @@ env:
   CODER_RELEASE_NOTES: ${{ inputs.release_notes }}
 
 jobs:
+  # Only allow maintainers/admins to release.
+  check-perms:
+    runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-8' || 'ubuntu-latest' }}
+    steps:
+      - name: Allow only maintainers/admins
+        uses: actions/github-script@v7.0.1
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const {data} = await github.rest.repos.getCollaboratorPermissionLevel({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              username: context.actor
+            });
+            const role = data.role_name || data.user?.role_name || data.permission;
+            const perms = data.user?.permissions || {};
+            core.info(`Actor ${context.actor} permission=${data.permission}, role_name=${role}`);
+
+            const allowed =
+              role === 'admin' ||
+              role === 'maintain' ||
+              perms.admin === true ||
+              perms.maintain === true;
+
+            if (!allowed) core.setFailed('Denied: requires maintain or admin');
+
   # build-dylib is a separate job to build the dylib on macOS.
   build-dylib:
     runs-on: ${{ github.repository_owner == 'coder' && 'depot-macos-latest' || 'macos-latest' }}
+    needs: check-perms
     steps:
       # Harden Runner doesn't work on macOS.
       - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
         with:
           fetch-depth: 0
+          persist-credentials: false
 
       # If the event that triggered the build was an annotated tag (which our
       # tags are supposed to be), actions/checkout has a bug where the tag in
@@ -53,14 +81,16 @@ jobs:
       - name: Setup build tools
         run: |
           brew install bash gnu-getopt make
-          echo "$(brew --prefix bash)/bin" >> $GITHUB_PATH
-          echo "$(brew --prefix gnu-getopt)/bin" >> $GITHUB_PATH
-          echo "$(brew --prefix make)/libexec/gnubin" >> $GITHUB_PATH
+          {
+            echo "$(brew --prefix bash)/bin"
+            echo "$(brew --prefix gnu-getopt)/bin"
+            echo "$(brew --prefix make)/libexec/gnubin"
+          } >> "$GITHUB_PATH"
 
       - name: Switch XCode Version
         uses: maxim-lobanov/setup-xcode@60606e260d2fc5762a71e64e74b2174e8ea3c8bd # v1.6.0
         with:
-          xcode-version: "16.0.0"
+          xcode-version: "16.1.0"
 
       - name: Setup Go
         uses: ./.github/actions/setup-go
@@ -114,7 +144,7 @@ jobs:
 
   release:
     name: Build and publish
-    needs: build-dylib
+    needs: [build-dylib, check-perms]
     runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-8' || 'ubuntu-latest' }}
     permissions:
       # Required to publish a release
@@ -134,14 +164,15 @@ jobs:
       version: ${{ steps.version.outputs.version }}
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
         with:
           fetch-depth: 0
+          persist-credentials: false
 
       # If the event that triggered the build was an annotated tag (which our
       # tags are supposed to be), actions/checkout has a bug where the tag in
@@ -156,9 +187,9 @@ jobs:
         run: |
           set -euo pipefail
           version="$(./scripts/version.sh)"
-          echo "version=$version" >> $GITHUB_OUTPUT
+          echo "version=$version" >> "$GITHUB_OUTPUT"
           # Speed up future version.sh calls.
-          echo "CODER_FORCE_VERSION=$version" >> $GITHUB_ENV
+          echo "CODER_FORCE_VERSION=$version" >> "$GITHUB_ENV"
           echo "$version"
 
       # Verify that all expectations for a release are met.
@@ -200,7 +231,7 @@ jobs:
 
           release_notes_file="$(mktemp -t release_notes.XXXXXX)"
           echo "$CODER_RELEASE_NOTES" > "$release_notes_file"
-          echo CODER_RELEASE_NOTES_FILE="$release_notes_file" >> $GITHUB_ENV
+          echo CODER_RELEASE_NOTES_FILE="$release_notes_file" >> "$GITHUB_ENV"
 
       - name: Show release notes
         run: |
@@ -208,7 +239,7 @@ jobs:
           cat "$CODER_RELEASE_NOTES_FILE"
 
       - name: Docker Login
-        uses: docker/login-action@74a5d142397b4f367a81961eba4e8cd7edddf772 # v3.4.0
+        uses: docker/login-action@184bdaa0721073962dff0199f1fb9940f07167d1 # v3.5.0
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
@@ -286,17 +317,17 @@ jobs:
       # Setup GCloud for signing Windows binaries.
       - name: Authenticate to Google Cloud
         id: gcloud_auth
-        uses: google-github-actions/auth@ba79af03959ebeac9769e648f473a284504d9193 # v2.1.10
+        uses: google-github-actions/auth@b7593ed2efd1c1617e1b0254da33b86225adb2a5 # v2.1.12
         with:
-          workload_identity_provider: ${{ secrets.GCP_CODE_SIGNING_WORKLOAD_ID_PROVIDER }}
-          service_account: ${{ secrets.GCP_CODE_SIGNING_SERVICE_ACCOUNT }}
+          workload_identity_provider: ${{ vars.GCP_CODE_SIGNING_WORKLOAD_ID_PROVIDER }}
+          service_account: ${{ vars.GCP_CODE_SIGNING_SERVICE_ACCOUNT }}
           token_format: "access_token"
 
       - name: Setup GCloud SDK
-        uses: google-github-actions/setup-gcloud@77e7a554d41e2ee56fc945c52dfd3f33d12def9a # v2.1.4
+        uses: google-github-actions/setup-gcloud@cb1e50a9932213ecece00a606661ae9ca44f3397 # v2.2.0
 
       - name: Download dylibs
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0
         with:
           name: dylibs
           path: ./build
@@ -323,6 +354,8 @@ jobs:
         env:
           CODER_SIGN_WINDOWS: "1"
           CODER_SIGN_DARWIN: "1"
+          CODER_SIGN_GPG: "1"
+          CODER_GPG_RELEASE_KEY_BASE64: ${{ secrets.GPG_RELEASE_KEY_BASE64 }}
           CODER_WINDOWS_RESOURCES: "1"
           AC_CERTIFICATE_FILE: /tmp/apple_cert.p12
           AC_CERTIFICATE_PASSWORD_FILE: /tmp/apple_cert_password.txt
@@ -348,9 +381,9 @@ jobs:
           set -euo pipefail
           if [[ "${CODER_RELEASE:-}" != *t* ]] || [[ "${CODER_DRY_RUN:-}" == *t* ]]; then
             # Empty value means use the default and avoid building a fresh one.
-            echo "tag=" >> $GITHUB_OUTPUT
+            echo "tag=" >> "$GITHUB_OUTPUT"
           else
-            echo "tag=$(CODER_IMAGE_BASE=ghcr.io/coder/coder-base ./scripts/image_tag.sh)" >> $GITHUB_OUTPUT
+            echo "tag=$(CODER_IMAGE_BASE=ghcr.io/coder/coder-base ./scripts/image_tag.sh)" >> "$GITHUB_OUTPUT"
           fi
 
       - name: Create empty base-build-context directory
@@ -385,7 +418,7 @@ jobs:
           # available immediately
           for i in {1..10}; do
             rc=0
-            raw_manifests=$(docker buildx imagetools inspect --raw "${{ steps.image-base-tag.outputs.tag }}") || rc=$?
+            raw_manifests=$(docker buildx imagetools inspect --raw "${IMAGE_TAG}") || rc=$?
             if [[ "$rc" -eq 0 ]]; then
               break
             fi
@@ -407,6 +440,8 @@ jobs:
           echo "$manifests" | grep -q linux/amd64
           echo "$manifests" | grep -q linux/arm64
           echo "$manifests" | grep -q linux/arm/v7
+        env:
+          IMAGE_TAG: ${{ steps.image-base-tag.outputs.tag }}
 
       # GitHub attestation provides SLSA provenance for Docker images, establishing a verifiable
       # record that these images were built in GitHub Actions with specific inputs and environment.
@@ -474,7 +509,7 @@ jobs:
 
           # Save multiarch image tag for attestation
           multiarch_image="$(./scripts/image_tag.sh)"
-          echo "multiarch_image=${multiarch_image}" >> $GITHUB_OUTPUT
+          echo "multiarch_image=${multiarch_image}" >> "$GITHUB_OUTPUT"
 
           # For debugging, print all docker image tags
           docker images
@@ -482,16 +517,15 @@ jobs:
           # if the current version is equal to the highest (according to semver)
           # version in the repo, also create a multi-arch image as ":latest" and
           # push it
-          created_latest_tag=false
           if [[ "$(git tag | grep '^v' | grep -vE '(rc|dev|-|\+|\/)' | sort -r --version-sort | head -n1)" == "v$(./scripts/version.sh)" ]]; then
+            # shellcheck disable=SC2046
             ./scripts/build_docker_multiarch.sh \
               --push \
               --target "$(./scripts/image_tag.sh --version latest)" \
               $(cat build/coder_"$version"_linux_{amd64,arm64,armv7}.tag)
-            created_latest_tag=true
-            echo "created_latest_tag=true" >> $GITHUB_OUTPUT
+            echo "created_latest_tag=true" >> "$GITHUB_OUTPUT"
           else
-            echo "created_latest_tag=false" >> $GITHUB_OUTPUT
+            echo "created_latest_tag=false" >> "$GITHUB_OUTPUT"
           fi
         env:
           CODER_BASE_IMAGE_TAG: ${{ steps.image-base-tag.outputs.tag }}
@@ -499,24 +533,27 @@ jobs:
       - name: SBOM Generation and Attestation
         if: ${{ !inputs.dry_run }}
         env:
-          COSIGN_EXPERIMENTAL: "1"
+          COSIGN_EXPERIMENTAL: '1'
+          MULTIARCH_IMAGE: ${{ steps.build_docker.outputs.multiarch_image }}
+          VERSION: ${{ steps.version.outputs.version }}
+          CREATED_LATEST_TAG: ${{ steps.build_docker.outputs.created_latest_tag }}
         run: |
           set -euxo pipefail
 
           # Generate SBOM for multi-arch image with version in filename
-          echo "Generating SBOM for multi-arch image: ${{ steps.build_docker.outputs.multiarch_image }}"
-          syft "${{ steps.build_docker.outputs.multiarch_image }}" -o spdx-json > coder_${{ steps.version.outputs.version }}_sbom.spdx.json
+          echo "Generating SBOM for multi-arch image: ${MULTIARCH_IMAGE}"
+          syft "${MULTIARCH_IMAGE}" -o spdx-json > "coder_${VERSION}_sbom.spdx.json"
 
           # Attest SBOM to multi-arch image
-          echo "Attesting SBOM to multi-arch image: ${{ steps.build_docker.outputs.multiarch_image }}"
-          cosign clean --force=true "${{ steps.build_docker.outputs.multiarch_image }}"
+          echo "Attesting SBOM to multi-arch image: ${MULTIARCH_IMAGE}"
+          cosign clean --force=true "${MULTIARCH_IMAGE}"
           cosign attest --type spdxjson \
-            --predicate coder_${{ steps.version.outputs.version }}_sbom.spdx.json \
+            --predicate "coder_${VERSION}_sbom.spdx.json" \
             --yes \
-            "${{ steps.build_docker.outputs.multiarch_image }}"
+            "${MULTIARCH_IMAGE}"
 
           # If latest tag was created, also attest it
-          if [[ "${{ steps.build_docker.outputs.created_latest_tag }}" == "true" ]]; then
+          if [[ "${CREATED_LATEST_TAG}" == "true" ]]; then
             latest_tag="$(./scripts/image_tag.sh --version latest)"
             echo "Generating SBOM for latest image: ${latest_tag}"
             syft "${latest_tag}" -o spdx-json > coder_latest_sbom.spdx.json
@@ -570,7 +607,7 @@ jobs:
       - name: Get latest tag name
         id: latest_tag
         if: ${{ !inputs.dry_run && steps.build_docker.outputs.created_latest_tag == 'true' }}
-        run: echo "tag=$(./scripts/image_tag.sh --version latest)" >> $GITHUB_OUTPUT
+        run: echo "tag=$(./scripts/image_tag.sh --version latest)" >> "$GITHUB_OUTPUT"
 
       # If this is the highest version according to semver, also attest the "latest" tag
       - name: GitHub Attestation for "latest" Docker image
@@ -613,7 +650,7 @@ jobs:
       # Report attestation failures but don't fail the workflow
       - name: Check attestation status
         if: ${{ !inputs.dry_run }}
-        run: |
+        run: | # zizmor: ignore[template-injection] We're just reading steps.attest_x.outcome here, no risk of injection
           if [[ "${{ steps.attest_base.outcome }}" == "failure" && "${{ steps.attest_base.conclusion }}" != "skipped" ]]; then
             echo "::warning::GitHub attestation for base image failed"
           fi
@@ -632,6 +669,30 @@ jobs:
       - name: ls build
         run: ls -lh build
 
+      - name: Publish Coder CLI binaries and detached signatures to GCS
+        if: ${{ !inputs.dry_run }}
+        run: |
+          set -euxo pipefail
+
+          version="$(./scripts/version.sh)"
+
+          # Source array of slim binaries
+          declare -A binaries
+          binaries["coder-darwin-amd64"]="coder-slim_${version}_darwin_amd64"
+          binaries["coder-darwin-arm64"]="coder-slim_${version}_darwin_arm64"
+          binaries["coder-linux-amd64"]="coder-slim_${version}_linux_amd64"
+          binaries["coder-linux-arm64"]="coder-slim_${version}_linux_arm64"
+          binaries["coder-linux-armv7"]="coder-slim_${version}_linux_armv7"
+          binaries["coder-windows-amd64.exe"]="coder-slim_${version}_windows_amd64.exe"
+          binaries["coder-windows-arm64.exe"]="coder-slim_${version}_windows_arm64.exe"
+
+          for cli_name in "${!binaries[@]}"; do
+            slim_binary="${binaries[$cli_name]}"
+            detached_signature="${slim_binary}.asc"
+            gcloud storage cp "./build/${slim_binary}" "gs://releases.coder.com/coder-cli/${version}/${cli_name}"
+            gcloud storage cp "./build/${detached_signature}" "gs://releases.coder.com/coder-cli/${version}/${cli_name}.asc"
+          done
+
       - name: Publish release
         run: |
           set -euo pipefail
@@ -654,11 +715,11 @@ jobs:
             ./build/*.apk
             ./build/*.deb
             ./build/*.rpm
-            ./coder_${{ steps.version.outputs.version }}_sbom.spdx.json
+            "./coder_${VERSION}_sbom.spdx.json"
           )
 
           # Only include the latest SBOM file if it was created
-          if [[ "${{ steps.build_docker.outputs.created_latest_tag }}" == "true" ]]; then
+          if [[ "${CREATED_LATEST_TAG}" == "true" ]]; then
             files+=(./coder_latest_sbom.spdx.json)
           fi
 
@@ -669,15 +730,17 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           CODER_GPG_RELEASE_KEY_BASE64: ${{ secrets.GPG_RELEASE_KEY_BASE64 }}
+          VERSION: ${{ steps.version.outputs.version }}
+          CREATED_LATEST_TAG: ${{ steps.build_docker.outputs.created_latest_tag }}
 
       - name: Authenticate to Google Cloud
-        uses: google-github-actions/auth@ba79af03959ebeac9769e648f473a284504d9193 # v2.1.10
+        uses: google-github-actions/auth@b7593ed2efd1c1617e1b0254da33b86225adb2a5 # v2.1.12
         with:
-          workload_identity_provider: ${{ secrets.GCP_WORKLOAD_ID_PROVIDER }}
-          service_account: ${{ secrets.GCP_SERVICE_ACCOUNT }}
+          workload_identity_provider: ${{ vars.GCP_WORKLOAD_ID_PROVIDER }}
+          service_account: ${{ vars.GCP_SERVICE_ACCOUNT }}
 
       - name: Setup GCloud SDK
-        uses: google-github-actions/setup-gcloud@77e7a554d41e2ee56fc945c52dfd3f33d12def9a # 2.1.4
+        uses: google-github-actions/setup-gcloud@cb1e50a9932213ecece00a606661ae9ca44f3397 # 2.2.0
 
       - name: Publish Helm Chart
         if: ${{ !inputs.dry_run }}
@@ -689,10 +752,12 @@ jobs:
           cp "build/provisioner_helm_${version}.tgz" build/helm
           gsutil cp gs://helm.coder.com/v2/index.yaml build/helm/index.yaml
           helm repo index build/helm --url https://helm.coder.com/v2 --merge build/helm/index.yaml
-          gsutil -h "Cache-Control:no-cache,max-age=0" cp build/helm/coder_helm_${version}.tgz gs://helm.coder.com/v2
-          gsutil -h "Cache-Control:no-cache,max-age=0" cp build/helm/provisioner_helm_${version}.tgz gs://helm.coder.com/v2
-          gsutil -h "Cache-Control:no-cache,max-age=0" cp build/helm/index.yaml gs://helm.coder.com/v2
-          gsutil -h "Cache-Control:no-cache,max-age=0" cp helm/artifacthub-repo.yml gs://helm.coder.com/v2
+          gsutil -h "Cache-Control:no-cache,max-age=0" cp "build/helm/coder_helm_${version}.tgz" gs://helm.coder.com/v2
+          gsutil -h "Cache-Control:no-cache,max-age=0" cp "build/helm/provisioner_helm_${version}.tgz" gs://helm.coder.com/v2
+          gsutil -h "Cache-Control:no-cache,max-age=0" cp "build/helm/index.yaml" gs://helm.coder.com/v2
+          gsutil -h "Cache-Control:no-cache,max-age=0" cp "helm/artifacthub-repo.yml" gs://helm.coder.com/v2
+          helm push "build/coder_helm_${version}.tgz" oci://ghcr.io/coder/chart
+          helm push "build/provisioner_helm_${version}.tgz" oci://ghcr.io/coder/chart
 
       - name: Upload artifacts to actions (if dry-run)
         if: ${{ inputs.dry_run }}
@@ -737,18 +802,18 @@ jobs:
       # TODO: skip this if it's not a new release (i.e. a backport). This is
       #       fine right now because it just makes a PR that we can close.
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
         with:
           egress-policy: audit
 
       - name: Update homebrew
         env:
-          # Variables used by the `gh` command
           GH_REPO: coder/homebrew-coder
           GH_TOKEN: ${{ secrets.CDRCI_GITHUB_TOKEN }}
+          VERSION: ${{ needs.release.outputs.version }}
         run: |
           # Keep version number around for reference, removing any potential leading v
-          coder_version="$(echo "${{ needs.release.outputs.version }}" | tr -d v)"
+          coder_version="$(echo "${VERSION}" | tr -d v)"
 
           set -euxo pipefail
 
@@ -767,9 +832,9 @@ jobs:
           wget "$checksums_url" -O checksums.txt
 
           # Get the SHAs
-          darwin_arm_sha="$(cat checksums.txt | grep "darwin_arm64.zip" | awk '{ print $1 }')"
-          darwin_intel_sha="$(cat checksums.txt | grep "darwin_amd64.zip" | awk '{ print $1 }')"
-          linux_sha="$(cat checksums.txt | grep "linux_amd64.tar.gz" | awk '{ print $1 }')"
+          darwin_arm_sha="$(grep "darwin_arm64.zip" checksums.txt | awk '{ print $1 }')"
+          darwin_intel_sha="$(grep "darwin_amd64.zip" checksums.txt | awk '{ print $1 }')"
+          linux_sha="$(grep "linux_amd64.tar.gz" checksums.txt | awk '{ print $1 }')"
 
           echo "macOS arm64: $darwin_arm_sha"
           echo "macOS amd64: $darwin_intel_sha"
@@ -782,7 +847,7 @@ jobs:
 
           # Check if a PR already exists.
           pr_count="$(gh pr list --search "head:$brew_branch" --json id,closed | jq -r ".[] | select(.closed == false) | .id" | wc -l)"
-          if [[ "$pr_count" > 0 ]]; then
+          if [ "$pr_count" -gt 0 ]; then
             echo "Bailing out as PR already exists" 2>&1
             exit 0
           fi
@@ -801,8 +866,8 @@ jobs:
             -B master -H "$brew_branch" \
             -t "coder $coder_version" \
             -b "" \
-            -r "${{ github.actor }}" \
-            -a "${{ github.actor }}" \
+            -r "${GITHUB_ACTOR}" \
+            -a "${GITHUB_ACTOR}" \
             -b "This automatic PR was triggered by the release of Coder v$coder_version"
 
   publish-winget:
@@ -813,7 +878,7 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
         with:
           egress-policy: audit
 
@@ -823,9 +888,10 @@ jobs:
           GH_TOKEN: ${{ secrets.CDRCI_GITHUB_TOKEN }}
 
       - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
         with:
           fetch-depth: 0
+          persist-credentials: false
 
       # If the event that triggered the build was an annotated tag (which our
       # tags are supposed to be), actions/checkout has a bug where the tag in
@@ -844,7 +910,7 @@ jobs:
           # The package version is the same as the tag minus the leading "v".
           # The version in this output already has the leading "v" removed but
           # we do it again to be safe.
-          $version = "${{ needs.release.outputs.version }}".Trim('v')
+          $version = $env:VERSION.Trim('v')
 
           $release_assets = gh release view --repo coder/coder "v${version}" --json assets | `
             ConvertFrom-Json
@@ -876,13 +942,14 @@ jobs:
           # For wingetcreate. We need a real token since we're pushing a commit
           # to GitHub and then making a PR in a different repo.
           WINGET_GH_TOKEN: ${{ secrets.CDRCI_GITHUB_TOKEN }}
+          VERSION: ${{ needs.release.outputs.version }}
 
       - name: Comment on PR
         run: |
           # wait 30 seconds
           Start-Sleep -Seconds 30.0
           # Find the PR that wingetcreate just made.
-          $version = "${{ needs.release.outputs.version }}".Trim('v')
+          $version = $env:VERSION.Trim('v')
           $pr_list = gh pr list --repo microsoft/winget-pkgs --search "author:cdrci Coder.Coder version ${version}" --limit 1 --json number | `
             ConvertFrom-Json
           $pr_number = $pr_list[0].number
@@ -893,6 +960,7 @@ jobs:
           # For gh CLI. We need a real token since we're commenting on a PR in a
           # different repo.
           GH_TOKEN: ${{ secrets.CDRCI_GITHUB_TOKEN }}
+          VERSION: ${{ needs.release.outputs.version }}
 
   # publish-sqlc pushes the latest schema to sqlc cloud.
   # At present these pushes cannot be tagged, so the last push is always the latest.
@@ -903,14 +971,15 @@ jobs:
     if: ${{ !inputs.dry_run }}
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
         with:
           fetch-depth: 1
+          persist-credentials: false
 
       # We need golang to run the migration main.go
       - name: Setup Go

.github/workflows/scorecard.yml

@@ -20,12 +20,12 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
         with:
           egress-policy: audit
 
       - name: "Checkout code"
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
         with:
           persist-credentials: false
 
@@ -47,6 +47,6 @@ jobs:
 
       # Upload the results to GitHub's code scanning dashboard.
       - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@ce28f5bb42b7a9f2c824e633a3f6ee835bab6858 # v3.29.0
+        uses: github/codeql-action/upload-sarif@76621b61decf072c1cee8dd1ce2d2a82d33c17ed # v3.29.5
         with:
           sarif_file: results.sarif

.github/workflows/security.yaml

@@ -27,18 +27,20 @@ jobs:
     runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-8' || 'ubuntu-latest' }}
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          persist-credentials: false
 
       - name: Setup Go
         uses: ./.github/actions/setup-go
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@ce28f5bb42b7a9f2c824e633a3f6ee835bab6858 # v3.29.0
+        uses: github/codeql-action/init@76621b61decf072c1cee8dd1ce2d2a82d33c17ed # v3.29.5
         with:
           languages: go, javascript
 
@@ -48,7 +50,7 @@ jobs:
           rm Makefile
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@ce28f5bb42b7a9f2c824e633a3f6ee835bab6858 # v3.29.0
+        uses: github/codeql-action/analyze@76621b61decf072c1cee8dd1ce2d2a82d33c17ed # v3.29.5
 
       - name: Send Slack notification on failure
         if: ${{ failure() }}
@@ -67,14 +69,15 @@ jobs:
     runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-8' || 'ubuntu-latest' }}
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
         with:
           fetch-depth: 0
+          persist-credentials: false
 
       - name: Setup Go
         uses: ./.github/actions/setup-go
@@ -134,15 +137,16 @@ jobs:
           # This environment variables forces scripts/build_docker.sh to build
           # the base image tag locally instead of using the cached version from
           # the registry.
-          export CODER_IMAGE_BUILD_BASE_TAG="$(CODER_IMAGE_BASE=coder-base ./scripts/image_tag.sh --version "$version")"
+          CODER_IMAGE_BUILD_BASE_TAG="$(CODER_IMAGE_BASE=coder-base ./scripts/image_tag.sh --version "$version")"
+          export CODER_IMAGE_BUILD_BASE_TAG
 
           # We would like to use make -j here, but it doesn't work with the some recent additions
           # to our code generation.
           make "$image_job"
-          echo "image=$(cat "$image_job")" >> $GITHUB_OUTPUT
+          echo "image=$(cat "$image_job")" >> "$GITHUB_OUTPUT"
 
       - name: Run Trivy vulnerability scanner
-        uses: aquasecurity/trivy-action@76071ef0d7ec797419534a183b498b4d6366cf37
+        uses: aquasecurity/trivy-action@dc5a429b52fcf669ce959baa2c2dd26090d2a6c4
         with:
           image-ref: ${{ steps.build.outputs.image }}
           format: sarif
@@ -150,7 +154,7 @@ jobs:
           severity: "CRITICAL,HIGH"
 
       - name: Upload Trivy scan results to GitHub Security tab
-        uses: github/codeql-action/upload-sarif@ce28f5bb42b7a9f2c824e633a3f6ee835bab6858 # v3.29.0
+        uses: github/codeql-action/upload-sarif@76621b61decf072c1cee8dd1ce2d2a82d33c17ed # v3.29.5
         with:
           sarif_file: trivy-results.sarif
           category: "Trivy"

.github/workflows/stale.yaml

@@ -18,7 +18,7 @@ jobs:
       pull-requests: write
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
         with:
           egress-policy: audit
 
@@ -96,12 +96,14 @@ jobs:
       contents: write
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
         with:
           egress-policy: audit
 
       - name: Checkout repository
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          persist-credentials: false
       - name: Run delete-old-branches-action
         uses: beatlabs/delete-old-branches-action@4eeeb8740ff8b3cb310296ddd6b43c3387734588 # v0.0.11
         with:
@@ -118,7 +120,7 @@ jobs:
       actions: write
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
         with:
           egress-policy: audit
 

.github/workflows/start-workspace.yaml

@@ -19,7 +19,7 @@ jobs:
     timeout-minutes: 5
     steps:
       - name: Start Coder workspace
-        uses: coder/start-workspace-action@35a4608cefc7e8cc56573cae7c3b85304575cb72
+        uses: coder/start-workspace-action@f97a681b4cc7985c9eef9963750c7cc6ebc93a19
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           github-username: >-

.github/workflows/typos.toml

@@ -28,6 +28,7 @@ HELO = "HELO"
 LKE = "LKE"
 byt = "byt"
 typ = "typ"
+Inferrable = "Inferrable"
 
 [files]
 extend-exclude = [
@@ -47,5 +48,5 @@ extend-exclude = [
 	"provisioner/terraform/testdata/**",
 	# notifications' golden files confuse the detector because of quoted-printable encoding
 	"coderd/notifications/testdata/**",
-	"agent/agentcontainers/testdata/devcontainercli/**"
+	"agent/agentcontainers/testdata/devcontainercli/**",
 ]

.github/workflows/weekly-docs.yaml

@@ -21,15 +21,17 @@ jobs:
       pull-requests: write # required to post PR review comments by the action
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          persist-credentials: false
 
       - name: Check Markdown links
-        uses: umbrelladocs/action-linkspector@e2ccef58c4b9eb89cd71ee23a8629744bba75aa6 # v1.3.5
+        uses: umbrelladocs/action-linkspector@874d01cae9fd488e3077b08952093235bd626977 # v1.3.7
         id: markdown-link-check
         # checks all markdown files from /docs including all subfolders
         with:
@@ -41,7 +43,10 @@ jobs:
       - name: Send Slack notification
         if: failure() && github.event_name == 'schedule'
         run: |
-          curl -X POST -H 'Content-type: application/json' -d '{"msg":"Broken links found in the documentation. Please check the logs at ${{ env.LOGS_URL }}"}' ${{ secrets.DOCS_LINK_SLACK_WEBHOOK }}
+          curl \
+            -X POST \
+            -H 'Content-type: application/json' \
+            -d '{"msg":"Broken links found in the documentation. Please check the logs at '"${LOGS_URL}"'"}' "${{ secrets.DOCS_LINK_SLACK_WEBHOOK }}"
           echo "Sent Slack notification"
         env:
           LOGS_URL: https://github.com/coder/coder/actions/runs/${{ github.run_id }}

.golangci.yaml

@@ -181,7 +181,6 @@ linters-settings:
 
 issues:
   exclude-dirs:
-    - coderd/database/dbmem
     - node_modules
     - .git
 

.mcp.json

@@ -0,0 +1,36 @@
+{
+  "mcpServers": {
+    "go-language-server": {
+      "type": "stdio",
+      "command": "go",
+      "args": [
+        "run",
+        "github.com/isaacphi/mcp-language-server@latest",
+        "-workspace",
+        "./",
+        "-lsp",
+        "go",
+        "--",
+        "run",
+        "golang.org/x/tools/gopls@latest"
+      ],
+      "env": {}
+    },
+    "typescript-language-server": {
+      "type": "stdio",
+      "command": "go",
+      "args": [
+        "run",
+        "github.com/isaacphi/mcp-language-server@latest",
+        "-workspace",
+        "./site/",
+        "-lsp",
+        "pnpx",
+        "--",
+        "typescript-language-server",
+        "--stdio"
+      ],
+      "env": {}
+    }
+  }
+}

.vscode/settings.json

@@ -49,7 +49,7 @@
 	"[javascript][javascriptreact][json][jsonc][typescript][typescriptreact]": {
 		"editor.defaultFormatter": "biomejs.biome",
 		"editor.codeActionsOnSave": {
-			"quickfix.biome": "explicit"
+			"source.fixAll.biome": "explicit"
 			//   "source.organizeImports.biome": "explicit"
 		}
 	},

AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

CLAUDE.md

@@ -1,21 +1,25 @@
 # Coder Development Guidelines
 
-Read [cursor rules](.cursorrules).
+@.claude/docs/WORKFLOWS.md
+@.cursorrules
+@README.md
+@package.json
 
-## Build/Test/Lint Commands
+## 🚀 Essential Commands
 
-### Main Commands
-
-- `make build` or `make build-fat` - Build all "fat" binaries (includes "server" functionality)
-- `make build-slim` - Build "slim" binaries
-- `make test` - Run Go tests
-- `make test RUN=TestFunctionName` or `go test -v ./path/to/package -run TestFunctionName` - Test single
-- `make test-postgres` - Run tests with Postgres database
-- `make test-race` - Run tests with Go race detector
-- `make test-e2e` - Run end-to-end tests
-- `make lint` - Run all linters
-- `make fmt` - Format all code
-- `make gen` - Generates mocks, database queries and other auto-generated files
+| Task              | Command                  | Notes                            |
+|-------------------|--------------------------|----------------------------------|
+| **Development**   | `./scripts/develop.sh`   | ⚠️ Don't use manual build        |
+| **Build**         | `make build`             | Fat binaries (includes server)   |
+| **Build Slim**    | `make build-slim`        | Slim binaries                    |
+| **Test**          | `make test`              | Full test suite                  |
+| **Test Single**   | `make test RUN=TestName` | Faster than full suite           |
+| **Test Postgres** | `make test-postgres`     | Run tests with Postgres database |
+| **Test Race**     | `make test-race`         | Run tests with Go race detector  |
+| **Lint**          | `make lint`              | Always run after changes         |
+| **Generate**      | `make gen`               | After database changes           |
+| **Format**        | `make fmt`               | Auto-format code                 |
+| **Clean**         | `make clean`             | Clean build artifacts            |
 
 ### Frontend Commands (site directory)
 
@@ -26,81 +30,109 @@ Read [cursor rules](.cursorrules).
 - `pnpm lint` - Lint frontend code
 - `pnpm test` - Run frontend tests
 
-## Code Style Guidelines
+### Documentation Commands
 
-### Go
+- `pnpm run format-docs` - Format markdown tables in docs
+- `pnpm run lint-docs` - Lint and fix markdown files
+- `pnpm run storybook` - Run Storybook (from site directory)
 
-- Follow [Effective Go](https://go.dev/doc/effective_go) and [Go's Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments)
-- Use `gofumpt` for formatting
-- Create packages when used during implementation
-- Validate abstractions against implementations
+## 🔧 Critical Patterns
 
-### Error Handling
+### Database Changes (ALWAYS FOLLOW)
 
-- Use descriptive error messages
-- Wrap errors with context
-- Propagate errors appropriately
-- Use proper error types
-- (`xerrors.Errorf("failed to X: %w", err)`)
+1. Modify `coderd/database/queries/*.sql` files
+2. Run `make gen`
+3. If audit errors: update `enterprise/audit/table.go`
+4. Run `make gen` again
 
-### Naming
+### LSP Navigation (USE FIRST)
 
-- Use clear, descriptive names
-- Abbreviate only when obvious
-- Follow Go and TypeScript naming conventions
+#### Go LSP (for backend code)
 
-### Comments
+- **Find definitions**: `mcp__go-language-server__definition symbolName`
+- **Find references**: `mcp__go-language-server__references symbolName`
+- **Get type info**: `mcp__go-language-server__hover filePath line column`
+- **Rename symbol**: `mcp__go-language-server__rename_symbol filePath line column newName`
 
-- Document exported functions, types, and non-obvious logic
-- Follow JSDoc format for TypeScript
-- Use godoc format for Go code
+#### TypeScript LSP (for frontend code in site/)
 
-## Commit Style
+- **Find definitions**: `mcp__typescript-language-server__definition symbolName`
+- **Find references**: `mcp__typescript-language-server__references symbolName`
+- **Get type info**: `mcp__typescript-language-server__hover filePath line column`
+- **Rename symbol**: `mcp__typescript-language-server__rename_symbol filePath line column newName`
 
-- Follow [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)
-- Format: `type(scope): message`
-- Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
-- Keep message titles concise (~70 characters)
-- Use imperative, present tense in commit titles
+### OAuth2 Error Handling
 
-## Database queries
+```go
+// OAuth2-compliant error responses
+writeOAuth2Error(ctx, rw, http.StatusBadRequest, "invalid_grant", "description")
+```
 
-- MUST DO! Any changes to database - adding queries, modifying queries should be done in the  `coderd\database\queries\*.sql` files. Use `make gen` to generate necessary changes after.
-- MUST DO! Queries are grouped in files relating to context - e.g. `prebuilds.sql`, `users.sql`, `provisionerjobs.sql`.
-- After making changes to any `coderd\database\queries\*.sql` files you must run `make gen` to generate respective ORM changes.
+### Authorization Context
 
-## Architecture
+```go
+// Public endpoints needing system access
+app, err := api.Database.GetOAuth2ProviderAppByClientID(dbauthz.AsSystemRestricted(ctx), clientID)
 
-### Core Components
+// Authenticated endpoints with user context
+app, err := api.Database.GetOAuth2ProviderAppByClientID(ctx, clientID)
+```
 
-- **coderd**: Main API service connecting workspaces, provisioners, and users
-- **provisionerd**: Execution context for infrastructure-modifying providers
-- **Agents**: Services in remote workspaces providing features like SSH and port forwarding
-- **Workspaces**: Cloud resources defined by Terraform
+## 📋 Quick Reference
 
-## Sub-modules
+### Full workflows available in imported WORKFLOWS.md
 
-### Template System
+### New Feature Checklist
 
-- Templates define infrastructure for workspaces using Terraform
-- Environment variables pass context between Coder and templates
-- Official modules extend development environments
+- [ ] Run `git pull` to ensure latest code
+- [ ] Check if feature touches database - you'll need migrations
+- [ ] Check if feature touches audit logs - update `enterprise/audit/table.go`
 
-### RBAC System
+## 🏗️ Architecture
 
-- Permissions defined at site, organization, and user levels
-- Object-Action model protects resources
-- Built-in roles: owner, member, auditor, templateAdmin
-- Permission format: `<sign>?<level>.<object>.<id>.<action>`
+- **coderd**: Main API service
+- **provisionerd**: Infrastructure provisioning
+- **Agents**: Workspace services (SSH, port forwarding)
+- **Database**: PostgreSQL with `dbauthz` authorization
 
-### Database
+## 🧪 Testing
 
-- PostgreSQL 13+ recommended for production
-- Migrations managed with `migrate`
-- Database authorization through `dbauthz` package
+### Race Condition Prevention
 
-## Frontend
+- Use unique identifiers: `fmt.Sprintf("test-client-%s-%d", t.Name(), time.Now().UnixNano())`
+- Never use hardcoded names in concurrent tests
 
-The frontend is contained in the site folder.
+### OAuth2 Testing
 
-For building Frontend refer to [this document](docs/about/contributing/frontend.md)
+- Full suite: `./scripts/oauth2/test-mcp-oauth2.sh`
+- Manual testing: `./scripts/oauth2/test-manual-flow.sh`
+
+### Timing Issues
+
+NEVER use `time.Sleep` to mitigate timing issues. If an issue
+seems like it should use `time.Sleep`, read through https://github.com/coder/quartz and specifically the [README](https://github.com/coder/quartz/blob/main/README.md) to better understand how to handle timing issues.
+
+## 🎯 Code Style
+
+### Detailed guidelines in imported WORKFLOWS.md
+
+- Follow [Uber Go Style Guide](https://github.com/uber-go/guide/blob/master/style.md)
+- Commit format: `type(scope): message`
+
+## 📚 Detailed Development Guides
+
+@.claude/docs/OAUTH2.md
+@.claude/docs/TESTING.md
+@.claude/docs/TROUBLESHOOTING.md
+@.claude/docs/DATABASE.md
+
+## 🚨 Common Pitfalls
+
+1. **Audit table errors** → Update `enterprise/audit/table.go`
+2. **OAuth2 errors** → Return RFC-compliant format
+3. **Race conditions** → Use unique test identifiers
+4. **Missing newlines** → Ensure files end with newline
+
+---
+
+*This file stays lean and actionable. Detailed workflows and explanations are imported automatically.*

CODEOWNERS

@@ -1,8 +1,41 @@
-# These APIs are versioned, so any changes need to be carefully reviewed for whether
-# to bump API major or minor versions.
+# These APIs are versioned, so any changes need to be carefully reviewed for
+# whether to bump API major or minor versions.
 agent/proto/ @spikecurtis @johnstcn
+provisionerd/proto/ @spikecurtis @johnstcn
+provisionersdk/proto/ @spikecurtis @johnstcn
 tailnet/proto/ @spikecurtis @johnstcn
 vpn/vpn.proto @spikecurtis @johnstcn
 vpn/version.go @spikecurtis @johnstcn
-provisionerd/proto/ @spikecurtis @johnstcn
-provisionersdk/proto/ @spikecurtis @johnstcn
+
+# This caching code is particularly tricky, and one must be very careful when
+# altering it.
+coderd/files/ @aslilac
+
+coderd/dynamicparameters/ @Emyrk
+coderd/rbac/ @Emyrk
+
+# Mainly dependent on coder/guts, which is maintained by @Emyrk
+scripts/apitypings/ @Emyrk
+scripts/gensite/ @aslilac
+
+site/ @aslilac @Parkreiner
+site/src/hooks/ @Parkreiner
+# These rules intentionally do not specify any owners. More specific rules
+# override less specific rules, so these files are "ignored" by the site/ rule.
+site/e2e/google/protobuf/timestampGenerated.ts
+site/e2e/provisionerGenerated.ts
+site/src/api/countriesGenerated.ts
+site/src/api/rbacresourcesGenerated.ts
+site/src/api/typesGenerated.ts
+site/src/testHelpers/entities.ts
+site/CLAUDE.md
+
+# The blood and guts of the autostop algorithm, which is quite complex and
+# requires elite ball knowledge of most of the scheduling code to make changes
+# without inadvertently affecting other parts of the codebase.
+coderd/schedule/autostop.go @deansheather @DanielleMaywood
+
+# Usage tracking code requires intimate knowledge of Tallyman and Metronome, as
+# well as guidance from revenue.
+coderd/usage/ @deansheather @spikecurtis
+enterprise/coderd/usage/ @deansheather @spikecurtis

Makefile

@@ -252,6 +252,10 @@ $(CODER_ALL_BINARIES): go.mod go.sum \
 		fi
 
 		cp "$@" "./site/out/bin/coder-$$os-$$arch$$dot_ext"
+
+		if [[ "$${CODER_SIGN_GPG:-0}" == "1" ]]; then
+			cp "$@.asc" "./site/out/bin/coder-$$os-$$arch$$dot_ext.asc"
+		fi
 	fi
 
 # This task builds Coder Desktop dylibs
@@ -456,16 +460,31 @@ fmt: fmt/ts fmt/go fmt/terraform fmt/shfmt fmt/biome fmt/markdown
 .PHONY: fmt
 
 fmt/go:
+ifdef FILE
+	# Format single file
+	if [[ -f "$(FILE)" ]] && [[ "$(FILE)" == *.go ]] && ! grep -q "DO NOT EDIT" "$(FILE)"; then \
+		echo "$(GREEN)==>$(RESET) $(BOLD)fmt/go$(RESET) $(FILE)"; \
+		go run mvdan.cc/gofumpt@v0.8.0 -w -l "$(FILE)"; \
+	fi
+else
 	go mod tidy
 	echo "$(GREEN)==>$(RESET) $(BOLD)fmt/go$(RESET)"
 	# VS Code users should check out
 	# https://github.com/mvdan/gofumpt#visual-studio-code
 	find . $(FIND_EXCLUSIONS) -type f -name '*.go' -print0 | \
-		xargs -0 grep --null -L "DO NOT EDIT" | \
-		xargs -0 go run mvdan.cc/gofumpt@v0.4.0 -w -l
+		xargs -0 grep -E --null -L '^// Code generated .* DO NOT EDIT\.$$' | \
+		xargs -0 go run mvdan.cc/gofumpt@v0.8.0 -w -l
+endif
 .PHONY: fmt/go
 
 fmt/ts: site/node_modules/.installed
+ifdef FILE
+	# Format single TypeScript/JavaScript file
+	if [[ -f "$(FILE)" ]] && [[ "$(FILE)" == *.ts ]] || [[ "$(FILE)" == *.tsx ]] || [[ "$(FILE)" == *.js ]] || [[ "$(FILE)" == *.jsx ]]; then \
+		echo "$(GREEN)==>$(RESET) $(BOLD)fmt/ts$(RESET) $(FILE)"; \
+		(cd site/ && pnpm exec biome format --write "../$(FILE)"); \
+	fi
+else
 	echo "$(GREEN)==>$(RESET) $(BOLD)fmt/ts$(RESET)"
 	cd site
 # Avoid writing files in CI to reduce file write activity
@@ -474,9 +493,17 @@ ifdef CI
 else
 	pnpm run check:fix
 endif
+endif
 .PHONY: fmt/ts
 
 fmt/biome: site/node_modules/.installed
+ifdef FILE
+	# Format single file with biome
+	if [[ -f "$(FILE)" ]] && [[ "$(FILE)" == *.ts ]] || [[ "$(FILE)" == *.tsx ]] || [[ "$(FILE)" == *.js ]] || [[ "$(FILE)" == *.jsx ]]; then \
+		echo "$(GREEN)==>$(RESET) $(BOLD)fmt/biome$(RESET) $(FILE)"; \
+		(cd site/ && pnpm exec biome format --write "../$(FILE)"); \
+	fi
+else
 	echo "$(GREEN)==>$(RESET) $(BOLD)fmt/biome$(RESET)"
 	cd site/
 # Avoid writing files in CI to reduce file write activity
@@ -485,14 +512,30 @@ ifdef CI
 else
 	pnpm run format
 endif
+endif
 .PHONY: fmt/biome
 
 fmt/terraform: $(wildcard *.tf)
+ifdef FILE
+	# Format single Terraform file
+	if [[ -f "$(FILE)" ]] && [[ "$(FILE)" == *.tf ]] || [[ "$(FILE)" == *.tfvars ]]; then \
+		echo "$(GREEN)==>$(RESET) $(BOLD)fmt/terraform$(RESET) $(FILE)"; \
+		terraform fmt "$(FILE)"; \
+	fi
+else
 	echo "$(GREEN)==>$(RESET) $(BOLD)fmt/terraform$(RESET)"
 	terraform fmt -recursive
+endif
 .PHONY: fmt/terraform
 
 fmt/shfmt: $(SHELL_SRC_FILES)
+ifdef FILE
+	# Format single shell script
+	if [[ -f "$(FILE)" ]] && [[ "$(FILE)" == *.sh ]]; then \
+		echo "$(GREEN)==>$(RESET) $(BOLD)fmt/shfmt$(RESET) $(FILE)"; \
+		shfmt -w "$(FILE)"; \
+	fi
+else
 	echo "$(GREEN)==>$(RESET) $(BOLD)fmt/shfmt$(RESET)"
 # Only do diff check in CI, errors on diff.
 ifdef CI
@@ -500,14 +543,25 @@ ifdef CI
 else
 	shfmt -w $(SHELL_SRC_FILES)
 endif
+endif
 .PHONY: fmt/shfmt
 
 fmt/markdown: node_modules/.installed
+ifdef FILE
+	# Format single markdown file
+	if [[ -f "$(FILE)" ]] && [[ "$(FILE)" == *.md ]]; then \
+		echo "$(GREEN)==>$(RESET) $(BOLD)fmt/markdown$(RESET) $(FILE)"; \
+		pnpm exec markdown-table-formatter "$(FILE)"; \
+	fi
+else
 	echo "$(GREEN)==>$(RESET) $(BOLD)fmt/markdown$(RESET)"
 	pnpm format-docs
+endif
 .PHONY: fmt/markdown
 
-lint: lint/shellcheck lint/go lint/ts lint/examples lint/helm lint/site-icons lint/markdown
+# Note: we don't run zizmor in the lint target because it takes a while. CI
+#       runs it explicitly.
+lint: lint/shellcheck lint/go lint/ts lint/examples lint/helm lint/site-icons lint/markdown lint/actions/actionlint
 .PHONY: lint
 
 lint/site-icons:
@@ -524,6 +578,7 @@ lint/go:
 	./scripts/check_codersdk_imports.sh
 	linter_ver=$(shell egrep -o 'GOLANGCI_LINT_VERSION=\S+' dogfood/coder/Dockerfile | cut -d '=' -f 2)
 	go run github.com/golangci/golangci-lint/cmd/golangci-lint@v$$linter_ver run
+	go run github.com/coder/paralleltestctx/cmd/paralleltestctx@v0.0.1 -custom-funcs="testutil.Context" ./...
 .PHONY: lint/go
 
 lint/examples:
@@ -545,13 +600,26 @@ lint/markdown: node_modules/.installed
 	pnpm lint-docs
 .PHONY: lint/markdown
 
+lint/actions: lint/actions/actionlint lint/actions/zizmor
+.PHONY: lint/actions
+
+lint/actions/actionlint:
+	go run github.com/rhysd/actionlint/cmd/actionlint@v1.7.7
+.PHONY: lint/actions/actionlint
+
+lint/actions/zizmor:
+	./scripts/zizmor.sh \
+		--strict-collection \
+		--persona=regular \
+		.
+.PHONY: lint/actions/zizmor
+
 # All files generated by the database should be added here, and this can be used
 # as a target for jobs that need to run after the database is generated.
 DB_GEN_FILES := \
 	coderd/database/dump.sql \
 	coderd/database/querier.go \
 	coderd/database/unique_constraint.go \
-	coderd/database/dbmem/dbmem.go \
 	coderd/database/dbmetrics/dbmetrics.go \
 	coderd/database/dbauthz/dbauthz.go \
 	coderd/database/dbmock/dbmock.go
@@ -584,7 +652,8 @@ GEN_FILES := \
 	coderd/database/pubsub/psmock/psmock.go \
 	agent/agentcontainers/acmock/acmock.go \
 	agent/agentcontainers/dcspec/dcspec_gen.go \
-	coderd/httpmw/loggermw/loggermock/loggermock.go
+	coderd/httpmw/loggermw/loggermock/loggermock.go \
+	codersdk/workspacesdk/agentconnmock/agentconnmock.go
 
 # all gen targets should be added here and to gen/mark-fresh
 gen: gen/db gen/golden-files $(GEN_FILES)
@@ -634,6 +703,7 @@ gen/mark-fresh:
 		agent/agentcontainers/acmock/acmock.go \
 		agent/agentcontainers/dcspec/dcspec_gen.go \
 		coderd/httpmw/loggermw/loggermock/loggermock.go \
+		codersdk/workspacesdk/agentconnmock/agentconnmock.go \
 		"
 
 	for file in $$files; do
@@ -677,6 +747,10 @@ coderd/httpmw/loggermw/loggermock/loggermock.go: coderd/httpmw/loggermw/logger.g
 	go generate ./coderd/httpmw/loggermw/loggermock/
 	touch "$@"
 
+codersdk/workspacesdk/agentconnmock/agentconnmock.go: codersdk/workspacesdk/agentconn.go
+	go generate ./codersdk/workspacesdk/agentconnmock/
+	touch "$@"
+
 agent/agentcontainers/dcspec/dcspec_gen.go: \
 	node_modules/.installed \
 	agent/agentcontainers/dcspec/devContainer.base.schema.json \
@@ -884,12 +958,31 @@ else
 GOTESTSUM_RETRY_FLAGS :=
 endif
 
+# default to 8x8 parallelism to avoid overwhelming our workspaces. Hopefully we can remove these defaults
+# when we get our test suite's resource utilization under control.
+GOTEST_FLAGS := -v -p $(or $(TEST_NUM_PARALLEL_PACKAGES),"8") -parallel=$(or $(TEST_NUM_PARALLEL_TESTS),"8")
+
+# The most common use is to set TEST_COUNT=1 to avoid Go's test cache.
+ifdef TEST_COUNT
+GOTEST_FLAGS += -count=$(TEST_COUNT)
+endif
+
+ifdef TEST_SHORT
+GOTEST_FLAGS += -short
+endif
+
+ifdef RUN
+GOTEST_FLAGS += -run $(RUN)
+endif
+
+TEST_PACKAGES ?= ./...
+
 test:
-	$(GIT_FLAGS) gotestsum --format standard-quiet $(GOTESTSUM_RETRY_FLAGS) --packages="./..." -- -v -short -count=1 $(if $(RUN),-run $(RUN))
+	$(GIT_FLAGS) gotestsum --format standard-quiet $(GOTESTSUM_RETRY_FLAGS) --packages="$(TEST_PACKAGES)" -- $(GOTEST_FLAGS)
 .PHONY: test
 
 test-cli:
-	$(GIT_FLAGS) gotestsum --format standard-quiet $(GOTESTSUM_RETRY_FLAGS) --packages="./cli/..." -- -v -short -count=1
+	$(MAKE) test TEST_PACKAGES="./cli..."
 .PHONY: test-cli
 
 # sqlc-cloud-is-setup will fail if no SQLc auth token is set. Use this as a
@@ -925,7 +1018,7 @@ sqlc-vet: test-postgres-docker
 test-postgres: test-postgres-docker
 	# The postgres test is prone to failure, so we limit parallelism for
 	# more consistent execution.
-	$(GIT_FLAGS)  DB=ci gotestsum \
+	$(GIT_FLAGS)  gotestsum \
 		--junitfile="gotests.xml" \
 		--jsonfile="gotests.json" \
 		$(GOTESTSUM_RETRY_FLAGS) \

agent/agent.go

@@ -91,13 +91,14 @@ type Options struct {
 	Execer                       agentexec.Execer
 	Devcontainers                bool
 	DevcontainerAPIOptions       []agentcontainers.Option // Enable Devcontainers for these to be effective.
+	Clock                        quartz.Clock
 }
 
 type Client interface {
 	ConnectRPC26(ctx context.Context) (
 		proto.DRPCAgentClient26, tailnetproto.DRPCTailnetClient26, error,
 	)
-	RewriteDERPMap(derpMap *tailcfg.DERPMap)
+	tailnet.DERPMapRewriter
 }
 
 type Agent interface {
@@ -144,6 +145,9 @@ func New(options Options) Agent {
 	if options.PortCacheDuration == 0 {
 		options.PortCacheDuration = 1 * time.Second
 	}
+	if options.Clock == nil {
+		options.Clock = quartz.NewReal()
+	}
 
 	prometheusRegistry := options.PrometheusRegistry
 	if prometheusRegistry == nil {
@@ -157,6 +161,7 @@ func New(options Options) Agent {
 	hardCtx, hardCancel := context.WithCancel(context.Background())
 	gracefulCtx, gracefulCancel := context.WithCancel(hardCtx)
 	a := &agent{
+		clock:                              options.Clock,
 		tailnetListenPort:                  options.TailnetListenPort,
 		reconnectingPTYTimeout:             options.ReconnectingPTYTimeout,
 		logger:                             options.Logger,
@@ -204,6 +209,7 @@ func New(options Options) Agent {
 }
 
 type agent struct {
+	clock             quartz.Clock
 	logger            slog.Logger
 	client            Client
 	exchangeToken     func(ctx context.Context) (string, error)
@@ -273,7 +279,7 @@ type agent struct {
 
 	devcontainers       bool
 	containerAPIOptions []agentcontainers.Option
-	containerAPI        atomic.Pointer[agentcontainers.API] // Set by apiHandler.
+	containerAPI        *agentcontainers.API
 }
 
 func (a *agent) TailnetConn() *tailnet.Conn {
@@ -330,6 +336,17 @@ func (a *agent) init() {
 	// will not report anywhere.
 	a.scriptRunner.RegisterMetrics(a.prometheusRegistry)
 
+	containerAPIOpts := []agentcontainers.Option{
+		agentcontainers.WithExecer(a.execer),
+		agentcontainers.WithCommandEnv(a.sshServer.CommandEnv),
+		agentcontainers.WithScriptLogger(func(logSourceID uuid.UUID) agentcontainers.ScriptLogger {
+			return a.logSender.GetScriptLogger(logSourceID)
+		}),
+	}
+	containerAPIOpts = append(containerAPIOpts, a.containerAPIOptions...)
+
+	a.containerAPI = agentcontainers.NewAPI(a.logger.Named("containers"), containerAPIOpts...)
+
 	a.reconnectingPTYServer = reconnectingpty.NewServer(
 		a.logger.Named("reconnecting-pty"),
 		a.sshServer,
@@ -546,7 +563,6 @@ func (a *agent) reportMetadata(ctx context.Context, aAPI proto.DRPCAgentClient26
 			// channel to synchronize the results and avoid both messy
 			// mutex logic and overloading the API.
 			for _, md := range manifest.Metadata {
-				md := md
 				// We send the result to the channel in the goroutine to avoid
 				// sending the same result multiple times. So, we don't care about
 				// the return values.
@@ -774,11 +790,15 @@ func (a *agent) reportConnectionsLoop(ctx context.Context, aAPI proto.DRPCAgentC
 			logger.Debug(ctx, "reporting connection")
 			_, err := aAPI.ReportConnection(ctx, payload)
 			if err != nil {
-				return xerrors.Errorf("failed to report connection: %w", err)
+				// Do not fail the loop if we fail to report a connection, just
+				// log a warning.
+				// Related to https://github.com/coder/coder/issues/20194
+				logger.Warn(ctx, "failed to report connection to server", slog.Error(err))
+				// no continue here, we still need to remove it from the slice
+			} else {
+				logger.Debug(ctx, "successfully reported connection")
 			}
 
-			logger.Debug(ctx, "successfully reported connection")
-
 			// Remove the payload we sent.
 			a.reportConnectionsMu.Lock()
 			a.reportConnections[0] = nil // Release the pointer from the underlying array.
@@ -809,6 +829,13 @@ func (a *agent) reportConnection(id uuid.UUID, connectionType proto.Connection_T
 		ip = host
 	}
 
+	// If the IP is "localhost" (which it can be in some cases), set it to
+	// 127.0.0.1 instead.
+	// Related to https://github.com/coder/coder/issues/20194
+	if ip == "localhost" {
+		ip = "127.0.0.1"
+	}
+
 	a.reportConnectionsMu.Lock()
 	defer a.reportConnectionsMu.Unlock()
 
@@ -1070,7 +1097,7 @@ func (a *agent) handleManifest(manifestOK *checkpoint) func(ctx context.Context,
 		if err != nil {
 			return xerrors.Errorf("fetch metadata: %w", err)
 		}
-		a.logger.Info(ctx, "fetched manifest", slog.F("manifest", mp))
+		a.logger.Info(ctx, "fetched manifest")
 		manifest, err := agentsdk.ManifestFromProto(mp)
 		if err != nil {
 			a.logger.Critical(ctx, "failed to convert manifest", slog.F("manifest", mp), slog.Error(err))
@@ -1141,17 +1168,27 @@ func (a *agent) handleManifest(manifestOK *checkpoint) func(ctx context.Context,
 			}
 
 			var (
-				scripts          = manifest.Scripts
-				scriptRunnerOpts []agentscripts.InitOption
+				scripts             = manifest.Scripts
+				devcontainerScripts map[uuid.UUID]codersdk.WorkspaceAgentScript
 			)
 			if a.devcontainers {
-				var dcScripts []codersdk.WorkspaceAgentScript
-				scripts, dcScripts = agentcontainers.ExtractAndInitializeDevcontainerScripts(manifest.Devcontainers, scripts)
-				// See ExtractAndInitializeDevcontainerScripts for motivation
-				// behind running dcScripts as post start scripts.
-				scriptRunnerOpts = append(scriptRunnerOpts, agentscripts.WithPostStartScripts(dcScripts...))
+				// Init the container API with the manifest and client so that
+				// we can start accepting requests. The final start of the API
+				// happens after the startup scripts have been executed to
+				// ensure the presence of required tools. This means we can
+				// return existing devcontainers but actual container detection
+				// and creation will be deferred.
+				a.containerAPI.Init(
+					agentcontainers.WithManifestInfo(manifest.OwnerName, manifest.WorkspaceName, manifest.AgentName, manifest.Directory),
+					agentcontainers.WithDevcontainers(manifest.Devcontainers, manifest.Scripts),
+					agentcontainers.WithSubAgentClient(agentcontainers.NewSubAgentClientFromAPI(a.logger, aAPI)),
+				)
+
+				// Since devcontainer are enabled, remove devcontainer scripts
+				// from the main scripts list to avoid showing an error.
+				scripts, devcontainerScripts = agentcontainers.ExtractDevcontainerScripts(manifest.Devcontainers, scripts)
 			}
-			err = a.scriptRunner.Init(scripts, aAPI.ScriptCompleted, scriptRunnerOpts...)
+			err = a.scriptRunner.Init(scripts, aAPI.ScriptCompleted)
 			if err != nil {
 				return xerrors.Errorf("init script runner: %w", err)
 			}
@@ -1168,7 +1205,18 @@ func (a *agent) handleManifest(manifestOK *checkpoint) func(ctx context.Context,
 				// finished (both start and post start). For instance, an
 				// autostarted devcontainer will be included in this time.
 				err := a.scriptRunner.Execute(a.gracefulCtx, agentscripts.ExecuteStartScripts)
-				err = errors.Join(err, a.scriptRunner.Execute(a.gracefulCtx, agentscripts.ExecutePostStartScripts))
+
+				if a.devcontainers {
+					// Start the container API after the startup scripts have
+					// been executed to ensure that the required tools can be
+					// installed.
+					a.containerAPI.Start()
+					for _, dc := range manifest.Devcontainers {
+						cErr := a.createDevcontainer(ctx, aAPI, dc, devcontainerScripts[dc.ID])
+						err = errors.Join(err, cErr)
+					}
+				}
+
 				dur := time.Since(start).Seconds()
 				if err != nil {
 					a.logger.Warn(ctx, "startup script(s) failed", slog.Error(err))
@@ -1187,14 +1235,6 @@ func (a *agent) handleManifest(manifestOK *checkpoint) func(ctx context.Context,
 				}
 				a.metrics.startupScriptSeconds.WithLabelValues(label).Set(dur)
 				a.scriptRunner.StartCron()
-
-				// If the container API is enabled, trigger an immediate refresh
-				// for quick sub agent injection.
-				if cAPI := a.containerAPI.Load(); cAPI != nil {
-					if err := cAPI.RefreshContainers(ctx); err != nil {
-						a.logger.Error(ctx, "failed to refresh containers", slog.Error(err))
-					}
-				}
 			})
 			if err != nil {
 				return xerrors.Errorf("track conn goroutine: %w", err)
@@ -1204,6 +1244,38 @@ func (a *agent) handleManifest(manifestOK *checkpoint) func(ctx context.Context,
 	}
 }
 
+func (a *agent) createDevcontainer(
+	ctx context.Context,
+	aAPI proto.DRPCAgentClient26,
+	dc codersdk.WorkspaceAgentDevcontainer,
+	script codersdk.WorkspaceAgentScript,
+) (err error) {
+	var (
+		exitCode  = int32(0)
+		startTime = a.clock.Now()
+		status    = proto.Timing_OK
+	)
+	if err = a.containerAPI.CreateDevcontainer(dc.WorkspaceFolder, dc.ConfigPath); err != nil {
+		exitCode = 1
+		status = proto.Timing_EXIT_FAILURE
+	}
+	endTime := a.clock.Now()
+
+	if _, scriptErr := aAPI.ScriptCompleted(ctx, &proto.WorkspaceAgentScriptCompletedRequest{
+		Timing: &proto.Timing{
+			ScriptId: script.ID[:],
+			Start:    timestamppb.New(startTime),
+			End:      timestamppb.New(endTime),
+			ExitCode: exitCode,
+			Stage:    proto.Timing_START,
+			Status:   status,
+		},
+	}); scriptErr != nil {
+		a.logger.Warn(ctx, "reporting script completed failed", slog.Error(scriptErr))
+	}
+	return err
+}
+
 // createOrUpdateNetwork waits for the manifest to be set using manifestOK, then creates or updates
 // the tailnet using the information in the manifest
 func (a *agent) createOrUpdateNetwork(manifestOK, networkOK *checkpoint) func(context.Context, proto.DRPCAgentClient26) error {
@@ -1227,7 +1299,6 @@ func (a *agent) createOrUpdateNetwork(manifestOK, networkOK *checkpoint) func(co
 			// agent API.
 			network, err = a.createTailnet(
 				a.gracefulCtx,
-				aAPI,
 				manifest.AgentID,
 				manifest.DERPMap,
 				manifest.DERPForceWebSockets,
@@ -1262,9 +1333,9 @@ func (a *agent) createOrUpdateNetwork(manifestOK, networkOK *checkpoint) func(co
 			network.SetBlockEndpoints(manifest.DisableDirectConnections)
 
 			// Update the subagent client if the container API is available.
-			if cAPI := a.containerAPI.Load(); cAPI != nil {
+			if a.containerAPI != nil {
 				client := agentcontainers.NewSubAgentClientFromAPI(a.logger, aAPI)
-				cAPI.UpdateSubAgentClient(client)
+				a.containerAPI.UpdateSubAgentClient(client)
 			}
 		}
 		return nil
@@ -1382,7 +1453,6 @@ func (a *agent) trackGoroutine(fn func()) error {
 
 func (a *agent) createTailnet(
 	ctx context.Context,
-	aAPI proto.DRPCAgentClient26,
 	agentID uuid.UUID,
 	derpMap *tailcfg.DERPMap,
 	derpForceWebSockets, disableDirectConnections bool,
@@ -1515,10 +1585,7 @@ func (a *agent) createTailnet(
 	}()
 	if err = a.trackGoroutine(func() {
 		defer apiListener.Close()
-		apiHandler, closeAPIHAndler := a.apiHandler(aAPI)
-		defer func() {
-			_ = closeAPIHAndler()
-		}()
+		apiHandler := a.apiHandler()
 		server := &http.Server{
 			BaseContext:       func(net.Listener) context.Context { return ctx },
 			Handler:           apiHandler,
@@ -1532,7 +1599,6 @@ func (a *agent) createTailnet(
 			case <-ctx.Done():
 			case <-a.hardCtx.Done():
 			}
-			_ = closeAPIHAndler()
 			_ = server.Close()
 		}()
 
@@ -1871,6 +1937,10 @@ func (a *agent) Close() error {
 		a.logger.Error(a.hardCtx, "script runner close", slog.Error(err))
 	}
 
+	if err := a.containerAPI.Close(); err != nil {
+		a.logger.Error(a.hardCtx, "container API close", slog.Error(err))
+	}
+
 	// Wait for the graceful shutdown to complete, but don't wait forever so
 	// that we don't break user expectations.
 	go func() {

agent/agent_test.go

@@ -456,8 +456,6 @@ func TestAgent_GitSSH(t *testing.T) {
 
 func TestAgent_SessionTTYShell(t *testing.T) {
 	t.Parallel()
-	ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
-	t.Cleanup(cancel)
 	if runtime.GOOS == "windows" {
 		// This might be our implementation, or ConPTY itself.
 		// It's difficult to find extensive tests for it, so
@@ -468,6 +466,7 @@ func TestAgent_SessionTTYShell(t *testing.T) {
 	for _, port := range sshPorts {
 		t.Run(fmt.Sprintf("(%d)", port), func(t *testing.T) {
 			t.Parallel()
+			ctx := testutil.Context(t, testutil.WaitShort)
 
 			session := setupSSHSessionOnPort(t, agentsdk.Manifest{}, codersdk.ServiceBannerConfig{}, nil, port)
 			command := "sh"
@@ -2130,7 +2129,7 @@ func TestAgent_DevcontainerAutostart(t *testing.T) {
 		"name": "mywork",
 		"image": "ubuntu:latest",
 		"cmd": ["sleep", "infinity"],
-		"runArgs": ["--network=host"]
+		"runArgs": ["--network=host", "--label=`+agentcontainers.DevcontainerIsTestRunLabel+`=true"]
     }`), 0o600)
 	require.NoError(t, err, "write devcontainer.json")
 
@@ -2167,6 +2166,7 @@ func TestAgent_DevcontainerAutostart(t *testing.T) {
 			// Only match this specific dev container.
 			agentcontainers.WithClock(mClock),
 			agentcontainers.WithContainerLabelIncludeFilter("devcontainer.local_folder", tempWorkspaceFolder),
+			agentcontainers.WithContainerLabelIncludeFilter(agentcontainers.DevcontainerIsTestRunLabel, "true"),
 			agentcontainers.WithSubAgentURL(srv.URL),
 			// The agent will copy "itself", but in the case of this test, the
 			// agent is actually this test binary. So we'll tell the test binary
@@ -2288,7 +2288,8 @@ func TestAgent_DevcontainerRecreate(t *testing.T) {
 	err = os.WriteFile(devcontainerFile, []byte(`{
         "name": "mywork",
         "image": "busybox:latest",
-        "cmd": ["sleep", "infinity"]
+        "cmd": ["sleep", "infinity"],
+		"runArgs": ["--label=`+agentcontainers.DevcontainerIsTestRunLabel+`=true"]
     }`), 0o600)
 	require.NoError(t, err, "write devcontainer.json")
 
@@ -2315,6 +2316,7 @@ func TestAgent_DevcontainerRecreate(t *testing.T) {
 		o.Devcontainers = true
 		o.DevcontainerAPIOptions = append(o.DevcontainerAPIOptions,
 			agentcontainers.WithContainerLabelIncludeFilter("devcontainer.local_folder", workspaceFolder),
+			agentcontainers.WithContainerLabelIncludeFilter(agentcontainers.DevcontainerIsTestRunLabel, "true"),
 		)
 	})
 
@@ -2369,7 +2371,7 @@ func TestAgent_DevcontainerRecreate(t *testing.T) {
 	// devcontainer, we do it in a goroutine so we can process logs
 	// concurrently.
 	go func(container codersdk.WorkspaceAgentContainer) {
-		_, err := conn.RecreateDevcontainer(ctx, container.ID)
+		_, err := conn.RecreateDevcontainer(ctx, devcontainerID.String())
 		assert.NoError(t, err, "recreate devcontainer should succeed")
 	}(container)
 
@@ -2438,7 +2440,8 @@ func TestAgent_DevcontainersDisabledForSubAgent(t *testing.T) {
 
 	// Setup the agent with devcontainers enabled initially.
 	//nolint:dogsled
-	conn, _, _, _, _ := setupAgent(t, manifest, 0, func(*agenttest.Client, *agent.Options) {
+	conn, _, _, _, _ := setupAgent(t, manifest, 0, func(_ *agenttest.Client, o *agent.Options) {
+		o.Devcontainers = true
 	})
 
 	// Query the containers API endpoint. This should fail because
@@ -2450,8 +2453,214 @@ func TestAgent_DevcontainersDisabledForSubAgent(t *testing.T) {
 	require.Error(t, err)
 
 	// Verify the error message contains the expected text.
-	require.Contains(t, err.Error(), "The agent dev containers feature is experimental and not enabled by default.")
-	require.Contains(t, err.Error(), "To enable this feature, set CODER_AGENT_DEVCONTAINERS_ENABLE=true in your template.")
+	require.Contains(t, err.Error(), "Dev Container feature not supported.")
+	require.Contains(t, err.Error(), "Dev Container integration inside other Dev Containers is explicitly not supported.")
+}
+
+// TestAgent_DevcontainerPrebuildClaim tests that we correctly handle
+// the claiming process for running devcontainers.
+//
+// You can run it manually as follows:
+//
+// CODER_TEST_USE_DOCKER=1 go test -count=1 ./agent -run TestAgent_DevcontainerPrebuildClaim
+//
+//nolint:paralleltest // This test sets an environment variable.
+func TestAgent_DevcontainerPrebuildClaim(t *testing.T) {
+	if os.Getenv("CODER_TEST_USE_DOCKER") != "1" {
+		t.Skip("Set CODER_TEST_USE_DOCKER=1 to run this test")
+	}
+	if _, err := exec.LookPath("devcontainer"); err != nil {
+		t.Skip("This test requires the devcontainer CLI: npm install -g @devcontainers/cli")
+	}
+
+	pool, err := dockertest.NewPool("")
+	require.NoError(t, err, "Could not connect to docker")
+
+	var (
+		ctx = testutil.Context(t, testutil.WaitShort)
+
+		devcontainerID          = uuid.New()
+		devcontainerLogSourceID = uuid.New()
+
+		workspaceFolder    = filepath.Join(t.TempDir(), "project")
+		devcontainerPath   = filepath.Join(workspaceFolder, ".devcontainer")
+		devcontainerConfig = filepath.Join(devcontainerPath, "devcontainer.json")
+	)
+
+	// Given: A devcontainer project.
+	t.Logf("Workspace folder: %s", workspaceFolder)
+
+	err = os.MkdirAll(devcontainerPath, 0o755)
+	require.NoError(t, err, "create dev container directory")
+
+	// Given: This devcontainer project specifies an app that uses the owner name and workspace name.
+	err = os.WriteFile(devcontainerConfig, []byte(`{
+	    "name": "project",
+		"image": "busybox:latest",
+	    "cmd": ["sleep", "infinity"],
+		"runArgs": ["--label=`+agentcontainers.DevcontainerIsTestRunLabel+`=true"],
+		"customizations": {
+		 	"coder": {
+				"apps": [{
+					"slug": "zed",
+					"url": "zed://ssh/${localEnv:CODER_WORKSPACE_AGENT_NAME}.${localEnv:CODER_WORKSPACE_NAME}.${localEnv:CODER_WORKSPACE_OWNER_NAME}.coder${containerWorkspaceFolder}"
+				}]
+			}
+		}
+	}`), 0o600)
+	require.NoError(t, err, "write devcontainer config")
+
+	// Given: A manifest with a prebuild username and workspace name.
+	manifest := agentsdk.Manifest{
+		OwnerName:     "prebuilds",
+		WorkspaceName: "prebuilds-xyz-123",
+
+		Devcontainers: []codersdk.WorkspaceAgentDevcontainer{
+			{ID: devcontainerID, Name: "test", WorkspaceFolder: workspaceFolder},
+		},
+		Scripts: []codersdk.WorkspaceAgentScript{
+			{ID: devcontainerID, LogSourceID: devcontainerLogSourceID},
+		},
+	}
+
+	// When: We create an agent with devcontainers enabled.
+	//nolint:dogsled
+	conn, client, _, _, _ := setupAgent(t, manifest, 0, func(_ *agenttest.Client, o *agent.Options) {
+		o.Devcontainers = true
+		o.DevcontainerAPIOptions = append(o.DevcontainerAPIOptions,
+			agentcontainers.WithContainerLabelIncludeFilter(agentcontainers.DevcontainerLocalFolderLabel, workspaceFolder),
+			agentcontainers.WithContainerLabelIncludeFilter(agentcontainers.DevcontainerIsTestRunLabel, "true"),
+		)
+	})
+
+	testutil.Eventually(ctx, t, func(ctx context.Context) bool {
+		return slices.Contains(client.GetLifecycleStates(), codersdk.WorkspaceAgentLifecycleReady)
+	}, testutil.IntervalMedium, "agent not ready")
+
+	var dcPrebuild codersdk.WorkspaceAgentDevcontainer
+	testutil.Eventually(ctx, t, func(ctx context.Context) bool {
+		resp, err := conn.ListContainers(ctx)
+		require.NoError(t, err)
+
+		for _, dc := range resp.Devcontainers {
+			if dc.Container == nil {
+				continue
+			}
+
+			v, ok := dc.Container.Labels[agentcontainers.DevcontainerLocalFolderLabel]
+			if ok && v == workspaceFolder {
+				dcPrebuild = dc
+				return true
+			}
+		}
+
+		return false
+	}, testutil.IntervalMedium, "devcontainer not found")
+	defer func() {
+		pool.Client.RemoveContainer(docker.RemoveContainerOptions{
+			ID:            dcPrebuild.Container.ID,
+			RemoveVolumes: true,
+			Force:         true,
+		})
+	}()
+
+	// Then: We expect a sub agent to have been created.
+	subAgents := client.GetSubAgents()
+	require.Len(t, subAgents, 1)
+
+	subAgent := subAgents[0]
+	subAgentID, err := uuid.FromBytes(subAgent.GetId())
+	require.NoError(t, err)
+
+	// And: We expect there to be 1 app.
+	subAgentApps, err := client.GetSubAgentApps(subAgentID)
+	require.NoError(t, err)
+	require.Len(t, subAgentApps, 1)
+
+	// And: This app should contain the prebuild workspace name and owner name.
+	subAgentApp := subAgentApps[0]
+	require.Equal(t, "zed://ssh/project.prebuilds-xyz-123.prebuilds.coder/workspaces/project", subAgentApp.GetUrl())
+
+	// Given: We close the client and connection
+	client.Close()
+	conn.Close()
+
+	// Given: A new manifest with a regular user owner name and workspace name.
+	manifest = agentsdk.Manifest{
+		OwnerName:     "user",
+		WorkspaceName: "user-workspace",
+
+		Devcontainers: []codersdk.WorkspaceAgentDevcontainer{
+			{ID: devcontainerID, Name: "test", WorkspaceFolder: workspaceFolder},
+		},
+		Scripts: []codersdk.WorkspaceAgentScript{
+			{ID: devcontainerID, LogSourceID: devcontainerLogSourceID},
+		},
+	}
+
+	// When: We create an agent with devcontainers enabled.
+	//nolint:dogsled
+	conn, client, _, _, _ = setupAgent(t, manifest, 0, func(_ *agenttest.Client, o *agent.Options) {
+		o.Devcontainers = true
+		o.DevcontainerAPIOptions = append(o.DevcontainerAPIOptions,
+			agentcontainers.WithContainerLabelIncludeFilter(agentcontainers.DevcontainerLocalFolderLabel, workspaceFolder),
+			agentcontainers.WithContainerLabelIncludeFilter(agentcontainers.DevcontainerIsTestRunLabel, "true"),
+		)
+	})
+
+	testutil.Eventually(ctx, t, func(ctx context.Context) bool {
+		return slices.Contains(client.GetLifecycleStates(), codersdk.WorkspaceAgentLifecycleReady)
+	}, testutil.IntervalMedium, "agent not ready")
+
+	var dcClaimed codersdk.WorkspaceAgentDevcontainer
+	testutil.Eventually(ctx, t, func(ctx context.Context) bool {
+		resp, err := conn.ListContainers(ctx)
+		require.NoError(t, err)
+
+		for _, dc := range resp.Devcontainers {
+			if dc.Container == nil {
+				continue
+			}
+
+			v, ok := dc.Container.Labels[agentcontainers.DevcontainerLocalFolderLabel]
+			if ok && v == workspaceFolder {
+				dcClaimed = dc
+				return true
+			}
+		}
+
+		return false
+	}, testutil.IntervalMedium, "devcontainer not found")
+	defer func() {
+		if dcClaimed.Container.ID != dcPrebuild.Container.ID {
+			pool.Client.RemoveContainer(docker.RemoveContainerOptions{
+				ID:            dcClaimed.Container.ID,
+				RemoveVolumes: true,
+				Force:         true,
+			})
+		}
+	}()
+
+	// Then: We expect the claimed devcontainer and prebuild devcontainer
+	// to be using the same underlying container.
+	require.Equal(t, dcPrebuild.Container.ID, dcClaimed.Container.ID)
+
+	// And: We expect there to be a sub agent created.
+	subAgents = client.GetSubAgents()
+	require.Len(t, subAgents, 1)
+
+	subAgent = subAgents[0]
+	subAgentID, err = uuid.FromBytes(subAgent.GetId())
+	require.NoError(t, err)
+
+	// And: We expect there to be an app.
+	subAgentApps, err = client.GetSubAgentApps(subAgentID)
+	require.NoError(t, err)
+	require.Len(t, subAgentApps, 1)
+
+	// And: We expect this app to have the user's owner name and workspace name.
+	subAgentApp = subAgentApps[0]
+	require.Equal(t, "zed://ssh/project.user-workspace.user.coder/workspaces/project", subAgentApp.GetUrl())
 }
 
 func TestAgent_Dial(t *testing.T) {
@@ -2459,11 +2668,11 @@ func TestAgent_Dial(t *testing.T) {
 
 	cases := []struct {
 		name  string
-		setup func(t *testing.T) net.Listener
+		setup func(t testing.TB) net.Listener
 	}{
 		{
 			name: "TCP",
-			setup: func(t *testing.T) net.Listener {
+			setup: func(t testing.TB) net.Listener {
 				l, err := net.Listen("tcp", "127.0.0.1:0")
 				require.NoError(t, err, "create TCP listener")
 				return l
@@ -2471,7 +2680,7 @@ func TestAgent_Dial(t *testing.T) {
 		},
 		{
 			name: "UDP",
-			setup: func(t *testing.T) net.Listener {
+			setup: func(t testing.TB) net.Listener {
 				addr := net.UDPAddr{
 					IP:   net.ParseIP("127.0.0.1"),
 					Port: 0,
@@ -2489,57 +2698,69 @@ func TestAgent_Dial(t *testing.T) {
 
 			// The purpose of this test is to ensure that a client can dial a
 			// listener in the workspace over tailnet.
-			l := c.setup(t)
-			done := make(chan struct{})
-			defer func() {
-				l.Close()
-				<-done
-			}()
+			//
+			// The OS sometimes drops packets if the system can't keep up with
+			// them. For TCP packets, it's typically fine due to
+			// retransmissions, but for UDP packets, it can fail this test.
+			//
+			// The OS gets involved for the Wireguard traffic (either via DERP
+			// or direct UDP), and also for the traffic between the agent and
+			// the listener in the "workspace".
+			//
+			// To avoid this, we'll retry this test up to 3 times.
+			//nolint:gocritic // This test is flaky due to uncontrollable OS packet drops under heavy load.
+			testutil.RunRetry(t, 3, func(t testing.TB) {
+				ctx := testutil.Context(t, testutil.WaitLong)
 
-			ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
-			defer cancel()
+				l := c.setup(t)
+				done := make(chan struct{})
+				defer func() {
+					l.Close()
+					<-done
+				}()
 
-			go func() {
-				defer close(done)
-				for range 2 {
-					c, err := l.Accept()
-					if assert.NoError(t, err, "accept connection") {
-						testAccept(ctx, t, c)
-						_ = c.Close()
+				go func() {
+					defer close(done)
+					for range 2 {
+						c, err := l.Accept()
+						if assert.NoError(t, err, "accept connection") {
+							testAccept(ctx, t, c)
+							_ = c.Close()
+						}
 					}
+				}()
+
+				agentID := uuid.UUID{0, 0, 0, 0, 0, 1, 2, 3, 4, 5, 6, 7, 8}
+				//nolint:dogsled
+				agentConn, _, _, _, _ := setupAgent(t, agentsdk.Manifest{
+					AgentID: agentID,
+				}, 0)
+				require.True(t, agentConn.AwaitReachable(ctx))
+				conn, err := agentConn.DialContext(ctx, l.Addr().Network(), l.Addr().String())
+				require.NoError(t, err)
+				testDial(ctx, t, conn)
+				err = conn.Close()
+				require.NoError(t, err)
+
+				// also connect via the CoderServicePrefix, to test that we can reach the agent on this
+				// IP. This will be required for CoderVPN.
+				_, rawPort, _ := net.SplitHostPort(l.Addr().String())
+				port, _ := strconv.ParseUint(rawPort, 10, 16)
+				ipp := netip.AddrPortFrom(tailnet.CoderServicePrefix.AddrFromUUID(agentID), uint16(port))
+
+				switch l.Addr().Network() {
+				case "tcp":
+					conn, err = agentConn.TailnetConn().DialContextTCP(ctx, ipp)
+				case "udp":
+					conn, err = agentConn.TailnetConn().DialContextUDP(ctx, ipp)
+				default:
+					t.Fatalf("unknown network: %s", l.Addr().Network())
 				}
-			}()
-
-			agentID := uuid.UUID{0, 0, 0, 0, 0, 1, 2, 3, 4, 5, 6, 7, 8}
-			//nolint:dogsled
-			agentConn, _, _, _, _ := setupAgent(t, agentsdk.Manifest{
-				AgentID: agentID,
-			}, 0)
-			require.True(t, agentConn.AwaitReachable(ctx))
-			conn, err := agentConn.DialContext(ctx, l.Addr().Network(), l.Addr().String())
-			require.NoError(t, err)
-			testDial(ctx, t, conn)
-			err = conn.Close()
-			require.NoError(t, err)
-
-			// also connect via the CoderServicePrefix, to test that we can reach the agent on this
-			// IP. This will be required for CoderVPN.
-			_, rawPort, _ := net.SplitHostPort(l.Addr().String())
-			port, _ := strconv.ParseUint(rawPort, 10, 16)
-			ipp := netip.AddrPortFrom(tailnet.CoderServicePrefix.AddrFromUUID(agentID), uint16(port))
-
-			switch l.Addr().Network() {
-			case "tcp":
-				conn, err = agentConn.Conn.DialContextTCP(ctx, ipp)
-			case "udp":
-				conn, err = agentConn.Conn.DialContextUDP(ctx, ipp)
-			default:
-				t.Fatalf("unknown network: %s", l.Addr().Network())
-			}
-			require.NoError(t, err)
-			testDial(ctx, t, conn)
-			err = conn.Close()
-			require.NoError(t, err)
+				require.NoError(t, err)
+				testDial(ctx, t, conn)
+				err = conn.Close()
+				require.NoError(t, err)
+			})
 		})
 	}
 }
@@ -2590,7 +2811,7 @@ func TestAgent_UpdatedDERP(t *testing.T) {
 	})
 
 	// Setup a client connection.
-	newClientConn := func(derpMap *tailcfg.DERPMap, name string) *workspacesdk.AgentConn {
+	newClientConn := func(derpMap *tailcfg.DERPMap, name string) workspacesdk.AgentConn {
 		conn, err := tailnet.NewConn(&tailnet.Options{
 			Addresses: []netip.Prefix{tailnet.TailscaleServicePrefix.RandomPrefix()},
 			DERPMap:   derpMap,
@@ -2670,13 +2891,13 @@ func TestAgent_UpdatedDERP(t *testing.T) {
 
 	// Connect from a second client and make sure it uses the new DERP map.
 	conn2 := newClientConn(newDerpMap, "client2")
-	require.Equal(t, []int{2}, conn2.DERPMap().RegionIDs())
+	require.Equal(t, []int{2}, conn2.TailnetConn().DERPMap().RegionIDs())
 	t.Log("conn2 got the new DERPMap")
 
 	// If the first client gets a DERP map update, it should be able to
 	// reconnect just fine.
-	conn1.SetDERPMap(newDerpMap)
-	require.Equal(t, []int{2}, conn1.DERPMap().RegionIDs())
+	conn1.TailnetConn().SetDERPMap(newDerpMap)
+	require.Equal(t, []int{2}, conn1.TailnetConn().DERPMap().RegionIDs())
 	t.Log("set the new DERPMap on conn1")
 	ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
 	defer cancel()
@@ -3042,8 +3263,8 @@ func setupSSHSessionOnPort(
 	return session
 }
 
-func setupAgent(t *testing.T, metadata agentsdk.Manifest, ptyTimeout time.Duration, opts ...func(*agenttest.Client, *agent.Options)) (
-	*workspacesdk.AgentConn,
+func setupAgent(t testing.TB, metadata agentsdk.Manifest, ptyTimeout time.Duration, opts ...func(*agenttest.Client, *agent.Options)) (
+	workspacesdk.AgentConn,
 	*agenttest.Client,
 	<-chan *proto.Stats,
 	afero.Fs,
@@ -3140,7 +3361,7 @@ func setupAgent(t *testing.T, metadata agentsdk.Manifest, ptyTimeout time.Durati
 
 var dialTestPayload = []byte("dean-was-here123")
 
-func testDial(ctx context.Context, t *testing.T, c net.Conn) {
+func testDial(ctx context.Context, t testing.TB, c net.Conn) {
 	t.Helper()
 
 	if deadline, ok := ctx.Deadline(); ok {
@@ -3156,7 +3377,7 @@ func testDial(ctx context.Context, t *testing.T, c net.Conn) {
 	assertReadPayload(t, c, dialTestPayload)
 }
 
-func testAccept(ctx context.Context, t *testing.T, c net.Conn) {
+func testAccept(ctx context.Context, t testing.TB, c net.Conn) {
 	t.Helper()
 	defer c.Close()
 
@@ -3173,7 +3394,7 @@ func testAccept(ctx context.Context, t *testing.T, c net.Conn) {
 	assertWritePayload(t, c, dialTestPayload)
 }
 
-func assertReadPayload(t *testing.T, r io.Reader, payload []byte) {
+func assertReadPayload(t testing.TB, r io.Reader, payload []byte) {
 	t.Helper()
 	b := make([]byte, len(payload)+16)
 	n, err := r.Read(b)
@@ -3182,11 +3403,11 @@ func assertReadPayload(t *testing.T, r io.Reader, payload []byte) {
 	assert.Equal(t, payload, b[:n])
 }
 
-func assertWritePayload(t *testing.T, w io.Writer, payload []byte) {
+func assertWritePayload(t testing.TB, w io.Writer, payload []byte) {
 	t.Helper()
 	n, err := w.Write(payload)
 	assert.NoError(t, err, "write payload")
-	assert.Equal(t, len(payload), n, "payload length does not match")
+	assert.Equal(t, len(payload), n, "written payload length does not match")
 }
 
 func testSessionOutput(t *testing.T, session *ssh.Session, expected, unexpected []string, expectedRe *regexp.Regexp) {
@@ -3249,7 +3470,11 @@ func TestAgent_Metrics_SSH(t *testing.T) {
 	registry := prometheus.NewRegistry()
 
 	//nolint:dogsled
-	conn, _, _, _, _ := setupAgent(t, agentsdk.Manifest{}, 0, func(_ *agenttest.Client, o *agent.Options) {
+	conn, _, _, _, _ := setupAgent(t, agentsdk.Manifest{
+		// Make sure we always get a DERP connection for
+		// currently_reachable_peers.
+		DisableDirectConnections: true,
+	}, 0, func(_ *agenttest.Client, o *agent.Options) {
 		o.PrometheusRegistry = registry
 	})
 
@@ -3303,7 +3528,7 @@ func TestAgent_Metrics_SSH(t *testing.T) {
 		{
 			Name:  "coderd_agentstats_currently_reachable_peers",
 			Type:  proto.Stats_Metric_GAUGE,
-			Value: 0,
+			Value: 1,
 			Labels: []*proto.Stats_Metric_Label{
 				{
 					Name:  "connection_type",
@@ -3314,7 +3539,7 @@ func TestAgent_Metrics_SSH(t *testing.T) {
 		{
 			Name:  "coderd_agentstats_currently_reachable_peers",
 			Type:  proto.Stats_Metric_GAUGE,
-			Value: 1,
+			Value: 0,
 			Labels: []*proto.Stats_Metric_Label{
 				{
 					Name:  "connection_type",

agent/agentcontainers/api.go

@@ -2,8 +2,11 @@ package agentcontainers
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"fmt"
+	"io/fs"
+	"maps"
 	"net/http"
 	"os"
 	"path"
@@ -18,10 +21,13 @@ import (
 
 	"github.com/fsnotify/fsnotify"
 	"github.com/go-chi/chi/v5"
+	"github.com/go-git/go-git/v5/plumbing/format/gitignore"
 	"github.com/google/uuid"
+	"github.com/spf13/afero"
 	"golang.org/x/xerrors"
 
 	"cdr.dev/slog"
+	"github.com/coder/coder/v2/agent/agentcontainers/ignore"
 	"github.com/coder/coder/v2/agent/agentcontainers/watcher"
 	"github.com/coder/coder/v2/agent/agentexec"
 	"github.com/coder/coder/v2/agent/usershell"
@@ -30,6 +36,7 @@ import (
 	"github.com/coder/coder/v2/codersdk/agentsdk"
 	"github.com/coder/coder/v2/provisioner"
 	"github.com/coder/quartz"
+	"github.com/coder/websocket"
 )
 
 const (
@@ -53,11 +60,12 @@ type API struct {
 	cancel                      context.CancelFunc
 	watcherDone                 chan struct{}
 	updaterDone                 chan struct{}
-	initialUpdateDone           chan struct{}   // Closed after first update in updaterLoop.
+	discoverDone                chan struct{}
 	updateTrigger               chan chan error // Channel to trigger manual refresh.
 	updateInterval              time.Duration   // Interval for periodic container updates.
 	logger                      slog.Logger
 	watcher                     watcher.Watcher
+	fs                          afero.Fs
 	execer                      agentexec.Execer
 	commandEnv                  CommandEnv
 	ccli                        ContainerCLI
@@ -69,15 +77,23 @@ type API struct {
 	subAgentURL                 string
 	subAgentEnv                 []string
 
-	ownerName     string
-	workspaceName string
+	projectDiscovery   bool // If we should perform project discovery or not.
+	discoveryAutostart bool // If we should autostart discovered projects.
 
-	mu                       sync.RWMutex
+	ownerName      string
+	workspaceName  string
+	parentAgent    string
+	agentDirectory string
+
+	mu                       sync.RWMutex  // Protects the following fields.
+	initDone                 chan struct{} // Closed by Init.
+	updateChans              []chan struct{}
 	closed                   bool
 	containers               codersdk.WorkspaceAgentListContainersResponse  // Output from the last list operation.
 	containersErr            error                                          // Error from the last list operation.
 	devcontainerNames        map[string]bool                                // By devcontainer name.
 	knownDevcontainers       map[string]codersdk.WorkspaceAgentDevcontainer // By workspace folder.
+	devcontainerLogSourceIDs map[string]uuid.UUID                           // By workspace folder.
 	configFileModifiedTimes  map[string]time.Time                           // By config file path.
 	recreateSuccessTimes     map[string]time.Time                           // By workspace folder.
 	recreateErrorTimes       map[string]time.Time                           // By workspace folder.
@@ -85,8 +101,6 @@ type API struct {
 	usingWorkspaceFolderName map[string]bool                                // By workspace folder.
 	ignoredDevcontainers     map[string]bool                                // By workspace folder. Tracks three states (true, false and not checked).
 	asyncWg                  sync.WaitGroup
-
-	devcontainerLogSourceIDs map[string]uuid.UUID // By workspace folder.
 }
 
 type subAgentProcess struct {
@@ -130,7 +144,9 @@ func WithCommandEnv(ce CommandEnv) Option {
 					strings.HasPrefix(s, "CODER_WORKSPACE_AGENT_URL=") ||
 					strings.HasPrefix(s, "CODER_AGENT_TOKEN=") ||
 					strings.HasPrefix(s, "CODER_AGENT_AUTH=") ||
-					strings.HasPrefix(s, "CODER_AGENT_DEVCONTAINERS_ENABLE=")
+					strings.HasPrefix(s, "CODER_AGENT_DEVCONTAINERS_ENABLE=") ||
+					strings.HasPrefix(s, "CODER_AGENT_DEVCONTAINERS_PROJECT_DISCOVERY_ENABLE=") ||
+					strings.HasPrefix(s, "CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE=")
 			})
 			return shell, dir, env, nil
 		}
@@ -147,8 +163,8 @@ func WithContainerCLI(ccli ContainerCLI) Option {
 
 // WithContainerLabelIncludeFilter sets a label filter for containers.
 // This option can be given multiple times to filter by multiple labels.
-// The behavior is such that only containers matching one or more of the
-// provided labels will be included.
+// The behavior is such that only containers matching all of the provided
+// labels will be included.
 func WithContainerLabelIncludeFilter(label, value string) Option {
 	return func(api *API) {
 		api.containerLabelIncludeFilter[label] = value
@@ -188,10 +204,12 @@ func WithSubAgentEnv(env ...string) Option {
 
 // WithManifestInfo sets the owner name, and workspace name
 // for the sub-agent.
-func WithManifestInfo(owner, workspace string) Option {
+func WithManifestInfo(owner, workspace, parentAgent, agentDirectory string) Option {
 	return func(api *API) {
 		api.ownerName = owner
 		api.workspaceName = workspace
+		api.parentAgent = parentAgent
+		api.agentDirectory = agentDirectory
 	}
 }
 
@@ -207,6 +225,29 @@ func WithDevcontainers(devcontainers []codersdk.WorkspaceAgentDevcontainer, scri
 		api.devcontainerNames = make(map[string]bool, len(devcontainers))
 		api.devcontainerLogSourceIDs = make(map[string]uuid.UUID)
 		for _, dc := range devcontainers {
+			if dc.Status == "" {
+				dc.Status = codersdk.WorkspaceAgentDevcontainerStatusStarting
+			}
+			logger := api.logger.With(
+				slog.F("devcontainer_id", dc.ID),
+				slog.F("devcontainer_name", dc.Name),
+				slog.F("workspace_folder", dc.WorkspaceFolder),
+				slog.F("config_path", dc.ConfigPath),
+			)
+
+			// Devcontainers have a name originating from Terraform, but
+			// we need to ensure that the name is unique. We will use
+			// the workspace folder name to generate a unique agent name,
+			// and if that fails, we will fall back to the devcontainers
+			// original name.
+			name, usingWorkspaceFolder := api.makeAgentName(dc.WorkspaceFolder, dc.Name)
+			if name != dc.Name {
+				logger = logger.With(slog.F("devcontainer_name", name))
+				logger.Debug(api.ctx, "updating devcontainer name", slog.F("devcontainer_old_name", dc.Name))
+				dc.Name = name
+				api.usingWorkspaceFolderName[dc.WorkspaceFolder] = usingWorkspaceFolder
+			}
+
 			api.knownDevcontainers[dc.WorkspaceFolder] = dc
 			api.devcontainerNames[dc.Name] = true
 			for _, script := range scripts {
@@ -218,12 +259,7 @@ func WithDevcontainers(devcontainers []codersdk.WorkspaceAgentDevcontainer, scri
 				}
 			}
 			if api.devcontainerLogSourceIDs[dc.WorkspaceFolder] == uuid.Nil {
-				api.logger.Error(api.ctx, "devcontainer log source ID not found for devcontainer",
-					slog.F("devcontainer_id", dc.ID),
-					slog.F("devcontainer_name", dc.Name),
-					slog.F("workspace_folder", dc.WorkspaceFolder),
-					slog.F("config_path", dc.ConfigPath),
-				)
+				logger.Error(api.ctx, "devcontainer log source ID not found for devcontainer")
 			}
 		}
 	}
@@ -238,6 +274,29 @@ func WithWatcher(w watcher.Watcher) Option {
 	}
 }
 
+// WithFileSystem sets the file system used for discovering projects.
+func WithFileSystem(fileSystem afero.Fs) Option {
+	return func(api *API) {
+		api.fs = fileSystem
+	}
+}
+
+// WithProjectDiscovery sets if the API should attempt to discover
+// projects on the filesystem.
+func WithProjectDiscovery(projectDiscovery bool) Option {
+	return func(api *API) {
+		api.projectDiscovery = projectDiscovery
+	}
+}
+
+// WithDiscoveryAutostart sets if the API should attempt to autostart
+// projects that have been discovered
+func WithDiscoveryAutostart(discoveryAutostart bool) Option {
+	return func(api *API) {
+		api.discoveryAutostart = discoveryAutostart
+	}
+}
+
 // ScriptLogger is an interface for sending devcontainer logs to the
 // controlplane.
 type ScriptLogger interface {
@@ -265,9 +324,7 @@ func NewAPI(logger slog.Logger, options ...Option) *API {
 	api := &API{
 		ctx:                         ctx,
 		cancel:                      cancel,
-		watcherDone:                 make(chan struct{}),
-		updaterDone:                 make(chan struct{}),
-		initialUpdateDone:           make(chan struct{}),
+		initDone:                    make(chan struct{}),
 		updateTrigger:               make(chan chan error),
 		updateInterval:              defaultUpdateInterval,
 		logger:                      logger,
@@ -310,15 +367,217 @@ func NewAPI(logger slog.Logger, options ...Option) *API {
 			api.watcher = watcher.NewNoop()
 		}
 	}
+	if api.fs == nil {
+		api.fs = afero.NewOsFs()
+	}
 	if api.subAgentClient.Load() == nil {
 		var c SubAgentClient = noopSubAgentClient{}
 		api.subAgentClient.Store(&c)
 	}
 
+	return api
+}
+
+// Init applies a final set of options to the API and then
+// closes initDone. This method can only be called once.
+func (api *API) Init(opts ...Option) {
+	api.mu.Lock()
+	defer api.mu.Unlock()
+	if api.closed {
+		return
+	}
+	select {
+	case <-api.initDone:
+		return
+	default:
+	}
+	defer close(api.initDone)
+
+	for _, opt := range opts {
+		opt(api)
+	}
+}
+
+// Start starts the API by initializing the watcher and updater loops.
+// This method calls Init, if it is desired to apply options after
+// the API has been created, it should be done by calling Init before
+// Start. This method must only be called once.
+func (api *API) Start() {
+	api.Init()
+
+	api.mu.Lock()
+	defer api.mu.Unlock()
+	if api.closed {
+		return
+	}
+
+	if api.projectDiscovery && api.agentDirectory != "" {
+		api.discoverDone = make(chan struct{})
+
+		go api.discover()
+	}
+
+	api.watcherDone = make(chan struct{})
+	api.updaterDone = make(chan struct{})
+
 	go api.watcherLoop()
 	go api.updaterLoop()
+}
 
-	return api
+func (api *API) discover() {
+	defer close(api.discoverDone)
+	defer api.logger.Debug(api.ctx, "project discovery finished")
+	api.logger.Debug(api.ctx, "project discovery started")
+
+	if err := api.discoverDevcontainerProjects(); err != nil {
+		api.logger.Error(api.ctx, "discovering dev container projects", slog.Error(err))
+	}
+
+	if err := api.RefreshContainers(api.ctx); err != nil {
+		api.logger.Error(api.ctx, "refreshing containers after discovery", slog.Error(err))
+	}
+}
+
+func (api *API) discoverDevcontainerProjects() error {
+	isGitProject, err := afero.DirExists(api.fs, filepath.Join(api.agentDirectory, ".git"))
+	if err != nil {
+		return xerrors.Errorf(".git dir exists: %w", err)
+	}
+
+	// If the agent directory is a git project, we'll search
+	// the project for any `.devcontainer/devcontainer.json`
+	// files.
+	if isGitProject {
+		return api.discoverDevcontainersInProject(api.agentDirectory)
+	}
+
+	// The agent directory is _not_ a git project, so we'll
+	// search the top level of the agent directory for any
+	// git projects, and search those.
+	entries, err := afero.ReadDir(api.fs, api.agentDirectory)
+	if err != nil {
+		return xerrors.Errorf("read agent directory: %w", err)
+	}
+
+	for _, entry := range entries {
+		if !entry.IsDir() {
+			continue
+		}
+
+		isGitProject, err = afero.DirExists(api.fs, filepath.Join(api.agentDirectory, entry.Name(), ".git"))
+		if err != nil {
+			return xerrors.Errorf(".git dir exists: %w", err)
+		}
+
+		// If this directory is a git project, we'll search
+		// it for any `.devcontainer/devcontainer.json` files.
+		if isGitProject {
+			if err := api.discoverDevcontainersInProject(filepath.Join(api.agentDirectory, entry.Name())); err != nil {
+				return err
+			}
+		}
+	}
+
+	return nil
+}
+
+func (api *API) discoverDevcontainersInProject(projectPath string) error {
+	logger := api.logger.
+		Named("project-discovery").
+		With(slog.F("project_path", projectPath))
+
+	globalPatterns, err := ignore.LoadGlobalPatterns(api.fs)
+	if err != nil {
+		return xerrors.Errorf("read global git ignore patterns: %w", err)
+	}
+
+	patterns, err := ignore.ReadPatterns(api.ctx, logger, api.fs, projectPath)
+	if err != nil {
+		return xerrors.Errorf("read git ignore patterns: %w", err)
+	}
+
+	matcher := gitignore.NewMatcher(append(globalPatterns, patterns...))
+
+	devcontainerConfigPaths := []string{
+		"/.devcontainer/devcontainer.json",
+		"/.devcontainer.json",
+	}
+
+	return afero.Walk(api.fs, projectPath, func(path string, info fs.FileInfo, err error) error {
+		if err != nil {
+			logger.Error(api.ctx, "encountered error while walking for dev container projects",
+				slog.F("path", path),
+				slog.Error(err))
+			return nil
+		}
+
+		pathParts := ignore.FilePathToParts(path)
+
+		// We know that a directory entry cannot be a `devcontainer.json` file, so we
+		// always skip processing directories. If the directory happens to be ignored
+		// by git then we'll make sure to ignore all of the children of that directory.
+		if info.IsDir() {
+			if matcher.Match(pathParts, true) {
+				return fs.SkipDir
+			}
+
+			return nil
+		}
+
+		if matcher.Match(pathParts, false) {
+			return nil
+		}
+
+		for _, relativeConfigPath := range devcontainerConfigPaths {
+			if !strings.HasSuffix(path, relativeConfigPath) {
+				continue
+			}
+
+			workspaceFolder := strings.TrimSuffix(path, relativeConfigPath)
+
+			logger := logger.With(slog.F("workspace_folder", workspaceFolder))
+			logger.Debug(api.ctx, "discovered dev container project")
+
+			api.mu.Lock()
+			if _, found := api.knownDevcontainers[workspaceFolder]; !found {
+				logger.Debug(api.ctx, "adding dev container project")
+
+				dc := codersdk.WorkspaceAgentDevcontainer{
+					ID:              uuid.New(),
+					Name:            "", // Updated later based on container state.
+					WorkspaceFolder: workspaceFolder,
+					ConfigPath:      path,
+					Status:          codersdk.WorkspaceAgentDevcontainerStatusStopped,
+					Dirty:           false, // Updated later based on config file changes.
+					Container:       nil,
+				}
+
+				if api.discoveryAutostart {
+					config, err := api.dccli.ReadConfig(api.ctx, workspaceFolder, path, []string{})
+					if err != nil {
+						logger.Error(api.ctx, "read project configuration", slog.Error(err))
+					} else if config.Configuration.Customizations.Coder.AutoStart {
+						dc.Status = codersdk.WorkspaceAgentDevcontainerStatusStarting
+					}
+				}
+
+				api.knownDevcontainers[workspaceFolder] = dc
+				api.broadcastUpdatesLocked()
+
+				if dc.Status == codersdk.WorkspaceAgentDevcontainerStatusStarting {
+					api.asyncWg.Add(1)
+					go func() {
+						defer api.asyncWg.Done()
+
+						_ = api.CreateDevcontainer(dc.WorkspaceFolder, dc.ConfigPath)
+					}()
+				}
+			}
+			api.mu.Unlock()
+		}
+
+		return nil
+	})
 }
 
 func (api *API) watcherLoop() {
@@ -391,28 +650,37 @@ func (api *API) updaterLoop() {
 	} else {
 		api.logger.Debug(api.ctx, "initial containers update complete")
 	}
-	// Signal that the initial update attempt (successful or not) is done.
-	// Other services can wait on this if they need the first data to be available.
-	close(api.initialUpdateDone)
 
 	// We utilize a TickerFunc here instead of a regular Ticker so that
 	// we can guarantee execution of the updateContainers method after
 	// advancing the clock.
+	var prevErr error
 	ticker := api.clock.TickerFunc(api.ctx, api.updateInterval, func() error {
 		done := make(chan error, 1)
-		defer close(done)
-
+		var sent bool
+		defer func() {
+			if !sent {
+				close(done)
+			}
+		}()
 		select {
 		case <-api.ctx.Done():
 			return api.ctx.Err()
 		case api.updateTrigger <- done:
+			sent = true
 			err := <-done
 			if err != nil {
 				if errors.Is(err, context.Canceled) {
 					api.logger.Warn(api.ctx, "updater loop ticker canceled", slog.Error(err))
-				} else {
+					return nil
+				}
+				// Avoid excessive logging of the same error.
+				if prevErr == nil || prevErr.Error() != err.Error() {
 					api.logger.Error(api.ctx, "updater loop ticker failed", slog.Error(err))
 				}
+				prevErr = err
+			} else {
+				prevErr = nil
 			}
 		default:
 			api.logger.Debug(api.ctx, "updater loop ticker skipped, update in progress")
@@ -434,6 +702,7 @@ func (api *API) updaterLoop() {
 			// Note that although we pass api.ctx here, updateContainers
 			// has an internal timeout to prevent long blocking calls.
 			done <- api.updateContainers(api.ctx)
+			close(done)
 		}
 	}
 }
@@ -447,7 +716,7 @@ func (api *API) UpdateSubAgentClient(client SubAgentClient) {
 func (api *API) Routes() http.Handler {
 	r := chi.NewRouter()
 
-	ensureInitialUpdateDoneMW := func(next http.Handler) http.Handler {
+	ensureInitDoneMW := func(next http.Handler) http.Handler {
 		return http.HandlerFunc(func(rw http.ResponseWriter, r *http.Request) {
 			select {
 			case <-api.ctx.Done():
@@ -458,9 +727,8 @@ func (api *API) Routes() http.Handler {
 				return
 			case <-r.Context().Done():
 				return
-			case <-api.initialUpdateDone:
-				// Initial update is done, we can start processing
-				// requests.
+			case <-api.initDone:
+				// API init is done, we can start processing requests.
 			}
 			next.ServeHTTP(rw, r)
 		})
@@ -469,18 +737,105 @@ func (api *API) Routes() http.Handler {
 	// For now, all endpoints require the initial update to be done.
 	// If we want to allow some endpoints to be available before
 	// the initial update, we can enable this per-route.
-	r.Use(ensureInitialUpdateDoneMW)
+	r.Use(ensureInitDoneMW)
 
 	r.Get("/", api.handleList)
+	r.Get("/watch", api.watchContainers)
 	// TODO(mafredri): Simplify this route as the previous /devcontainers
 	// /-route was dropped. We can drop the /devcontainers prefix here too.
-	r.Route("/devcontainers", func(r chi.Router) {
-		r.Post("/container/{container}/recreate", api.handleDevcontainerRecreate)
+	r.Route("/devcontainers/{devcontainer}", func(r chi.Router) {
+		r.Post("/recreate", api.handleDevcontainerRecreate)
 	})
 
 	return r
 }
 
+func (api *API) broadcastUpdatesLocked() {
+	// Broadcast state changes to WebSocket listeners.
+	for _, ch := range api.updateChans {
+		select {
+		case ch <- struct{}{}:
+		default:
+		}
+	}
+}
+
+func (api *API) watchContainers(rw http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+
+	conn, err := websocket.Accept(rw, r, &websocket.AcceptOptions{
+		// We want `NoContextTakeover` compression to balance improving
+		// bandwidth cost/latency with minimal memory usage overhead.
+		CompressionMode: websocket.CompressionNoContextTakeover,
+	})
+	if err != nil {
+		httpapi.Write(ctx, rw, http.StatusInternalServerError, codersdk.Response{
+			Message: "Failed to upgrade connection to websocket.",
+			Detail:  err.Error(),
+		})
+		return
+	}
+
+	// Here we close the websocket for reading, so that the websocket library will handle pings and
+	// close frames.
+	_ = conn.CloseRead(context.Background())
+
+	ctx, wsNetConn := codersdk.WebsocketNetConn(ctx, conn, websocket.MessageText)
+	defer wsNetConn.Close()
+
+	go httpapi.Heartbeat(ctx, conn)
+
+	updateCh := make(chan struct{}, 1)
+
+	api.mu.Lock()
+	api.updateChans = append(api.updateChans, updateCh)
+	api.mu.Unlock()
+
+	defer func() {
+		api.mu.Lock()
+		api.updateChans = slices.DeleteFunc(api.updateChans, func(ch chan struct{}) bool {
+			return ch == updateCh
+		})
+		close(updateCh)
+		api.mu.Unlock()
+	}()
+
+	encoder := json.NewEncoder(wsNetConn)
+
+	ct, err := api.getContainers()
+	if err != nil {
+		api.logger.Error(ctx, "unable to get containers", slog.Error(err))
+		return
+	}
+
+	if err := encoder.Encode(ct); err != nil {
+		api.logger.Error(ctx, "encode container list", slog.Error(err))
+		return
+	}
+
+	for {
+		select {
+		case <-api.ctx.Done():
+			return
+
+		case <-ctx.Done():
+			return
+
+		case <-updateCh:
+			ct, err := api.getContainers()
+			if err != nil {
+				api.logger.Error(ctx, "unable to get containers", slog.Error(err))
+				continue
+			}
+
+			if err := encoder.Encode(ct); err != nil {
+				api.logger.Error(ctx, "encode container list", slog.Error(err))
+				return
+			}
+		}
+	}
+}
+
 // handleList handles the HTTP request to list containers.
 func (api *API) handleList(rw http.ResponseWriter, r *http.Request) {
 	ct, err := api.getContainers()
@@ -508,7 +863,6 @@ func (api *API) updateContainers(ctx context.Context) error {
 		// will clear up on the next update.
 		if !errors.Is(err, context.Canceled) {
 			api.mu.Lock()
-			api.containers = codersdk.WorkspaceAgentListContainersResponse{}
 			api.containersErr = err
 			api.mu.Unlock()
 		}
@@ -521,8 +875,26 @@ func (api *API) updateContainers(ctx context.Context) error {
 	api.mu.Lock()
 	defer api.mu.Unlock()
 
+	var previouslyKnownDevcontainers map[string]codersdk.WorkspaceAgentDevcontainer
+	if len(api.updateChans) > 0 {
+		previouslyKnownDevcontainers = maps.Clone(api.knownDevcontainers)
+	}
+
 	api.processUpdatedContainersLocked(ctx, updated)
 
+	if len(api.updateChans) > 0 {
+		statesAreEqual := maps.EqualFunc(
+			previouslyKnownDevcontainers,
+			api.knownDevcontainers,
+			func(dc1, dc2 codersdk.WorkspaceAgentDevcontainer) bool {
+				return dc1.Equals(dc2)
+			})
+
+		if !statesAreEqual {
+			api.broadcastUpdatesLocked()
+		}
+	}
+
 	api.logger.Debug(ctx, "containers updated successfully", slog.F("container_count", len(api.containers.Containers)), slog.F("warning_count", len(api.containers.Warnings)), slog.F("devcontainer_count", len(api.knownDevcontainers)))
 
 	return nil
@@ -571,16 +943,22 @@ func (api *API) processUpdatedContainersLocked(ctx context.Context, updated code
 			slog.F("config_file", configFile),
 		)
 
+		// If we haven't set any include filters, we should explicitly ignore test devcontainers.
+		if len(api.containerLabelIncludeFilter) == 0 && container.Labels[DevcontainerIsTestRunLabel] == "true" {
+			continue
+		}
+
+		// Filter out devcontainer tests, unless explicitly set in include filters.
 		if len(api.containerLabelIncludeFilter) > 0 {
-			var ok bool
+			includeContainer := true
 			for label, value := range api.containerLabelIncludeFilter {
-				if v, found := container.Labels[label]; found && v == value {
-					ok = true
-				}
+				v, found := container.Labels[label]
+
+				includeContainer = includeContainer && (found && v == value)
 			}
 			// Verbose debug logging is fine here since typically filters
 			// are only used in development or testing environments.
-			if !ok {
+			if !includeContainer {
 				logger.Debug(ctx, "container does not match include filter, ignoring devcontainer", slog.F("container_labels", container.Labels), slog.F("include_filter", api.containerLabelIncludeFilter))
 				continue
 			}
@@ -661,6 +1039,9 @@ func (api *API) processUpdatedContainersLocked(ctx context.Context, updated code
 				err := api.maybeInjectSubAgentIntoContainerLocked(ctx, dc)
 				if err != nil {
 					logger.Error(ctx, "inject subagent into container failed", slog.Error(err))
+					dc.Error = err.Error()
+				} else {
+					dc.Error = ""
 				}
 			}
 
@@ -777,12 +1158,19 @@ func (api *API) RefreshContainers(ctx context.Context) (err error) {
 	}()
 
 	done := make(chan error, 1)
+	var sent bool
+	defer func() {
+		if !sent {
+			close(done)
+		}
+	}()
 	select {
 	case <-api.ctx.Done():
 		return xerrors.Errorf("API closed: %w", api.ctx.Err())
 	case <-ctx.Done():
 		return ctx.Err()
 	case api.updateTrigger <- done:
+		sent = true
 		select {
 		case <-api.ctx.Done():
 			return xerrors.Errorf("API closed: %w", api.ctx.Err())
@@ -823,7 +1211,7 @@ func (api *API) getContainers() (codersdk.WorkspaceAgentListContainersResponse,
 			devcontainers = append(devcontainers, dc)
 		}
 		slices.SortFunc(devcontainers, func(a, b codersdk.WorkspaceAgentDevcontainer) int {
-			return strings.Compare(a.Name, b.Name)
+			return strings.Compare(a.WorkspaceFolder, b.WorkspaceFolder)
 		})
 	}
 
@@ -838,68 +1226,40 @@ func (api *API) getContainers() (codersdk.WorkspaceAgentListContainersResponse,
 // devcontainer by referencing the container.
 func (api *API) handleDevcontainerRecreate(w http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
-	containerID := chi.URLParam(r, "container")
+	devcontainerID := chi.URLParam(r, "devcontainer")
 
-	if containerID == "" {
+	if devcontainerID == "" {
 		httpapi.Write(ctx, w, http.StatusBadRequest, codersdk.Response{
-			Message: "Missing container ID or name",
-			Detail:  "Container ID or name is required to recreate a devcontainer.",
-		})
-		return
-	}
-
-	containers, err := api.getContainers()
-	if err != nil {
-		httpapi.Write(ctx, w, http.StatusInternalServerError, codersdk.Response{
-			Message: "Could not list containers",
-			Detail:  err.Error(),
-		})
-		return
-	}
-
-	containerIdx := slices.IndexFunc(containers.Containers, func(c codersdk.WorkspaceAgentContainer) bool { return c.Match(containerID) })
-	if containerIdx == -1 {
-		httpapi.Write(ctx, w, http.StatusNotFound, codersdk.Response{
-			Message: "Container not found",
-			Detail:  "Container ID or name not found in the list of containers.",
-		})
-		return
-	}
-
-	container := containers.Containers[containerIdx]
-	workspaceFolder := container.Labels[DevcontainerLocalFolderLabel]
-	configPath := container.Labels[DevcontainerConfigFileLabel]
-
-	// Workspace folder is required to recreate a container, we don't verify
-	// the config path here because it's optional.
-	if workspaceFolder == "" {
-		httpapi.Write(ctx, w, http.StatusBadRequest, codersdk.Response{
-			Message: "Missing workspace folder label",
-			Detail:  "The container is not a devcontainer, the container must have the workspace folder label to support recreation.",
+			Message: "Missing devcontainer ID",
+			Detail:  "Devcontainer ID is required to recreate a devcontainer.",
 		})
 		return
 	}
 
 	api.mu.Lock()
 
-	dc, ok := api.knownDevcontainers[workspaceFolder]
-	switch {
-	case !ok:
+	var dc codersdk.WorkspaceAgentDevcontainer
+	for _, knownDC := range api.knownDevcontainers {
+		if knownDC.ID.String() == devcontainerID {
+			dc = knownDC
+			break
+		}
+	}
+	if dc.ID == uuid.Nil {
 		api.mu.Unlock()
 
-		// This case should not happen if the container is a valid devcontainer.
-		api.logger.Error(ctx, "devcontainer not found for workspace folder", slog.F("workspace_folder", workspaceFolder))
-		httpapi.Write(ctx, w, http.StatusInternalServerError, codersdk.Response{
+		httpapi.Write(ctx, w, http.StatusNotFound, codersdk.Response{
 			Message: "Devcontainer not found.",
-			Detail:  fmt.Sprintf("Could not find devcontainer for workspace folder: %q", workspaceFolder),
+			Detail:  fmt.Sprintf("Could not find devcontainer with ID: %q", devcontainerID),
 		})
 		return
-	case dc.Status == codersdk.WorkspaceAgentDevcontainerStatusStarting:
+	}
+	if dc.Status == codersdk.WorkspaceAgentDevcontainerStatusStarting {
 		api.mu.Unlock()
 
 		httpapi.Write(ctx, w, http.StatusConflict, codersdk.Response{
 			Message: "Devcontainer recreation already in progress",
-			Detail:  fmt.Sprintf("Recreation for workspace folder %q is already underway.", dc.WorkspaceFolder),
+			Detail:  fmt.Sprintf("Recreation for devcontainer %q is already underway.", dc.Name),
 		})
 		return
 	}
@@ -908,52 +1268,69 @@ func (api *API) handleDevcontainerRecreate(w http.ResponseWriter, r *http.Reques
 	// devcontainer multiple times in parallel.
 	dc.Status = codersdk.WorkspaceAgentDevcontainerStatusStarting
 	dc.Container = nil
+	dc.Error = ""
 	api.knownDevcontainers[dc.WorkspaceFolder] = dc
-	api.asyncWg.Add(1)
-	go api.recreateDevcontainer(dc, configPath)
+	api.broadcastUpdatesLocked()
+
+	go func() {
+		_ = api.CreateDevcontainer(dc.WorkspaceFolder, dc.ConfigPath, WithRemoveExistingContainer())
+	}()
 
 	api.mu.Unlock()
 
 	httpapi.Write(ctx, w, http.StatusAccepted, codersdk.Response{
 		Message: "Devcontainer recreation initiated",
-		Detail:  fmt.Sprintf("Recreation process for workspace folder %q has started.", dc.WorkspaceFolder),
+		Detail:  fmt.Sprintf("Recreation process for devcontainer %q has started.", dc.Name),
 	})
 }
 
-// recreateDevcontainer should run in its own goroutine and is responsible for
+// createDevcontainer should run in its own goroutine and is responsible for
 // recreating a devcontainer based on the provided devcontainer configuration.
 // It updates the devcontainer status and logs the process. The configPath is
 // passed as a parameter for the odd chance that the container being recreated
 // has a different config file than the one stored in the devcontainer state.
 // The devcontainer state must be set to starting and the asyncWg must be
 // incremented before calling this function.
-func (api *API) recreateDevcontainer(dc codersdk.WorkspaceAgentDevcontainer, configPath string) {
-	defer api.asyncWg.Done()
+func (api *API) CreateDevcontainer(workspaceFolder, configPath string, opts ...DevcontainerCLIUpOptions) error {
+	api.mu.Lock()
+	if api.closed {
+		api.mu.Unlock()
+		return nil
+	}
+
+	dc, found := api.knownDevcontainers[workspaceFolder]
+	if !found {
+		api.mu.Unlock()
+		return xerrors.Errorf("devcontainer not found")
+	}
 
 	var (
-		err    error
 		ctx    = api.ctx
 		logger = api.logger.With(
 			slog.F("devcontainer_id", dc.ID),
 			slog.F("devcontainer_name", dc.Name),
 			slog.F("workspace_folder", dc.WorkspaceFolder),
-			slog.F("config_path", configPath),
+			slog.F("config_path", dc.ConfigPath),
 		)
 	)
 
+	// Send logs via agent logging facilities.
+	logSourceID := api.devcontainerLogSourceIDs[dc.WorkspaceFolder]
+	if logSourceID == uuid.Nil {
+		api.logger.Debug(api.ctx, "devcontainer log source ID not found, falling back to external log source ID")
+		logSourceID = agentsdk.ExternalLogSourceID
+	}
+
+	api.asyncWg.Add(1)
+	defer api.asyncWg.Done()
+	api.mu.Unlock()
+
 	if dc.ConfigPath != configPath {
 		logger.Warn(ctx, "devcontainer config path mismatch",
 			slog.F("config_path_param", configPath),
 		)
 	}
 
-	// Send logs via agent logging facilities.
-	logSourceID := api.devcontainerLogSourceIDs[dc.WorkspaceFolder]
-	if logSourceID == uuid.Nil {
-		// Fallback to the external log source ID if not found.
-		logSourceID = agentsdk.ExternalLogSourceID
-	}
-
 	scriptLogger := api.scriptLogger(logSourceID)
 	defer func() {
 		flushCtx, cancel := context.WithTimeout(api.ctx, 5*time.Second)
@@ -969,24 +1346,29 @@ func (api *API) recreateDevcontainer(dc codersdk.WorkspaceAgentDevcontainer, con
 
 	logger.Debug(ctx, "starting devcontainer recreation")
 
-	_, err = api.dccli.Up(ctx, dc.WorkspaceFolder, configPath, WithUpOutput(infoW, errW), WithRemoveExistingContainer())
+	upOptions := []DevcontainerCLIUpOptions{WithUpOutput(infoW, errW)}
+	upOptions = append(upOptions, opts...)
+
+	_, err := api.dccli.Up(ctx, dc.WorkspaceFolder, configPath, upOptions...)
 	if err != nil {
 		// No need to log if the API is closing (context canceled), as this
 		// is expected behavior when the API is shutting down.
 		if !errors.Is(err, context.Canceled) {
-			logger.Error(ctx, "devcontainer recreation failed", slog.Error(err))
+			logger.Error(ctx, "devcontainer creation failed", slog.Error(err))
 		}
 
 		api.mu.Lock()
 		dc = api.knownDevcontainers[dc.WorkspaceFolder]
 		dc.Status = codersdk.WorkspaceAgentDevcontainerStatusError
+		dc.Error = err.Error()
 		api.knownDevcontainers[dc.WorkspaceFolder] = dc
 		api.recreateErrorTimes[dc.WorkspaceFolder] = api.clock.Now("agentcontainers", "recreate", "errorTimes")
 		api.mu.Unlock()
-		return
+
+		return xerrors.Errorf("start devcontainer: %w", err)
 	}
 
-	logger.Info(ctx, "devcontainer recreated successfully")
+	logger.Info(ctx, "devcontainer created successfully")
 
 	api.mu.Lock()
 	dc = api.knownDevcontainers[dc.WorkspaceFolder]
@@ -1002,15 +1384,20 @@ func (api *API) recreateDevcontainer(dc codersdk.WorkspaceAgentDevcontainer, con
 		}
 	}
 	dc.Dirty = false
+	dc.Error = ""
 	api.recreateSuccessTimes[dc.WorkspaceFolder] = api.clock.Now("agentcontainers", "recreate", "successTimes")
 	api.knownDevcontainers[dc.WorkspaceFolder] = dc
+	api.broadcastUpdatesLocked()
 	api.mu.Unlock()
 
 	// Ensure an immediate refresh to accurately reflect the
 	// devcontainer state after recreation.
 	if err := api.RefreshContainers(ctx); err != nil {
-		logger.Error(ctx, "failed to trigger immediate refresh after devcontainer recreation", slog.Error(err))
+		logger.Error(ctx, "failed to trigger immediate refresh after devcontainer creation", slog.Error(err))
+		return xerrors.Errorf("refresh containers: %w", err)
 	}
+
+	return nil
 }
 
 // markDevcontainerDirty finds the devcontainer with the given config file path
@@ -1259,6 +1646,7 @@ func (api *API) maybeInjectSubAgentIntoContainerLocked(ctx context.Context, dc c
 		}
 
 		var (
+			featureOptionsAsEnvs       []string
 			appsWithPossibleDuplicates []SubAgentApp
 			workspaceFolder            = DevcontainerDefaultContainerWorkspaceFolder
 		)
@@ -1270,12 +1658,16 @@ func (api *API) maybeInjectSubAgentIntoContainerLocked(ctx context.Context, dc c
 			)
 
 			readConfig := func() (DevcontainerConfig, error) {
-				return api.dccli.ReadConfig(ctx, dc.WorkspaceFolder, dc.ConfigPath, []string{
-					fmt.Sprintf("CODER_WORKSPACE_AGENT_NAME=%s", subAgentConfig.Name),
-					fmt.Sprintf("CODER_WORKSPACE_OWNER_NAME=%s", api.ownerName),
-					fmt.Sprintf("CODER_WORKSPACE_NAME=%s", api.workspaceName),
-					fmt.Sprintf("CODER_URL=%s", api.subAgentURL),
-				})
+				return api.dccli.ReadConfig(ctx, dc.WorkspaceFolder, dc.ConfigPath,
+					append(featureOptionsAsEnvs, []string{
+						fmt.Sprintf("CODER_WORKSPACE_AGENT_NAME=%s", subAgentConfig.Name),
+						fmt.Sprintf("CODER_WORKSPACE_OWNER_NAME=%s", api.ownerName),
+						fmt.Sprintf("CODER_WORKSPACE_NAME=%s", api.workspaceName),
+						fmt.Sprintf("CODER_WORKSPACE_PARENT_AGENT_NAME=%s", api.parentAgent),
+						fmt.Sprintf("CODER_URL=%s", api.subAgentURL),
+						fmt.Sprintf("CONTAINER_ID=%s", container.ID),
+					}...),
+				)
 			}
 
 			if config, err = readConfig(); err != nil {
@@ -1291,6 +1683,11 @@ func (api *API) maybeInjectSubAgentIntoContainerLocked(ctx context.Context, dc c
 
 			workspaceFolder = config.Workspace.WorkspaceFolder
 
+			featureOptionsAsEnvs = config.MergedConfiguration.Features.OptionsAsEnvs()
+			if len(featureOptionsAsEnvs) > 0 {
+				configOutdated = true
+			}
+
 			// NOTE(DanielleMaywood):
 			// We only want to take an agent name specified in the root customization layer.
 			// This restricts the ability for a feature to specify the agent name. We may revisit
@@ -1415,6 +1812,11 @@ func (api *API) maybeInjectSubAgentIntoContainerLocked(ctx context.Context, dc c
 		return xerrors.Errorf("set agent binary executable: %w", err)
 	}
 
+	// Make sure the agent binary is owned by a valid user so we can run it.
+	if _, err := api.ccli.ExecAs(ctx, container.ID, "root", "/bin/sh", "-c", fmt.Sprintf("chown $(id -u):$(id -g) %s", coderPathInsideContainer)); err != nil {
+		return xerrors.Errorf("set agent binary ownership: %w", err)
+	}
+
 	// Attempt to add CAP_NET_ADMIN to the binary to improve network
 	// performance (optional, allow to fail). See `bootstrap_linux.sh`.
 	// TODO(mafredri): Disable for now until we can figure out why this
@@ -1452,7 +1854,9 @@ func (api *API) maybeInjectSubAgentIntoContainerLocked(ctx context.Context, dc c
 		originalName := subAgentConfig.Name
 
 		for attempt := 1; attempt <= maxAttemptsToNameAgent; attempt++ {
-			if proc.agent, err = client.Create(ctx, subAgentConfig); err == nil {
+			agent, err := client.Create(ctx, subAgentConfig)
+			if err == nil {
+				proc.agent = agent // Only reassign on success.
 				if api.usingWorkspaceFolderName[dc.WorkspaceFolder] {
 					api.devcontainerNames[dc.Name] = true
 					delete(api.usingWorkspaceFolderName, dc.WorkspaceFolder)
@@ -1460,7 +1864,6 @@ func (api *API) maybeInjectSubAgentIntoContainerLocked(ctx context.Context, dc c
 
 				break
 			}
-
 			// NOTE(DanielleMaywood):
 			// Ordinarily we'd use `errors.As` here, but it didn't appear to work. Not
 			// sure if this is because of the communication protocol? Instead I've opted
@@ -1609,8 +2012,15 @@ func (api *API) Close() error {
 	err := api.watcher.Close()
 
 	// Wait for loops to finish.
-	<-api.watcherDone
-	<-api.updaterDone
+	if api.watcherDone != nil {
+		<-api.watcherDone
+	}
+	if api.updaterDone != nil {
+		<-api.updaterDone
+	}
+	if api.discoverDone != nil {
+		<-api.discoverDone
+	}
 
 	// Wait for all async tasks to complete.
 	api.asyncWg.Wait()

agent/agentcontainers/containers_dockercli_test.go

@@ -55,11 +55,11 @@ func TestIntegrationDockerCLI(t *testing.T) {
 	}, testutil.WaitShort, testutil.IntervalSlow, "Container did not start in time")
 
 	dcli := agentcontainers.NewDockerCLI(agentexec.DefaultExecer)
-	ctx := testutil.Context(t, testutil.WaitMedium) // Longer timeout for multiple subtests
 	containerName := strings.TrimPrefix(ct.Container.Name, "/")
 
 	t.Run("DetectArchitecture", func(t *testing.T) {
 		t.Parallel()
+		ctx := testutil.Context(t, testutil.WaitShort)
 
 		arch, err := dcli.DetectArchitecture(ctx, containerName)
 		require.NoError(t, err, "DetectArchitecture failed")
@@ -71,6 +71,7 @@ func TestIntegrationDockerCLI(t *testing.T) {
 
 	t.Run("Copy", func(t *testing.T) {
 		t.Parallel()
+		ctx := testutil.Context(t, testutil.WaitShort)
 
 		want := "Help, I'm trapped!"
 		tempFile := filepath.Join(t.TempDir(), "test-file.txt")
@@ -90,6 +91,7 @@ func TestIntegrationDockerCLI(t *testing.T) {
 
 	t.Run("ExecAs", func(t *testing.T) {
 		t.Parallel()
+		ctx := testutil.Context(t, testutil.WaitShort)
 
 		// Test ExecAs without specifying user (should use container's default).
 		want := "root"

agent/agentcontainers/dcspec/gen.sh

@@ -61,7 +61,7 @@ fi
 exec 3>&-
 
 # Format the generated code.
-go run mvdan.cc/gofumpt@v0.4.0 -w -l "${TMPDIR}/${DEST_FILENAME}"
+go run mvdan.cc/gofumpt@v0.8.0 -w -l "${TMPDIR}/${DEST_FILENAME}"
 
 # Add a header so that Go recognizes this as a generated file.
 if grep -q -- "\[-i extension\]" < <(sed -h 2>&1); then

agent/agentcontainers/devcontainer.go

@@ -2,10 +2,10 @@ package agentcontainers
 
 import (
 	"context"
-	"fmt"
 	"os"
 	"path/filepath"
-	"strings"
+
+	"github.com/google/uuid"
 
 	"cdr.dev/slog"
 	"github.com/coder/coder/v2/codersdk"
@@ -18,37 +18,25 @@ const (
 	// DevcontainerConfigFileLabel is the label that contains the path to
 	// the devcontainer.json configuration file.
 	DevcontainerConfigFileLabel = "devcontainer.config_file"
+	// DevcontainerIsTestRunLabel is set if the devcontainer is part of a test
+	// and should be excluded.
+	DevcontainerIsTestRunLabel = "devcontainer.is_test_run"
 	// The default workspace folder inside the devcontainer.
 	DevcontainerDefaultContainerWorkspaceFolder = "/workspaces"
 )
 
-const devcontainerUpScriptTemplate = `
-if ! which devcontainer > /dev/null 2>&1; then
-  echo "ERROR: Unable to start devcontainer, @devcontainers/cli is not installed or not found in \$PATH." 1>&2
-  echo "Please install @devcontainers/cli by running \"npm install -g @devcontainers/cli\" or by using the \"devcontainers-cli\" Coder module." 1>&2
-  exit 1
-fi
-devcontainer up %s
-`
-
-// ExtractAndInitializeDevcontainerScripts extracts devcontainer scripts from
-// the given scripts and devcontainers. The devcontainer scripts are removed
-// from the returned scripts so that they can be run separately.
-//
-// Dev Containers have an inherent dependency on start scripts, since they
-// initialize the workspace (e.g. git clone, npm install, etc). This is
-// important if e.g. a Coder module to install @devcontainer/cli is used.
-func ExtractAndInitializeDevcontainerScripts(
+func ExtractDevcontainerScripts(
 	devcontainers []codersdk.WorkspaceAgentDevcontainer,
 	scripts []codersdk.WorkspaceAgentScript,
-) (filteredScripts []codersdk.WorkspaceAgentScript, devcontainerScripts []codersdk.WorkspaceAgentScript) {
+) (filteredScripts []codersdk.WorkspaceAgentScript, devcontainerScripts map[uuid.UUID]codersdk.WorkspaceAgentScript) {
+	devcontainerScripts = make(map[uuid.UUID]codersdk.WorkspaceAgentScript)
 ScriptLoop:
 	for _, script := range scripts {
 		for _, dc := range devcontainers {
 			// The devcontainer scripts match the devcontainer ID for
 			// identification.
 			if script.ID == dc.ID {
-				devcontainerScripts = append(devcontainerScripts, devcontainerStartupScript(dc, script))
+				devcontainerScripts[dc.ID] = script
 				continue ScriptLoop
 			}
 		}
@@ -59,24 +47,6 @@ ScriptLoop:
 	return filteredScripts, devcontainerScripts
 }
 
-func devcontainerStartupScript(dc codersdk.WorkspaceAgentDevcontainer, script codersdk.WorkspaceAgentScript) codersdk.WorkspaceAgentScript {
-	args := []string{
-		"--log-format json",
-		fmt.Sprintf("--workspace-folder %q", dc.WorkspaceFolder),
-	}
-	if dc.ConfigPath != "" {
-		args = append(args, fmt.Sprintf("--config %q", dc.ConfigPath))
-	}
-	cmd := fmt.Sprintf(devcontainerUpScriptTemplate, strings.Join(args, " "))
-	// Force the script to run in /bin/sh, since some shells (e.g. fish)
-	// don't support the script.
-	script.Script = fmt.Sprintf("/bin/sh -c '%s'", cmd)
-	// Disable RunOnStart, scripts have this set so that when devcontainers
-	// have not been enabled, a warning will be surfaced in the agent logs.
-	script.RunOnStart = false
-	return script
-}
-
 // ExpandAllDevcontainerPaths expands all devcontainer paths in the given
 // devcontainers. This is required by the devcontainer CLI, which requires
 // absolute paths for the workspace folder and config path.

agent/agentcontainers/devcontainer_test.go

@@ -1,274 +0,0 @@
-package agentcontainers_test
-
-import (
-	"path/filepath"
-	"strings"
-	"testing"
-
-	"github.com/google/go-cmp/cmp"
-	"github.com/google/go-cmp/cmp/cmpopts"
-	"github.com/google/uuid"
-	"github.com/stretchr/testify/require"
-
-	"cdr.dev/slog/sloggers/slogtest"
-	"github.com/coder/coder/v2/agent/agentcontainers"
-	"github.com/coder/coder/v2/codersdk"
-)
-
-func TestExtractAndInitializeDevcontainerScripts(t *testing.T) {
-	t.Parallel()
-
-	scriptIDs := []uuid.UUID{uuid.New(), uuid.New()}
-	devcontainerIDs := []uuid.UUID{uuid.New(), uuid.New()}
-
-	type args struct {
-		expandPath    func(string) (string, error)
-		devcontainers []codersdk.WorkspaceAgentDevcontainer
-		scripts       []codersdk.WorkspaceAgentScript
-	}
-	tests := []struct {
-		name                    string
-		args                    args
-		wantFilteredScripts     []codersdk.WorkspaceAgentScript
-		wantDevcontainerScripts []codersdk.WorkspaceAgentScript
-
-		skipOnWindowsDueToPathSeparator bool
-	}{
-		{
-			name: "no scripts",
-			args: args{
-				expandPath:    nil,
-				devcontainers: nil,
-				scripts:       nil,
-			},
-			wantFilteredScripts:     nil,
-			wantDevcontainerScripts: nil,
-		},
-		{
-			name: "no devcontainers",
-			args: args{
-				expandPath:    nil,
-				devcontainers: nil,
-				scripts: []codersdk.WorkspaceAgentScript{
-					{ID: scriptIDs[0]},
-					{ID: scriptIDs[1]},
-				},
-			},
-			wantFilteredScripts: []codersdk.WorkspaceAgentScript{
-				{ID: scriptIDs[0]},
-				{ID: scriptIDs[1]},
-			},
-			wantDevcontainerScripts: nil,
-		},
-		{
-			name: "no scripts match devcontainers",
-			args: args{
-				expandPath: nil,
-				devcontainers: []codersdk.WorkspaceAgentDevcontainer{
-					{ID: devcontainerIDs[0]},
-					{ID: devcontainerIDs[1]},
-				},
-				scripts: []codersdk.WorkspaceAgentScript{
-					{ID: scriptIDs[0]},
-					{ID: scriptIDs[1]},
-				},
-			},
-			wantFilteredScripts: []codersdk.WorkspaceAgentScript{
-				{ID: scriptIDs[0]},
-				{ID: scriptIDs[1]},
-			},
-			wantDevcontainerScripts: nil,
-		},
-		{
-			name: "scripts match devcontainers and sets RunOnStart=false",
-			args: args{
-				expandPath: nil,
-				devcontainers: []codersdk.WorkspaceAgentDevcontainer{
-					{ID: devcontainerIDs[0], WorkspaceFolder: "workspace1"},
-					{ID: devcontainerIDs[1], WorkspaceFolder: "workspace2"},
-				},
-				scripts: []codersdk.WorkspaceAgentScript{
-					{ID: scriptIDs[0], RunOnStart: true},
-					{ID: scriptIDs[1], RunOnStart: true},
-					{ID: devcontainerIDs[0], RunOnStart: true},
-					{ID: devcontainerIDs[1], RunOnStart: true},
-				},
-			},
-			wantFilteredScripts: []codersdk.WorkspaceAgentScript{
-				{ID: scriptIDs[0], RunOnStart: true},
-				{ID: scriptIDs[1], RunOnStart: true},
-			},
-			wantDevcontainerScripts: []codersdk.WorkspaceAgentScript{
-				{
-					ID:         devcontainerIDs[0],
-					Script:     "devcontainer up --log-format json --workspace-folder \"workspace1\"",
-					RunOnStart: false,
-				},
-				{
-					ID:         devcontainerIDs[1],
-					Script:     "devcontainer up --log-format json --workspace-folder \"workspace2\"",
-					RunOnStart: false,
-				},
-			},
-		},
-		{
-			name: "scripts match devcontainers with config path",
-			args: args{
-				expandPath: nil,
-				devcontainers: []codersdk.WorkspaceAgentDevcontainer{
-					{
-						ID:              devcontainerIDs[0],
-						WorkspaceFolder: "workspace1",
-						ConfigPath:      "config1",
-					},
-					{
-						ID:              devcontainerIDs[1],
-						WorkspaceFolder: "workspace2",
-						ConfigPath:      "config2",
-					},
-				},
-				scripts: []codersdk.WorkspaceAgentScript{
-					{ID: devcontainerIDs[0]},
-					{ID: devcontainerIDs[1]},
-				},
-			},
-			wantFilteredScripts: []codersdk.WorkspaceAgentScript{},
-			wantDevcontainerScripts: []codersdk.WorkspaceAgentScript{
-				{
-					ID:         devcontainerIDs[0],
-					Script:     "devcontainer up --log-format json --workspace-folder \"workspace1\" --config \"workspace1/config1\"",
-					RunOnStart: false,
-				},
-				{
-					ID:         devcontainerIDs[1],
-					Script:     "devcontainer up --log-format json --workspace-folder \"workspace2\" --config \"workspace2/config2\"",
-					RunOnStart: false,
-				},
-			},
-			skipOnWindowsDueToPathSeparator: true,
-		},
-		{
-			name: "scripts match devcontainers with expand path",
-			args: args{
-				expandPath: func(s string) (string, error) {
-					return "/home/" + s, nil
-				},
-				devcontainers: []codersdk.WorkspaceAgentDevcontainer{
-					{
-						ID:              devcontainerIDs[0],
-						WorkspaceFolder: "workspace1",
-						ConfigPath:      "config1",
-					},
-					{
-						ID:              devcontainerIDs[1],
-						WorkspaceFolder: "workspace2",
-						ConfigPath:      "config2",
-					},
-				},
-				scripts: []codersdk.WorkspaceAgentScript{
-					{ID: devcontainerIDs[0], RunOnStart: true},
-					{ID: devcontainerIDs[1], RunOnStart: true},
-				},
-			},
-			wantFilteredScripts: []codersdk.WorkspaceAgentScript{},
-			wantDevcontainerScripts: []codersdk.WorkspaceAgentScript{
-				{
-					ID:         devcontainerIDs[0],
-					Script:     "devcontainer up --log-format json --workspace-folder \"/home/workspace1\" --config \"/home/workspace1/config1\"",
-					RunOnStart: false,
-				},
-				{
-					ID:         devcontainerIDs[1],
-					Script:     "devcontainer up --log-format json --workspace-folder \"/home/workspace2\" --config \"/home/workspace2/config2\"",
-					RunOnStart: false,
-				},
-			},
-			skipOnWindowsDueToPathSeparator: true,
-		},
-		{
-			name: "expand config path when ~",
-			args: args{
-				expandPath: func(s string) (string, error) {
-					s = strings.Replace(s, "~/", "", 1)
-					if filepath.IsAbs(s) {
-						return s, nil
-					}
-					return "/home/" + s, nil
-				},
-				devcontainers: []codersdk.WorkspaceAgentDevcontainer{
-					{
-						ID:              devcontainerIDs[0],
-						WorkspaceFolder: "workspace1",
-						ConfigPath:      "~/config1",
-					},
-					{
-						ID:              devcontainerIDs[1],
-						WorkspaceFolder: "workspace2",
-						ConfigPath:      "/config2",
-					},
-				},
-				scripts: []codersdk.WorkspaceAgentScript{
-					{ID: devcontainerIDs[0], RunOnStart: true},
-					{ID: devcontainerIDs[1], RunOnStart: true},
-				},
-			},
-			wantFilteredScripts: []codersdk.WorkspaceAgentScript{},
-			wantDevcontainerScripts: []codersdk.WorkspaceAgentScript{
-				{
-					ID:         devcontainerIDs[0],
-					Script:     "devcontainer up --log-format json --workspace-folder \"/home/workspace1\" --config \"/home/config1\"",
-					RunOnStart: false,
-				},
-				{
-					ID:         devcontainerIDs[1],
-					Script:     "devcontainer up --log-format json --workspace-folder \"/home/workspace2\" --config \"/config2\"",
-					RunOnStart: false,
-				},
-			},
-			skipOnWindowsDueToPathSeparator: true,
-		},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			t.Parallel()
-			if tt.skipOnWindowsDueToPathSeparator && filepath.Separator == '\\' {
-				t.Skip("Skipping test on Windows due to path separator difference.")
-			}
-
-			logger := slogtest.Make(t, nil)
-			if tt.args.expandPath == nil {
-				tt.args.expandPath = func(s string) (string, error) {
-					return s, nil
-				}
-			}
-			gotFilteredScripts, gotDevcontainerScripts := agentcontainers.ExtractAndInitializeDevcontainerScripts(
-				agentcontainers.ExpandAllDevcontainerPaths(logger, tt.args.expandPath, tt.args.devcontainers),
-				tt.args.scripts,
-			)
-
-			if diff := cmp.Diff(tt.wantFilteredScripts, gotFilteredScripts, cmpopts.EquateEmpty()); diff != "" {
-				t.Errorf("ExtractAndInitializeDevcontainerScripts() gotFilteredScripts mismatch (-want +got):\n%s", diff)
-			}
-
-			// Preprocess the devcontainer scripts to remove scripting part.
-			for i := range gotDevcontainerScripts {
-				gotDevcontainerScripts[i].Script = textGrep("devcontainer up", gotDevcontainerScripts[i].Script)
-				require.NotEmpty(t, gotDevcontainerScripts[i].Script, "devcontainer up script not found")
-			}
-			if diff := cmp.Diff(tt.wantDevcontainerScripts, gotDevcontainerScripts); diff != "" {
-				t.Errorf("ExtractAndInitializeDevcontainerScripts() gotDevcontainerScripts mismatch (-want +got):\n%s", diff)
-			}
-		})
-	}
-}
-
-// textGrep returns matching lines from multiline string.
-func textGrep(want, got string) (filtered string) {
-	var lines []string
-	for _, line := range strings.Split(got, "\n") {
-		if strings.Contains(line, want) {
-			lines = append(lines, line)
-		}
-	}
-	return strings.Join(lines, "\n")
-}

agent/agentcontainers/devcontainercli.go

@@ -6,7 +6,10 @@ import (
 	"context"
 	"encoding/json"
 	"errors"
+	"fmt"
 	"io"
+	"slices"
+	"strings"
 
 	"golang.org/x/xerrors"
 
@@ -26,12 +29,55 @@ type DevcontainerConfig struct {
 
 type DevcontainerMergedConfiguration struct {
 	Customizations DevcontainerMergedCustomizations `json:"customizations,omitempty"`
+	Features       DevcontainerFeatures             `json:"features,omitempty"`
 }
 
 type DevcontainerMergedCustomizations struct {
 	Coder []CoderCustomization `json:"coder,omitempty"`
 }
 
+type DevcontainerFeatures map[string]any
+
+// OptionsAsEnvs converts the DevcontainerFeatures into a list of
+// environment variables that can be used to set feature options.
+// The format is FEATURE_<FEATURE_NAME>_OPTION_<OPTION_NAME>=<value>.
+// For example, if the feature is:
+//
+//		"ghcr.io/coder/devcontainer-features/code-server:1": {
+//	   "port": 9090,
+//	 }
+//
+// It will produce:
+//
+//	FEATURE_CODE_SERVER_OPTION_PORT=9090
+//
+// Note that the feature name is derived from the last part of the key,
+// so "ghcr.io/coder/devcontainer-features/code-server:1" becomes
+// "CODE_SERVER". The version part (e.g. ":1") is removed, and dashes in
+// the feature and option names are replaced with underscores.
+func (f DevcontainerFeatures) OptionsAsEnvs() []string {
+	var env []string
+	for k, v := range f {
+		vv, ok := v.(map[string]any)
+		if !ok {
+			continue
+		}
+		// Take the last part of the key as the feature name/path.
+		k = k[strings.LastIndex(k, "/")+1:]
+		// Remove ":" and anything following it.
+		if idx := strings.Index(k, ":"); idx != -1 {
+			k = k[:idx]
+		}
+		k = strings.ReplaceAll(k, "-", "_")
+		for k2, v2 := range vv {
+			k2 = strings.ReplaceAll(k2, "-", "_")
+			env = append(env, fmt.Sprintf("FEATURE_%s_OPTION_%s=%s", strings.ToUpper(k), strings.ToUpper(k2), fmt.Sprintf("%v", v2)))
+		}
+	}
+	slices.Sort(env)
+	return env
+}
+
 type DevcontainerConfiguration struct {
 	Customizations DevcontainerCustomizations `json:"customizations,omitempty"`
 }
@@ -45,6 +91,7 @@ type CoderCustomization struct {
 	Apps        []SubAgentApp                `json:"apps,omitempty"`
 	Name        string                       `json:"name,omitempty"`
 	Ignore      bool                         `json:"ignore,omitempty"`
+	AutoStart   bool                         `json:"autoStart,omitempty"`
 }
 
 type DevcontainerWorkspace struct {
@@ -60,63 +107,63 @@ type DevcontainerCLI interface {
 
 // DevcontainerCLIUpOptions are options for the devcontainer CLI Up
 // command.
-type DevcontainerCLIUpOptions func(*devcontainerCLIUpConfig)
+type DevcontainerCLIUpOptions func(*DevcontainerCLIUpConfig)
 
-type devcontainerCLIUpConfig struct {
-	args   []string // Additional arguments for the Up command.
-	stdout io.Writer
-	stderr io.Writer
+type DevcontainerCLIUpConfig struct {
+	Args   []string // Additional arguments for the Up command.
+	Stdout io.Writer
+	Stderr io.Writer
 }
 
 // WithRemoveExistingContainer is an option to remove the existing
 // container.
 func WithRemoveExistingContainer() DevcontainerCLIUpOptions {
-	return func(o *devcontainerCLIUpConfig) {
-		o.args = append(o.args, "--remove-existing-container")
+	return func(o *DevcontainerCLIUpConfig) {
+		o.Args = append(o.Args, "--remove-existing-container")
 	}
 }
 
 // WithUpOutput sets additional stdout and stderr writers for logs
 // during Up operations.
 func WithUpOutput(stdout, stderr io.Writer) DevcontainerCLIUpOptions {
-	return func(o *devcontainerCLIUpConfig) {
-		o.stdout = stdout
-		o.stderr = stderr
+	return func(o *DevcontainerCLIUpConfig) {
+		o.Stdout = stdout
+		o.Stderr = stderr
 	}
 }
 
 // DevcontainerCLIExecOptions are options for the devcontainer CLI Exec
 // command.
-type DevcontainerCLIExecOptions func(*devcontainerCLIExecConfig)
+type DevcontainerCLIExecOptions func(*DevcontainerCLIExecConfig)
 
-type devcontainerCLIExecConfig struct {
-	args   []string // Additional arguments for the Exec command.
-	stdout io.Writer
-	stderr io.Writer
+type DevcontainerCLIExecConfig struct {
+	Args   []string // Additional arguments for the Exec command.
+	Stdout io.Writer
+	Stderr io.Writer
 }
 
 // WithExecOutput sets additional stdout and stderr writers for logs
 // during Exec operations.
 func WithExecOutput(stdout, stderr io.Writer) DevcontainerCLIExecOptions {
-	return func(o *devcontainerCLIExecConfig) {
-		o.stdout = stdout
-		o.stderr = stderr
+	return func(o *DevcontainerCLIExecConfig) {
+		o.Stdout = stdout
+		o.Stderr = stderr
 	}
 }
 
 // WithExecContainerID sets the container ID to target a specific
 // container.
 func WithExecContainerID(id string) DevcontainerCLIExecOptions {
-	return func(o *devcontainerCLIExecConfig) {
-		o.args = append(o.args, "--container-id", id)
+	return func(o *DevcontainerCLIExecConfig) {
+		o.Args = append(o.Args, "--container-id", id)
 	}
 }
 
 // WithRemoteEnv sets environment variables for the Exec command.
 func WithRemoteEnv(env ...string) DevcontainerCLIExecOptions {
-	return func(o *devcontainerCLIExecConfig) {
+	return func(o *DevcontainerCLIExecConfig) {
 		for _, e := range env {
-			o.args = append(o.args, "--remote-env", e)
+			o.Args = append(o.Args, "--remote-env", e)
 		}
 	}
 }
@@ -139,8 +186,8 @@ func WithReadConfigOutput(stdout, stderr io.Writer) DevcontainerCLIReadConfigOpt
 	}
 }
 
-func applyDevcontainerCLIUpOptions(opts []DevcontainerCLIUpOptions) devcontainerCLIUpConfig {
-	conf := devcontainerCLIUpConfig{}
+func applyDevcontainerCLIUpOptions(opts []DevcontainerCLIUpOptions) DevcontainerCLIUpConfig {
+	conf := DevcontainerCLIUpConfig{Stdout: io.Discard, Stderr: io.Discard}
 	for _, opt := range opts {
 		if opt != nil {
 			opt(&conf)
@@ -149,8 +196,8 @@ func applyDevcontainerCLIUpOptions(opts []DevcontainerCLIUpOptions) devcontainer
 	return conf
 }
 
-func applyDevcontainerCLIExecOptions(opts []DevcontainerCLIExecOptions) devcontainerCLIExecConfig {
-	conf := devcontainerCLIExecConfig{}
+func applyDevcontainerCLIExecOptions(opts []DevcontainerCLIExecOptions) DevcontainerCLIExecConfig {
+	conf := DevcontainerCLIExecConfig{Stdout: io.Discard, Stderr: io.Discard}
 	for _, opt := range opts {
 		if opt != nil {
 			opt(&conf)
@@ -160,7 +207,7 @@ func applyDevcontainerCLIExecOptions(opts []DevcontainerCLIExecOptions) devconta
 }
 
 func applyDevcontainerCLIReadConfigOptions(opts []DevcontainerCLIReadConfigOptions) devcontainerCLIReadConfigConfig {
-	conf := devcontainerCLIReadConfigConfig{}
+	conf := devcontainerCLIReadConfigConfig{stdout: io.Discard, stderr: io.Discard}
 	for _, opt := range opts {
 		if opt != nil {
 			opt(&conf)
@@ -195,22 +242,25 @@ func (d *devcontainerCLI) Up(ctx context.Context, workspaceFolder, configPath st
 	if configPath != "" {
 		args = append(args, "--config", configPath)
 	}
-	args = append(args, conf.args...)
+	args = append(args, conf.Args...)
 	cmd := d.execer.CommandContext(ctx, "devcontainer", args...)
 
 	// Capture stdout for parsing and stream logs for both default and provided writers.
 	var stdoutBuf bytes.Buffer
-	stdoutWriters := []io.Writer{&stdoutBuf, &devcontainerCLILogWriter{ctx: ctx, logger: logger.With(slog.F("stdout", true))}}
-	if conf.stdout != nil {
-		stdoutWriters = append(stdoutWriters, conf.stdout)
-	}
-	cmd.Stdout = io.MultiWriter(stdoutWriters...)
+	cmd.Stdout = io.MultiWriter(
+		&stdoutBuf,
+		&devcontainerCLILogWriter{
+			ctx:    ctx,
+			logger: logger.With(slog.F("stdout", true)),
+			writer: conf.Stdout,
+		},
+	)
 	// Stream stderr logs and provided writer if any.
-	stderrWriters := []io.Writer{&devcontainerCLILogWriter{ctx: ctx, logger: logger.With(slog.F("stderr", true))}}
-	if conf.stderr != nil {
-		stderrWriters = append(stderrWriters, conf.stderr)
+	cmd.Stderr = &devcontainerCLILogWriter{
+		ctx:    ctx,
+		logger: logger.With(slog.F("stderr", true)),
+		writer: conf.Stderr,
 	}
-	cmd.Stderr = io.MultiWriter(stderrWriters...)
 
 	if err := cmd.Run(); err != nil {
 		_, err2 := parseDevcontainerCLILastLine[devcontainerCLIResult](ctx, logger, stdoutBuf.Bytes())
@@ -244,21 +294,21 @@ func (d *devcontainerCLI) Exec(ctx context.Context, workspaceFolder, configPath
 	if configPath != "" {
 		args = append(args, "--config", configPath)
 	}
-	args = append(args, conf.args...)
+	args = append(args, conf.Args...)
 	args = append(args, cmd)
 	args = append(args, cmdArgs...)
 	c := d.execer.CommandContext(ctx, "devcontainer", args...)
 
-	stdoutWriters := []io.Writer{&devcontainerCLILogWriter{ctx: ctx, logger: logger.With(slog.F("stdout", true))}}
-	if conf.stdout != nil {
-		stdoutWriters = append(stdoutWriters, conf.stdout)
-	}
-	c.Stdout = io.MultiWriter(stdoutWriters...)
-	stderrWriters := []io.Writer{&devcontainerCLILogWriter{ctx: ctx, logger: logger.With(slog.F("stderr", true))}}
-	if conf.stderr != nil {
-		stderrWriters = append(stderrWriters, conf.stderr)
-	}
-	c.Stderr = io.MultiWriter(stderrWriters...)
+	c.Stdout = io.MultiWriter(conf.Stdout, &devcontainerCLILogWriter{
+		ctx:    ctx,
+		logger: logger.With(slog.F("stdout", true)),
+		writer: io.Discard,
+	})
+	c.Stderr = io.MultiWriter(conf.Stderr, &devcontainerCLILogWriter{
+		ctx:    ctx,
+		logger: logger.With(slog.F("stderr", true)),
+		writer: io.Discard,
+	})
 
 	if err := c.Run(); err != nil {
 		return xerrors.Errorf("devcontainer exec failed: %w", err)
@@ -283,16 +333,19 @@ func (d *devcontainerCLI) ReadConfig(ctx context.Context, workspaceFolder, confi
 	c.Env = append(c.Env, env...)
 
 	var stdoutBuf bytes.Buffer
-	stdoutWriters := []io.Writer{&stdoutBuf, &devcontainerCLILogWriter{ctx: ctx, logger: logger.With(slog.F("stdout", true))}}
-	if conf.stdout != nil {
-		stdoutWriters = append(stdoutWriters, conf.stdout)
+	c.Stdout = io.MultiWriter(
+		&stdoutBuf,
+		&devcontainerCLILogWriter{
+			ctx:    ctx,
+			logger: logger.With(slog.F("stdout", true)),
+			writer: conf.stdout,
+		},
+	)
+	c.Stderr = &devcontainerCLILogWriter{
+		ctx:    ctx,
+		logger: logger.With(slog.F("stderr", true)),
+		writer: conf.stderr,
 	}
-	c.Stdout = io.MultiWriter(stdoutWriters...)
-	stderrWriters := []io.Writer{&devcontainerCLILogWriter{ctx: ctx, logger: logger.With(slog.F("stderr", true))}}
-	if conf.stderr != nil {
-		stderrWriters = append(stderrWriters, conf.stderr)
-	}
-	c.Stderr = io.MultiWriter(stderrWriters...)
 
 	if err := c.Run(); err != nil {
 		return DevcontainerConfig{}, xerrors.Errorf("devcontainer read-configuration failed: %w", err)
@@ -385,6 +438,7 @@ type devcontainerCLIJSONLogLine struct {
 type devcontainerCLILogWriter struct {
 	ctx    context.Context
 	logger slog.Logger
+	writer io.Writer
 }
 
 func (l *devcontainerCLILogWriter) Write(p []byte) (n int, err error) {
@@ -405,8 +459,20 @@ func (l *devcontainerCLILogWriter) Write(p []byte) (n int, err error) {
 		}
 		if logLine.Level >= 3 {
 			l.logger.Info(l.ctx, "@devcontainer/cli", slog.F("line", string(line)))
+			_, _ = l.writer.Write([]byte(strings.TrimSpace(logLine.Text) + "\n"))
 			continue
 		}
+		// If we've successfully parsed the final log line, it will successfully parse
+		// but will not fill out any of the fields for `logLine`. In this scenario we
+		// assume it is the final log line, unmarshal it as that, and check if the
+		// outcome is a non-empty string.
+		if logLine.Level == 0 {
+			var lastLine devcontainerCLIResult
+			if err := json.Unmarshal(line, &lastLine); err == nil && lastLine.Outcome != "" {
+				_, _ = l.writer.Write(line)
+				_, _ = l.writer.Write([]byte{'\n'})
+			}
+		}
 		l.logger.Debug(l.ctx, "@devcontainer/cli", slog.F("line", string(line)))
 	}
 	if err := s.Err(); err != nil {

agent/agentcontainers/devcontainercli_test.go

@@ -3,6 +3,7 @@ package agentcontainers_test
 import (
 	"bytes"
 	"context"
+	"encoding/json"
 	"errors"
 	"flag"
 	"fmt"
@@ -10,9 +11,11 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"runtime"
 	"strings"
 	"testing"
 
+	"github.com/google/go-cmp/cmp"
 	"github.com/ory/dockertest/v3"
 	"github.com/ory/dockertest/v3/docker"
 	"github.com/stretchr/testify/assert"
@@ -341,6 +344,10 @@ func TestDevcontainerCLI_WithOutput(t *testing.T) {
 	t.Run("Up", func(t *testing.T) {
 		t.Parallel()
 
+		if runtime.GOOS == "windows" {
+			t.Skip("Windows uses CRLF line endings, golden file is LF")
+		}
+
 		// Buffers to capture stdout and stderr.
 		outBuf := &bytes.Buffer{}
 		errBuf := &bytes.Buffer{}
@@ -363,7 +370,7 @@ func TestDevcontainerCLI_WithOutput(t *testing.T) {
 		require.NotEmpty(t, containerID, "expected non-empty container ID")
 
 		// Read expected log content.
-		expLog, err := os.ReadFile(filepath.Join("testdata", "devcontainercli", "parse", "up.log"))
+		expLog, err := os.ReadFile(filepath.Join("testdata", "devcontainercli", "parse", "up.golden"))
 		require.NoError(t, err, "reading expected log file")
 
 		// Verify stdout buffer contains the CLI logs and stderr is empty.
@@ -586,7 +593,7 @@ func setupDevcontainerWorkspace(t *testing.T, workspaceFolder string) string {
 	"containerEnv": {
 		"TEST_CONTAINER": "true"
 	},
-	"runArgs": ["--label", "com.coder.test=devcontainercli"]
+	"runArgs": ["--label=com.coder.test=devcontainercli", "--label=` + agentcontainers.DevcontainerIsTestRunLabel + `=true"]
 }`
 	err = os.WriteFile(configPath, []byte(content), 0o600)
 	require.NoError(t, err, "create devcontainer.json file")
@@ -637,3 +644,107 @@ func removeDevcontainerByID(t *testing.T, pool *dockertest.Pool, id string) {
 		assert.NoError(t, err, "remove container failed")
 	}
 }
+
+func TestDevcontainerFeatures_OptionsAsEnvs(t *testing.T) {
+	t.Parallel()
+
+	realConfigJSON := `{
+		"mergedConfiguration": {
+			"features": {
+				"./code-server": {
+					"port": 9090
+				},
+				"ghcr.io/devcontainers/features/docker-in-docker:2": {
+					"moby": "false"
+				}
+			}
+		}
+	}`
+	var realConfig agentcontainers.DevcontainerConfig
+	err := json.Unmarshal([]byte(realConfigJSON), &realConfig)
+	require.NoError(t, err, "unmarshal JSON payload")
+
+	tests := []struct {
+		name     string
+		features agentcontainers.DevcontainerFeatures
+		want     []string
+	}{
+		{
+			name: "code-server feature",
+			features: agentcontainers.DevcontainerFeatures{
+				"./code-server": map[string]any{
+					"port": 9090,
+				},
+			},
+			want: []string{
+				"FEATURE_CODE_SERVER_OPTION_PORT=9090",
+			},
+		},
+		{
+			name: "docker-in-docker feature",
+			features: agentcontainers.DevcontainerFeatures{
+				"ghcr.io/devcontainers/features/docker-in-docker:2": map[string]any{
+					"moby": "false",
+				},
+			},
+			want: []string{
+				"FEATURE_DOCKER_IN_DOCKER_OPTION_MOBY=false",
+			},
+		},
+		{
+			name: "multiple features with multiple options",
+			features: agentcontainers.DevcontainerFeatures{
+				"./code-server": map[string]any{
+					"port":     9090,
+					"password": "secret",
+				},
+				"ghcr.io/devcontainers/features/docker-in-docker:2": map[string]any{
+					"moby":                        "false",
+					"docker-dash-compose-version": "v2",
+				},
+			},
+			want: []string{
+				"FEATURE_CODE_SERVER_OPTION_PASSWORD=secret",
+				"FEATURE_CODE_SERVER_OPTION_PORT=9090",
+				"FEATURE_DOCKER_IN_DOCKER_OPTION_DOCKER_DASH_COMPOSE_VERSION=v2",
+				"FEATURE_DOCKER_IN_DOCKER_OPTION_MOBY=false",
+			},
+		},
+		{
+			name: "feature with non-map value (should be ignored)",
+			features: agentcontainers.DevcontainerFeatures{
+				"./code-server": map[string]any{
+					"port": 9090,
+				},
+				"./invalid-feature": "not-a-map",
+			},
+			want: []string{
+				"FEATURE_CODE_SERVER_OPTION_PORT=9090",
+			},
+		},
+		{
+			name:     "real config example",
+			features: realConfig.MergedConfiguration.Features,
+			want: []string{
+				"FEATURE_CODE_SERVER_OPTION_PORT=9090",
+				"FEATURE_DOCKER_IN_DOCKER_OPTION_MOBY=false",
+			},
+		},
+		{
+			name:     "empty features",
+			features: agentcontainers.DevcontainerFeatures{},
+			want:     nil,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			got := tt.features.OptionsAsEnvs()
+			if diff := cmp.Diff(tt.want, got); diff != "" {
+				require.Failf(t, "OptionsAsEnvs() mismatch (-want +got):\n%s", diff)
+			}
+		})
+	}
+}

agent/agentcontainers/ignore/dir.go

@@ -0,0 +1,124 @@
+package ignore
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/go-git/go-git/v5/plumbing/format/config"
+	"github.com/go-git/go-git/v5/plumbing/format/gitignore"
+	"github.com/spf13/afero"
+	"golang.org/x/xerrors"
+
+	"cdr.dev/slog"
+)
+
+const (
+	gitconfigFile      = ".gitconfig"
+	gitignoreFile      = ".gitignore"
+	gitInfoExcludeFile = ".git/info/exclude"
+)
+
+func FilePathToParts(path string) []string {
+	components := []string{}
+
+	if path == "" {
+		return components
+	}
+
+	for segment := range strings.SplitSeq(filepath.Clean(path), string(filepath.Separator)) {
+		if segment != "" {
+			components = append(components, segment)
+		}
+	}
+
+	return components
+}
+
+func readIgnoreFile(fileSystem afero.Fs, path, ignore string) ([]gitignore.Pattern, error) {
+	var ps []gitignore.Pattern
+
+	data, err := afero.ReadFile(fileSystem, filepath.Join(path, ignore))
+	if err != nil && !errors.Is(err, os.ErrNotExist) {
+		return nil, err
+	}
+
+	for s := range strings.SplitSeq(string(data), "\n") {
+		if !strings.HasPrefix(s, "#") && len(strings.TrimSpace(s)) > 0 {
+			ps = append(ps, gitignore.ParsePattern(s, FilePathToParts(path)))
+		}
+	}
+
+	return ps, nil
+}
+
+func ReadPatterns(ctx context.Context, logger slog.Logger, fileSystem afero.Fs, path string) ([]gitignore.Pattern, error) {
+	var ps []gitignore.Pattern
+
+	subPs, err := readIgnoreFile(fileSystem, path, gitInfoExcludeFile)
+	if err != nil {
+		return nil, err
+	}
+
+	ps = append(ps, subPs...)
+
+	if err := afero.Walk(fileSystem, path, func(path string, info fs.FileInfo, err error) error {
+		if err != nil {
+			logger.Error(ctx, "encountered error while walking for git ignore files",
+				slog.F("path", path),
+				slog.Error(err))
+			return nil
+		}
+
+		if !info.IsDir() {
+			return nil
+		}
+
+		subPs, err := readIgnoreFile(fileSystem, path, gitignoreFile)
+		if err != nil {
+			return err
+		}
+
+		ps = append(ps, subPs...)
+
+		return nil
+	}); err != nil {
+		return nil, err
+	}
+
+	return ps, nil
+}
+
+func loadPatterns(fileSystem afero.Fs, path string) ([]gitignore.Pattern, error) {
+	data, err := afero.ReadFile(fileSystem, path)
+	if err != nil && !errors.Is(err, os.ErrNotExist) {
+		return nil, err
+	}
+
+	decoder := config.NewDecoder(bytes.NewBuffer(data))
+
+	conf := config.New()
+	if err := decoder.Decode(conf); err != nil {
+		return nil, xerrors.Errorf("decode config: %w", err)
+	}
+
+	excludes := conf.Section("core").Options.Get("excludesfile")
+	if excludes == "" {
+		return nil, nil
+	}
+
+	return readIgnoreFile(fileSystem, "", excludes)
+}
+
+func LoadGlobalPatterns(fileSystem afero.Fs) ([]gitignore.Pattern, error) {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return nil, err
+	}
+
+	return loadPatterns(fileSystem, filepath.Join(home, gitconfigFile))
+}

agent/agentcontainers/ignore/dir_test.go

@@ -0,0 +1,38 @@
+package ignore_test
+
+import (
+	"fmt"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/coder/coder/v2/agent/agentcontainers/ignore"
+)
+
+func TestFilePathToParts(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		path     string
+		expected []string
+	}{
+		{"", []string{}},
+		{"/", []string{}},
+		{"foo", []string{"foo"}},
+		{"/foo", []string{"foo"}},
+		{"./foo/bar", []string{"foo", "bar"}},
+		{"../foo/bar", []string{"..", "foo", "bar"}},
+		{"foo/bar/baz", []string{"foo", "bar", "baz"}},
+		{"/foo/bar/baz", []string{"foo", "bar", "baz"}},
+		{"foo/../bar", []string{"bar"}},
+	}
+
+	for _, tt := range tests {
+		t.Run(fmt.Sprintf("`%s`", tt.path), func(t *testing.T) {
+			t.Parallel()
+
+			parts := ignore.FilePathToParts(tt.path)
+			require.Equal(t, tt.expected, parts)
+		})
+	}
+}

agent/agentcontainers/subagent.go

@@ -188,7 +188,7 @@ func (a *subAgentAPIClient) List(ctx context.Context) ([]SubAgent, error) {
 	return agents, nil
 }
 
-func (a *subAgentAPIClient) Create(ctx context.Context, agent SubAgent) (SubAgent, error) {
+func (a *subAgentAPIClient) Create(ctx context.Context, agent SubAgent) (_ SubAgent, err error) {
 	a.logger.Debug(ctx, "creating sub agent", slog.F("name", agent.Name), slog.F("directory", agent.Directory))
 
 	displayApps := make([]agentproto.CreateSubAgentRequest_DisplayApp, 0, len(agent.DisplayApps))
@@ -233,19 +233,27 @@ func (a *subAgentAPIClient) Create(ctx context.Context, agent SubAgent) (SubAgen
 	if err != nil {
 		return SubAgent{}, err
 	}
+	defer func() {
+		if err != nil {
+			// Best effort.
+			_, _ = a.api.DeleteSubAgent(ctx, &agentproto.DeleteSubAgentRequest{
+				Id: resp.GetAgent().GetId(),
+			})
+		}
+	}()
 
-	agent.Name = resp.Agent.Name
-	agent.ID, err = uuid.FromBytes(resp.Agent.Id)
+	agent.Name = resp.GetAgent().GetName()
+	agent.ID, err = uuid.FromBytes(resp.GetAgent().GetId())
 	if err != nil {
-		return agent, err
+		return SubAgent{}, err
 	}
-	agent.AuthToken, err = uuid.FromBytes(resp.Agent.AuthToken)
+	agent.AuthToken, err = uuid.FromBytes(resp.GetAgent().GetAuthToken())
 	if err != nil {
-		return agent, err
+		return SubAgent{}, err
 	}
 
-	for _, appError := range resp.AppCreationErrors {
-		app := apps[appError.Index]
+	for _, appError := range resp.GetAppCreationErrors() {
+		app := apps[appError.GetIndex()]
 
 		a.logger.Warn(ctx, "unable to create app",
 			slog.F("agent_name", agent.Name),

agent/agentcontainers/testdata/devcontainercli/parse/up.golden

@@ -0,0 +1,64 @@
+@devcontainers/cli 0.75.0. Node.js v23.9.0. darwin 24.4.0 arm64.
+Resolving Feature dependencies for 'ghcr.io/devcontainers/features/docker-in-docker:2'...
+Soft-dependency 'ghcr.io/devcontainers/features/common-utils' is not required.  Removing from installation order...
+Files to omit: ''
+Run: docker buildx build --load --build-context dev_containers_feature_content_source=/var/folders/1y/cm8mblxd7_x9cljwl_jvfprh0000gn/T/devcontainercli/container-features/0.75.0-1744102171193 --build-arg _DEV_CONTAINERS_BASE_IMAGE=mcr.microsoft.com/devcontainers/javascript-node:1-18-bullseye --build-arg _DEV_CONTAINERS_IMAGE_USER=root --build-arg _DEV_CONTAINERS_FEATURE_CONTENT_SOURCE=dev_container_feature_content_temp --target dev_containers_target_stage -f /var/folders/1y/cm8mblxd7_x9cljwl_jvfprh0000gn/T/devcontainercli/container-features/0.75.0-1744102171193/Dockerfile.extended -t vsc-devcontainers-template-starter-81d8f17e32abef6d434cbb5a37fe05e5c8a6f8ccede47a61197f002dcbf60566-features /var/folders/1y/cm8mblxd7_x9cljwl_jvfprh0000gn/T/devcontainercli/empty-folder
+#0 building with "orbstack" instance using docker driver
+
+#1 [internal] load build definition from Dockerfile.extended
+#1 transferring dockerfile: 3.09kB done
+#1 DONE 0.0s
+
+#2 resolve image config for docker-image://docker.io/docker/dockerfile:1.4
+#2 DONE 1.3s
+#3 docker-image://docker.io/docker/dockerfile:1.4@sha256:9ba7531bd80fb0a858632727cf7a112fbfd19b17e94c4e84ced81e24ef1a0dbc
+#3 CACHED
+
+#4 [internal] load .dockerignore
+#4 transferring context: 2B done
+#4 DONE 0.0s
+
+#5 [internal] load metadata for mcr.microsoft.com/devcontainers/javascript-node:1-18-bullseye
+#5 DONE 0.0s
+
+#6 [context dev_containers_feature_content_source] load .dockerignore
+#6 transferring dev_containers_feature_content_source: 2B done
+#6 DONE 0.0s
+
+#7 [dev_containers_feature_content_normalize 1/3] FROM mcr.microsoft.com/devcontainers/javascript-node:1-18-bullseye
+#7 DONE 0.0s
+
+#8 [context dev_containers_feature_content_source] load from client
+#8 transferring dev_containers_feature_content_source: 82.11kB 0.0s done
+#8 DONE 0.0s
+
+#9 [dev_containers_feature_content_normalize 2/3] COPY --from=dev_containers_feature_content_source devcontainer-features.builtin.env /tmp/build-features/
+#9 CACHED
+
+#10 [dev_containers_target_stage 2/5] RUN mkdir -p /tmp/dev-container-features
+#10 CACHED
+
+#11 [dev_containers_target_stage 3/5] COPY --from=dev_containers_feature_content_normalize /tmp/build-features/ /tmp/dev-container-features
+#11 CACHED
+
+#12 [dev_containers_target_stage 4/5] RUN echo "_CONTAINER_USER_HOME=$( (command -v getent >/dev/null 2>&1 && getent passwd 'root' || grep -E '^root|^[^:]*:[^:]*:root:' /etc/passwd || true) | cut -d: -f6)" >> /tmp/dev-container-features/devcontainer-features.builtin.env && echo "_REMOTE_USER_HOME=$( (command -v getent >/dev/null 2>&1 && getent passwd 'node' || grep -E '^node|^[^:]*:[^:]*:node:' /etc/passwd || true) | cut -d: -f6)" >> /tmp/dev-container-features/devcontainer-features.builtin.env
+#12 CACHED
+
+#13 [dev_containers_feature_content_normalize 3/3] RUN chmod -R 0755 /tmp/build-features/
+#13 CACHED
+
+#14 [dev_containers_target_stage 5/5] RUN --mount=type=bind,from=dev_containers_feature_content_source,source=docker-in-docker_0,target=/tmp/build-features-src/docker-in-docker_0     cp -ar /tmp/build-features-src/docker-in-docker_0 /tmp/dev-container-features  && chmod -R 0755 /tmp/dev-container-features/docker-in-docker_0  && cd /tmp/dev-container-features/docker-in-docker_0  && chmod +x ./devcontainer-features-install.sh  && ./devcontainer-features-install.sh  && rm -rf /tmp/dev-container-features/docker-in-docker_0
+#14 CACHED
+
+#15 exporting to image
+#15 exporting layers done
+#15 writing image sha256:275dc193c905d448ef3945e3fc86220cc315fe0cb41013988d6ff9f8d6ef2357 done
+#15 naming to docker.io/library/vsc-devcontainers-template-starter-81d8f17e32abef6d434cbb5a37fe05e5c8a6f8ccede47a61197f002dcbf60566-features done
+#15 DONE 0.0s
+Run: docker buildx build --load --build-context dev_containers_feature_content_source=/var/folders/1y/cm8mblxd7_x9cljwl_jvfprh0000gn/T/devcontainercli/container-features/0.75.0-1744102171193 --build-arg _DEV_CONTAINERS_BASE_IMAGE=mcr.microsoft.com/devcontainers/javascript-node:1-18-bullseye --build-arg _DEV_CONTAINERS_IMAGE_USER=root --build-arg _DEV_CONTAINERS_FEATURE_CONTENT_SOURCE=dev_container_feature_content_temp --target dev_containers_target_stage -f /var/folders/1y/cm8mblxd7_x9cljwl_jvfprh0000gn/T/devcontainercli/container-features/0.75.0-1744102171193/Dockerfile.extended -t vsc-devcontainers-template-starter-81d8f17e32abef6d434cbb5a37fe05e5c8a6f8ccede47a61197f002dcbf60566-features /var/folders/1y/cm8mblxd7_x9cljwl_jvfprh0000gn/T/devcontainercli/empty-folder
+Run: docker run --sig-proxy=false -a STDOUT -a STDERR --mount type=bind,source=/code/devcontainers-template-starter,target=/workspaces/devcontainers-template-starter,consistency=cached --mount type=volume,src=dind-var-lib-docker-0pctifo8bbg3pd06g3j5s9ae8j7lp5qfcd67m25kuahurel7v7jm,dst=/var/lib/docker -l devcontainer.local_folder=/code/devcontainers-template-starter -l devcontainer.config_file=/code/devcontainers-template-starter/.devcontainer/devcontainer.json --privileged --entrypoint /bin/sh vsc-devcontainers-template-starter-81d8f17e32abef6d434cbb5a37fe05e5c8a6f8ccede47a61197f002dcbf60566-features -c echo Container started
+Container started
+Not setting dockerd DNS manually.
+Running the postCreateCommand from devcontainer.json...
+added 1 package in 784ms
+{"outcome":"success","containerId":"bc72db8d0c4c4e941bd9ffc341aee64a18d3397fd45b87cd93d4746150967ba8","remoteUser":"node","remoteWorkspaceFolder":"/workspaces/devcontainers-template-starter"}

agent/agentcontainers/watcher/watcher_test.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"os"
 	"path/filepath"
+	"runtime"
 	"testing"
 
 	"github.com/fsnotify/fsnotify"
@@ -88,24 +89,34 @@ func TestFSNotifyWatcher(t *testing.T) {
 		break
 	}
 
-	err = os.WriteFile(testFile+".atomic", []byte(`{"test": "atomic"}`), 0o600)
-	require.NoError(t, err, "write new atomic test file failed")
+	// TODO(DanielleMaywood):
+	// Unfortunately it appears this atomic-rename phase of the test is flakey on macOS.
+	//
+	// This test flake could be indicative of an issue that may present itself
+	// in a running environment. Fortunately, we only use this (as of 2025-07-29)
+	// for our dev container integration. We do not expect the host workspace
+	// (where this is used), to ever be run on macOS, as containers are a linux
+	// paradigm.
+	if runtime.GOOS != "darwin" {
+		err = os.WriteFile(testFile+".atomic", []byte(`{"test": "atomic"}`), 0o600)
+		require.NoError(t, err, "write new atomic test file failed")
 
-	err = os.Rename(testFile+".atomic", testFile)
-	require.NoError(t, err, "rename atomic test file failed")
+		err = os.Rename(testFile+".atomic", testFile)
+		require.NoError(t, err, "rename atomic test file failed")
 
-	// Verify that we receive the event we want.
-	for {
-		event, err := wut.Next(ctx)
-		require.NoError(t, err, "next event failed")
-		require.NotNil(t, event, "want non-nil event")
-		if !event.Has(fsnotify.Create) {
-			t.Logf("Ignoring event: %s", event)
-			continue
+		// Verify that we receive the event we want.
+		for {
+			event, err := wut.Next(ctx)
+			require.NoError(t, err, "next event failed")
+			require.NotNil(t, event, "want non-nil event")
+			if !event.Has(fsnotify.Create) {
+				t.Logf("Ignoring event: %s", event)
+				continue
+			}
+			require.Truef(t, event.Has(fsnotify.Create), "want create event: %s", event.String())
+			require.Equal(t, event.Name, testFile, "want event for test file")
+			break
 		}
-		require.Truef(t, event.Has(fsnotify.Create), "want create event: %s", event.String())
-		require.Equal(t, event.Name, testFile, "want event for test file")
-		break
 	}
 
 	// Test removing the file from the watcher.

agent/agentscripts/agentscripts.go

@@ -79,21 +79,6 @@ func New(opts Options) *Runner {
 
 type ScriptCompletedFunc func(context.Context, *proto.WorkspaceAgentScriptCompletedRequest) (*proto.WorkspaceAgentScriptCompletedResponse, error)
 
-type runnerScript struct {
-	runOnPostStart bool
-	codersdk.WorkspaceAgentScript
-}
-
-func toRunnerScript(scripts ...codersdk.WorkspaceAgentScript) []runnerScript {
-	var rs []runnerScript
-	for _, s := range scripts {
-		rs = append(rs, runnerScript{
-			WorkspaceAgentScript: s,
-		})
-	}
-	return rs
-}
-
 type Runner struct {
 	Options
 
@@ -103,7 +88,7 @@ type Runner struct {
 	closed          chan struct{}
 	closeMutex      sync.Mutex
 	cron            *cron.Cron
-	scripts         []runnerScript
+	scripts         []codersdk.WorkspaceAgentScript
 	dataDir         string
 	scriptCompleted ScriptCompletedFunc
 
@@ -138,19 +123,6 @@ func (r *Runner) RegisterMetrics(reg prometheus.Registerer) {
 // InitOption describes an option for the runner initialization.
 type InitOption func(*Runner)
 
-// WithPostStartScripts adds scripts that should be run after the workspace
-// start scripts but before the workspace is marked as started.
-func WithPostStartScripts(scripts ...codersdk.WorkspaceAgentScript) InitOption {
-	return func(r *Runner) {
-		for _, s := range scripts {
-			r.scripts = append(r.scripts, runnerScript{
-				runOnPostStart:       true,
-				WorkspaceAgentScript: s,
-			})
-		}
-	}
-}
-
 // Init initializes the runner with the provided scripts.
 // It also schedules any scripts that have a schedule.
 // This function must be called before Execute.
@@ -161,7 +133,7 @@ func (r *Runner) Init(scripts []codersdk.WorkspaceAgentScript, scriptCompleted S
 		return xerrors.New("init: already initialized")
 	}
 	r.initialized = true
-	r.scripts = toRunnerScript(scripts...)
+	r.scripts = scripts
 	r.scriptCompleted = scriptCompleted
 	for _, opt := range opts {
 		opt(r)
@@ -177,9 +149,8 @@ func (r *Runner) Init(scripts []codersdk.WorkspaceAgentScript, scriptCompleted S
 		if script.Cron == "" {
 			continue
 		}
-		script := script
 		_, err := r.cron.AddFunc(script.Cron, func() {
-			err := r.trackRun(r.cronCtx, script.WorkspaceAgentScript, ExecuteCronScripts)
+			err := r.trackRun(r.cronCtx, script, ExecuteCronScripts)
 			if err != nil {
 				r.Logger.Warn(context.Background(), "run agent script on schedule", slog.Error(err))
 			}
@@ -223,7 +194,6 @@ type ExecuteOption int
 const (
 	ExecuteAllScripts ExecuteOption = iota
 	ExecuteStartScripts
-	ExecutePostStartScripts
 	ExecuteStopScripts
 	ExecuteCronScripts
 )
@@ -246,7 +216,6 @@ func (r *Runner) Execute(ctx context.Context, option ExecuteOption) error {
 	for _, script := range r.scripts {
 		runScript := (option == ExecuteStartScripts && script.RunOnStart) ||
 			(option == ExecuteStopScripts && script.RunOnStop) ||
-			(option == ExecutePostStartScripts && script.runOnPostStart) ||
 			(option == ExecuteCronScripts && script.Cron != "") ||
 			option == ExecuteAllScripts
 
@@ -254,9 +223,8 @@ func (r *Runner) Execute(ctx context.Context, option ExecuteOption) error {
 			continue
 		}
 
-		script := script
 		eg.Go(func() error {
-			err := r.trackRun(ctx, script.WorkspaceAgentScript, option)
+			err := r.trackRun(ctx, script, option)
 			if err != nil {
 				return xerrors.Errorf("run agent script %q: %w", script.LogSourceID, err)
 			}

agent/agentscripts/agentscripts_test.go

@@ -4,7 +4,6 @@ import (
 	"context"
 	"path/filepath"
 	"runtime"
-	"slices"
 	"sync"
 	"testing"
 	"time"
@@ -177,11 +176,6 @@ func TestExecuteOptions(t *testing.T) {
 		Script:      "echo stop",
 		RunOnStop:   true,
 	}
-	postStartScript := codersdk.WorkspaceAgentScript{
-		ID:          uuid.New(),
-		LogSourceID: uuid.New(),
-		Script:      "echo poststart",
-	}
 	regularScript := codersdk.WorkspaceAgentScript{
 		ID:          uuid.New(),
 		LogSourceID: uuid.New(),
@@ -193,10 +187,9 @@ func TestExecuteOptions(t *testing.T) {
 		stopScript,
 		regularScript,
 	}
-	allScripts := append(slices.Clone(scripts), postStartScript)
 
 	scriptByID := func(t *testing.T, id uuid.UUID) codersdk.WorkspaceAgentScript {
-		for _, script := range allScripts {
+		for _, script := range scripts {
 			if script.ID == id {
 				return script
 			}
@@ -206,10 +199,9 @@ func TestExecuteOptions(t *testing.T) {
 	}
 
 	wantOutput := map[uuid.UUID]string{
-		startScript.ID:     "start",
-		stopScript.ID:      "stop",
-		postStartScript.ID: "poststart",
-		regularScript.ID:   "regular",
+		startScript.ID:   "start",
+		stopScript.ID:    "stop",
+		regularScript.ID: "regular",
 	}
 
 	testCases := []struct {
@@ -220,18 +212,13 @@ func TestExecuteOptions(t *testing.T) {
 		{
 			name:    "ExecuteAllScripts",
 			option:  agentscripts.ExecuteAllScripts,
-			wantRun: []uuid.UUID{startScript.ID, stopScript.ID, regularScript.ID, postStartScript.ID},
+			wantRun: []uuid.UUID{startScript.ID, stopScript.ID, regularScript.ID},
 		},
 		{
 			name:    "ExecuteStartScripts",
 			option:  agentscripts.ExecuteStartScripts,
 			wantRun: []uuid.UUID{startScript.ID},
 		},
-		{
-			name:    "ExecutePostStartScripts",
-			option:  agentscripts.ExecutePostStartScripts,
-			wantRun: []uuid.UUID{postStartScript.ID},
-		},
 		{
 			name:    "ExecuteStopScripts",
 			option:  agentscripts.ExecuteStopScripts,
@@ -260,7 +247,6 @@ func TestExecuteOptions(t *testing.T) {
 			err := runner.Init(
 				scripts,
 				aAPI.ScriptCompleted,
-				agentscripts.WithPostStartScripts(postStartScript),
 			)
 			require.NoError(t, err)
 
@@ -274,7 +260,7 @@ func TestExecuteOptions(t *testing.T) {
 					"script %s should have run when using filter %s", scriptByID(t, id).Script, tc.name)
 			}
 
-			for _, script := range allScripts {
+			for _, script := range scripts {
 				if _, ok := gotRun[script.ID]; ok {
 					continue
 				}

agent/agentssh/agentssh.go

@@ -46,6 +46,8 @@ const (
 	// MagicProcessCmdlineJetBrains is a string in a process's command line that
 	// uniquely identifies it as JetBrains software.
 	MagicProcessCmdlineJetBrains = "idea.vendor.name=JetBrains"
+	MagicProcessCmdlineToolbox   = "com.jetbrains.toolbox"
+	MagicProcessCmdlineGateway   = "remote-dev-server"
 
 	// BlockedFileTransferErrorCode indicates that SSH server restricted the raw command from performing
 	// the file transfer.
@@ -117,6 +119,10 @@ type Config struct {
 	// Note that this is different from the devcontainers feature, which uses
 	// subagents.
 	ExperimentalContainers bool
+	// X11Net allows overriding the networking implementation used for X11
+	// forwarding listeners. When nil, a default implementation backed by the
+	// standard library networking package is used.
+	X11Net X11Network
 }
 
 type Server struct {
@@ -125,14 +131,16 @@ type Server struct {
 	listeners map[net.Listener]struct{}
 	conns     map[net.Conn]struct{}
 	sessions  map[ssh.Session]struct{}
+	processes map[*os.Process]struct{}
 	closing   chan struct{}
 	// Wait for goroutines to exit, waited without
 	// a lock on mu but protected by closing.
 	wg sync.WaitGroup
 
-	Execer agentexec.Execer
-	logger slog.Logger
-	srv    *ssh.Server
+	Execer       agentexec.Execer
+	logger       slog.Logger
+	srv          *ssh.Server
+	x11Forwarder *x11Forwarder
 
 	config *Config
 
@@ -183,11 +191,26 @@ func NewServer(ctx context.Context, logger slog.Logger, prometheusRegistry *prom
 		fs:        fs,
 		conns:     make(map[net.Conn]struct{}),
 		sessions:  make(map[ssh.Session]struct{}),
+		processes: make(map[*os.Process]struct{}),
 		logger:    logger,
 
 		config: config,
 
 		metrics: metrics,
+		x11Forwarder: &x11Forwarder{
+			logger:           logger,
+			x11HandlerErrors: metrics.x11HandlerErrors,
+			fs:               fs,
+			displayOffset:    *config.X11DisplayOffset,
+			sessions:         make(map[*x11Session]struct{}),
+			connections:      make(map[net.Conn]struct{}),
+			network: func() X11Network {
+				if config.X11Net != nil {
+					return config.X11Net
+				}
+				return osNet{}
+			}(),
+		},
 	}
 
 	srv := &ssh.Server{
@@ -455,7 +478,7 @@ func (s *Server) sessionHandler(session ssh.Session) {
 
 	x11, hasX11 := session.X11()
 	if hasX11 {
-		display, handled := s.x11Handler(ctx, x11)
+		display, handled := s.x11Forwarder.x11Handler(ctx, session)
 		if !handled {
 			logger.Error(ctx, "x11 handler failed")
 			closeCause("x11 handler failed")
@@ -587,7 +610,12 @@ func (s *Server) startNonPTYSession(logger slog.Logger, session ssh.Session, mag
 	// otherwise context cancellation will not propagate properly
 	// and SSH server close may be delayed.
 	cmd.SysProcAttr = cmdSysProcAttr()
-	cmd.Cancel = cmdCancel(session.Context(), logger, cmd)
+
+	// to match OpenSSH, we don't actually tear a non-TTY command down, even if the session ends. OpenSSH closes the
+	// pipes to the process when the session ends; which is what happens here since we wire the command up to the
+	// session for I/O.
+	// c.f. https://github.com/coder/coder/issues/18519#issuecomment-3019118271
+	cmd.Cancel = nil
 
 	cmd.Stdout = session
 	cmd.Stderr = session.Stderr()
@@ -610,6 +638,16 @@ func (s *Server) startNonPTYSession(logger slog.Logger, session ssh.Session, mag
 		s.metrics.sessionErrors.WithLabelValues(magicTypeLabel, "no", "start_command").Add(1)
 		return xerrors.Errorf("start: %w", err)
 	}
+
+	// Since we don't cancel the process when the session stops, we still need to tear it down if we are closing. So
+	// track it here.
+	if !s.trackProcess(cmd.Process, true) {
+		// must be closing
+		err = cmdCancel(logger, cmd.Process)
+		return xerrors.Errorf("failed to track process: %w", err)
+	}
+	defer s.trackProcess(cmd.Process, false)
+
 	sigs := make(chan ssh.Signal, 1)
 	session.Signals(sigs)
 	defer func() {
@@ -1070,6 +1108,27 @@ func (s *Server) trackSession(ss ssh.Session, add bool) (ok bool) {
 	return true
 }
 
+// trackCommand registers the process with the server. If the server is
+// closing, the process is not registered and should be closed.
+//
+//nolint:revive
+func (s *Server) trackProcess(p *os.Process, add bool) (ok bool) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if add {
+		if s.closing != nil {
+			// Server closed.
+			return false
+		}
+		s.wg.Add(1)
+		s.processes[p] = struct{}{}
+		return true
+	}
+	s.wg.Done()
+	delete(s.processes, p)
+	return true
+}
+
 // Close the server and all active connections. Server can be re-used
 // after Close is done.
 func (s *Server) Close() error {
@@ -1109,11 +1168,18 @@ func (s *Server) Close() error {
 		_ = c.Close()
 	}
 
+	for p := range s.processes {
+		_ = cmdCancel(s.logger, p)
+	}
+
 	s.logger.Debug(ctx, "closing SSH server")
 	err := s.srv.Close()
 
 	s.mu.Unlock()
 
+	s.logger.Debug(ctx, "closing X11 forwarding")
+	_ = s.x11Forwarder.Close()
+
 	s.logger.Debug(ctx, "waiting for all goroutines to exit")
 	s.wg.Wait() // Wait for all goroutines to exit.
 

agent/agentssh/agentssh_test.go

@@ -8,7 +8,9 @@ import (
 	"context"
 	"fmt"
 	"net"
+	"os"
 	"os/user"
+	"path/filepath"
 	"runtime"
 	"strings"
 	"sync"
@@ -403,6 +405,92 @@ func TestNewServer_Signal(t *testing.T) {
 	})
 }
 
+func TestSSHServer_ClosesStdin(t *testing.T) {
+	t.Parallel()
+	if runtime.GOOS == "windows" {
+		t.Skip("bash doesn't exist on Windows")
+	}
+
+	ctx := testutil.Context(t, testutil.WaitMedium)
+	logger := testutil.Logger(t)
+	s, err := agentssh.NewServer(ctx, logger.Named("ssh-server"), prometheus.NewRegistry(), afero.NewMemMapFs(), agentexec.DefaultExecer, nil)
+	require.NoError(t, err)
+	logger = logger.Named("test")
+	defer s.Close()
+	err = s.UpdateHostSigner(42)
+	assert.NoError(t, err)
+
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	require.NoError(t, err)
+
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		err := s.Serve(ln)
+		assert.Error(t, err) // Server is closed.
+	}()
+	defer func() {
+		err := s.Close()
+		require.NoError(t, err)
+		<-done
+	}()
+
+	c := sshClient(t, ln.Addr().String())
+
+	sess, err := c.NewSession()
+	require.NoError(t, err)
+	stdout, err := sess.StdoutPipe()
+	require.NoError(t, err)
+	stdin, err := sess.StdinPipe()
+	require.NoError(t, err)
+	defer stdin.Close()
+
+	dir := t.TempDir()
+	err = os.MkdirAll(dir, 0o755)
+	require.NoError(t, err)
+	filePath := filepath.Join(dir, "result.txt")
+
+	// the shell command `read` will block until data is written to stdin, or closed. It will return
+	// exit code 1 if it hits EOF, which is what we want to test.
+	cmdErrCh := make(chan error, 1)
+	go func() {
+		cmdErrCh <- sess.Start(fmt.Sprintf(`echo started; echo "read exit code: $(read && echo 0 || echo 1)" > %s`, filePath))
+	}()
+
+	cmdErr := testutil.RequireReceive(ctx, t, cmdErrCh)
+	require.NoError(t, cmdErr)
+
+	readCh := make(chan error, 1)
+	go func() {
+		buf := make([]byte, 8)
+		_, err := stdout.Read(buf)
+		assert.Equal(t, "started\n", string(buf))
+		readCh <- err
+	}()
+	err = testutil.RequireReceive(ctx, t, readCh)
+	require.NoError(t, err)
+
+	err = sess.Close()
+	require.NoError(t, err)
+
+	var content []byte
+	expected := []byte("read exit code: 1\n")
+	testutil.Eventually(ctx, t, func(_ context.Context) bool {
+		content, err = os.ReadFile(filePath)
+		if err != nil {
+			logger.Debug(ctx, "failed to read file; will retry", slog.Error(err))
+			return false
+		}
+		if len(content) != len(expected) {
+			logger.Debug(ctx, "file is partially written", slog.F("content", content))
+			return false
+		}
+		return true
+	}, testutil.IntervalFast)
+	require.NoError(t, err)
+	require.Equal(t, string(expected), string(content))
+}
+
 func sshClient(t *testing.T, addr string) *ssh.Client {
 	conn, err := net.Dial("tcp", addr)
 	require.NoError(t, err)

agent/agentssh/exec_other.go

@@ -4,7 +4,7 @@ package agentssh
 
 import (
 	"context"
-	"os/exec"
+	"os"
 	"syscall"
 
 	"cdr.dev/slog"
@@ -16,9 +16,7 @@ func cmdSysProcAttr() *syscall.SysProcAttr {
 	}
 }
 
-func cmdCancel(ctx context.Context, logger slog.Logger, cmd *exec.Cmd) func() error {
-	return func() error {
-		logger.Debug(ctx, "cmdCancel: sending SIGHUP to process and children", slog.F("pid", cmd.Process.Pid))
-		return syscall.Kill(-cmd.Process.Pid, syscall.SIGHUP)
-	}
+func cmdCancel(logger slog.Logger, p *os.Process) error {
+	logger.Debug(context.Background(), "cmdCancel: sending SIGHUP to process and children", slog.F("pid", p.Pid))
+	return syscall.Kill(-p.Pid, syscall.SIGHUP)
 }

agent/agentssh/exec_windows.go

@@ -2,7 +2,7 @@ package agentssh
 
 import (
 	"context"
-	"os/exec"
+	"os"
 	"syscall"
 
 	"cdr.dev/slog"
@@ -12,14 +12,12 @@ func cmdSysProcAttr() *syscall.SysProcAttr {
 	return &syscall.SysProcAttr{}
 }
 
-func cmdCancel(ctx context.Context, logger slog.Logger, cmd *exec.Cmd) func() error {
-	return func() error {
-		logger.Debug(ctx, "cmdCancel: killing process", slog.F("pid", cmd.Process.Pid))
-		// Windows doesn't support sending signals to process groups, so we
-		// have to kill the process directly. In the future, we may want to
-		// implement a more sophisticated solution for process groups on
-		// Windows, but for now, this is a simple way to ensure that the
-		// process is terminated when the context is cancelled.
-		return cmd.Process.Kill()
-	}
+func cmdCancel(logger slog.Logger, p *os.Process) error {
+	logger.Debug(context.Background(), "cmdCancel: killing process", slog.F("pid", p.Pid))
+	// Windows doesn't support sending signals to process groups, so we
+	// have to kill the process directly. In the future, we may want to
+	// implement a more sophisticated solution for process groups on
+	// Windows, but for now, this is a simple way to ensure that the
+	// process is terminated when the context is cancelled.
+	return p.Kill()
 }

agent/agentssh/jetbrainstrack.go

@@ -53,7 +53,7 @@ func NewJetbrainsChannelWatcher(ctx ssh.Context, logger slog.Logger, reportConne
 
 	// If this is not JetBrains, then we do not need to do anything special.  We
 	// attempt to match on something that appears unique to JetBrains software.
-	if !strings.Contains(strings.ToLower(cmdline), strings.ToLower(MagicProcessCmdlineJetBrains)) {
+	if !isJetbrainsProcess(cmdline) {
 		return newChannel
 	}
 
@@ -104,3 +104,18 @@ func (c *ChannelOnClose) Close() error {
 	c.once.Do(c.done)
 	return c.Channel.Close()
 }
+
+func isJetbrainsProcess(cmdline string) bool {
+	opts := []string{
+		MagicProcessCmdlineJetBrains,
+		MagicProcessCmdlineToolbox,
+		MagicProcessCmdlineGateway,
+	}
+
+	for _, opt := range opts {
+		if strings.Contains(strings.ToLower(cmdline), strings.ToLower(opt)) {
+			return true
+		}
+	}
+	return false
+}

agent/agentssh/x11.go

@@ -7,15 +7,16 @@ import (
 	"errors"
 	"fmt"
 	"io"
-	"math"
 	"net"
 	"os"
 	"path/filepath"
 	"strconv"
+	"sync"
 	"time"
 
 	"github.com/gliderlabs/ssh"
 	"github.com/gofrs/flock"
+	"github.com/prometheus/client_golang/prometheus"
 	"github.com/spf13/afero"
 	gossh "golang.org/x/crypto/ssh"
 	"golang.org/x/xerrors"
@@ -29,8 +30,51 @@ const (
 	X11StartPort = 6000
 	// X11DefaultDisplayOffset is the default offset for X11 forwarding.
 	X11DefaultDisplayOffset = 10
+	X11MaxDisplays          = 200
+	// X11MaxPort is the highest port we will ever use for X11 forwarding. This limits the total number of TCP sockets
+	// we will create. It seems more useful to have a maximum port number than a direct limit on sockets with no max
+	// port because we'd like to be able to tell users the exact range of ports the Agent might use.
+	X11MaxPort = X11StartPort + X11MaxDisplays
 )
 
+// X11Network abstracts the creation of network listeners for X11 forwarding.
+// It is intended mainly for testing; production code uses the default
+// implementation backed by the operating system networking stack.
+type X11Network interface {
+	Listen(network, address string) (net.Listener, error)
+}
+
+// osNet is the default X11Network implementation that uses the standard
+// library network stack.
+type osNet struct{}
+
+func (osNet) Listen(network, address string) (net.Listener, error) {
+	return net.Listen(network, address)
+}
+
+type x11Forwarder struct {
+	logger           slog.Logger
+	x11HandlerErrors *prometheus.CounterVec
+	fs               afero.Fs
+	displayOffset    int
+
+	// network creates X11 listener sockets. Defaults to osNet{}.
+	network X11Network
+
+	mu          sync.Mutex
+	sessions    map[*x11Session]struct{}
+	connections map[net.Conn]struct{}
+	closing     bool
+	wg          sync.WaitGroup
+}
+
+type x11Session struct {
+	session  ssh.Session
+	display  int
+	listener net.Listener
+	usedAt   time.Time
+}
+
 // x11Callback is called when the client requests X11 forwarding.
 func (*Server) x11Callback(_ ssh.Context, _ ssh.X11) bool {
 	// Always allow.
@@ -39,115 +83,243 @@ func (*Server) x11Callback(_ ssh.Context, _ ssh.X11) bool {
 
 // x11Handler is called when a session has requested X11 forwarding.
 // It listens for X11 connections and forwards them to the client.
-func (s *Server) x11Handler(ctx ssh.Context, x11 ssh.X11) (displayNumber int, handled bool) {
-	serverConn, valid := ctx.Value(ssh.ContextKeyConn).(*gossh.ServerConn)
-	if !valid {
-		s.logger.Warn(ctx, "failed to get server connection")
+func (x *x11Forwarder) x11Handler(sshCtx ssh.Context, sshSession ssh.Session) (displayNumber int, handled bool) {
+	x11, hasX11 := sshSession.X11()
+	if !hasX11 {
 		return -1, false
 	}
+	serverConn, valid := sshCtx.Value(ssh.ContextKeyConn).(*gossh.ServerConn)
+	if !valid {
+		x.logger.Warn(sshCtx, "failed to get server connection")
+		return -1, false
+	}
+	ctx := slog.With(sshCtx, slog.F("session_id", fmt.Sprintf("%x", serverConn.SessionID())))
 
 	hostname, err := os.Hostname()
 	if err != nil {
-		s.logger.Warn(ctx, "failed to get hostname", slog.Error(err))
-		s.metrics.x11HandlerErrors.WithLabelValues("hostname").Add(1)
+		x.logger.Warn(ctx, "failed to get hostname", slog.Error(err))
+		x.x11HandlerErrors.WithLabelValues("hostname").Add(1)
 		return -1, false
 	}
 
-	ln, display, err := createX11Listener(ctx, *s.config.X11DisplayOffset)
+	x11session, err := x.createX11Session(ctx, sshSession)
 	if err != nil {
-		s.logger.Warn(ctx, "failed to create X11 listener", slog.Error(err))
-		s.metrics.x11HandlerErrors.WithLabelValues("listen").Add(1)
+		x.logger.Warn(ctx, "failed to create X11 listener", slog.Error(err))
+		x.x11HandlerErrors.WithLabelValues("listen").Add(1)
 		return -1, false
 	}
-	s.trackListener(ln, true)
 	defer func() {
 		if !handled {
-			s.trackListener(ln, false)
-			_ = ln.Close()
+			x.closeAndRemoveSession(x11session)
 		}
 	}()
 
-	err = addXauthEntry(ctx, s.fs, hostname, strconv.Itoa(display), x11.AuthProtocol, x11.AuthCookie)
+	err = addXauthEntry(ctx, x.fs, hostname, strconv.Itoa(x11session.display), x11.AuthProtocol, x11.AuthCookie)
 	if err != nil {
-		s.logger.Warn(ctx, "failed to add Xauthority entry", slog.Error(err))
-		s.metrics.x11HandlerErrors.WithLabelValues("xauthority").Add(1)
+		x.logger.Warn(ctx, "failed to add Xauthority entry", slog.Error(err))
+		x.x11HandlerErrors.WithLabelValues("xauthority").Add(1)
 		return -1, false
 	}
 
+	// clean up the X11 session if the SSH session completes.
 	go func() {
-		// Don't leave the listener open after the session is gone.
 		<-ctx.Done()
-		_ = ln.Close()
+		x.closeAndRemoveSession(x11session)
 	}()
 
-	go func() {
-		defer ln.Close()
-		defer s.trackListener(ln, false)
+	go x.listenForConnections(ctx, x11session, serverConn, x11)
+	x.logger.Debug(ctx, "X11 forwarding started", slog.F("display", x11session.display))
 
-		for {
-			conn, err := ln.Accept()
-			if err != nil {
-				if errors.Is(err, net.ErrClosed) {
-					return
-				}
-				s.logger.Warn(ctx, "failed to accept X11 connection", slog.Error(err))
+	return x11session.display, true
+}
+
+func (x *x11Forwarder) trackGoroutine() (closing bool, done func()) {
+	x.mu.Lock()
+	defer x.mu.Unlock()
+	if !x.closing {
+		x.wg.Add(1)
+		return false, func() { x.wg.Done() }
+	}
+	return true, func() {}
+}
+
+func (x *x11Forwarder) listenForConnections(
+	ctx context.Context, session *x11Session, serverConn *gossh.ServerConn, x11 ssh.X11,
+) {
+	defer x.closeAndRemoveSession(session)
+	if closing, done := x.trackGoroutine(); closing {
+		return
+	} else { // nolint: revive
+		defer done()
+	}
+
+	for {
+		conn, err := session.listener.Accept()
+		if err != nil {
+			if errors.Is(err, net.ErrClosed) {
 				return
 			}
-			if x11.SingleConnection {
-				s.logger.Debug(ctx, "single connection requested, closing X11 listener")
-				_ = ln.Close()
-			}
-
-			tcpConn, ok := conn.(*net.TCPConn)
-			if !ok {
-				s.logger.Warn(ctx, fmt.Sprintf("failed to cast connection to TCPConn. got: %T", conn))
-				_ = conn.Close()
-				continue
-			}
-			tcpAddr, ok := tcpConn.LocalAddr().(*net.TCPAddr)
-			if !ok {
-				s.logger.Warn(ctx, fmt.Sprintf("failed to cast local address to TCPAddr. got: %T", tcpConn.LocalAddr()))
-				_ = conn.Close()
-				continue
-			}
-
-			channel, reqs, err := serverConn.OpenChannel("x11", gossh.Marshal(struct {
-				OriginatorAddress string
-				OriginatorPort    uint32
-			}{
-				OriginatorAddress: tcpAddr.IP.String(),
-				// #nosec G115 - Safe conversion as TCP port numbers are within uint32 range (0-65535)
-				OriginatorPort: uint32(tcpAddr.Port),
-			}))
-			if err != nil {
-				s.logger.Warn(ctx, "failed to open X11 channel", slog.Error(err))
-				_ = conn.Close()
-				continue
-			}
-			go gossh.DiscardRequests(reqs)
-
-			if !s.trackConn(ln, conn, true) {
-				s.logger.Warn(ctx, "failed to track X11 connection")
-				_ = conn.Close()
-				continue
-			}
-			go func() {
-				defer s.trackConn(ln, conn, false)
-				Bicopy(ctx, conn, channel)
-			}()
+			x.logger.Warn(ctx, "failed to accept X11 connection", slog.Error(err))
+			return
 		}
-	}()
 
-	return display, true
+		// Update session usage time since a new X11 connection was forwarded.
+		x.mu.Lock()
+		session.usedAt = time.Now()
+		x.mu.Unlock()
+		if x11.SingleConnection {
+			x.logger.Debug(ctx, "single connection requested, closing X11 listener")
+			x.closeAndRemoveSession(session)
+		}
+
+		var originAddr string
+		var originPort uint32
+
+		if tcpConn, ok := conn.(*net.TCPConn); ok {
+			if tcpAddr, ok := tcpConn.LocalAddr().(*net.TCPAddr); ok {
+				originAddr = tcpAddr.IP.String()
+				// #nosec G115 - Safe conversion as TCP port numbers are within uint32 range (0-65535)
+				originPort = uint32(tcpAddr.Port)
+			}
+		}
+		// Fallback values for in-memory or non-TCP connections.
+		if originAddr == "" {
+			originAddr = "127.0.0.1"
+		}
+
+		channel, reqs, err := serverConn.OpenChannel("x11", gossh.Marshal(struct {
+			OriginatorAddress string
+			OriginatorPort    uint32
+		}{
+			OriginatorAddress: originAddr,
+			OriginatorPort:    originPort,
+		}))
+		if err != nil {
+			x.logger.Warn(ctx, "failed to open X11 channel", slog.Error(err))
+			_ = conn.Close()
+			continue
+		}
+		go gossh.DiscardRequests(reqs)
+
+		if !x.trackConn(conn, true) {
+			x.logger.Warn(ctx, "failed to track X11 connection")
+			_ = conn.Close()
+			continue
+		}
+		go func() {
+			defer x.trackConn(conn, false)
+			Bicopy(ctx, conn, channel)
+		}()
+	}
+}
+
+// closeAndRemoveSession closes and removes the session.
+func (x *x11Forwarder) closeAndRemoveSession(x11session *x11Session) {
+	_ = x11session.listener.Close()
+	x.mu.Lock()
+	delete(x.sessions, x11session)
+	x.mu.Unlock()
+}
+
+// createX11Session creates an X11 forwarding session.
+func (x *x11Forwarder) createX11Session(ctx context.Context, sshSession ssh.Session) (*x11Session, error) {
+	var (
+		ln      net.Listener
+		display int
+		err     error
+	)
+	// retry listener creation after evictions. Limit to 10 retries to prevent pathological cases looping forever.
+	const maxRetries = 10
+	for try := range maxRetries {
+		ln, display, err = x.createX11Listener(ctx)
+		if err == nil {
+			break
+		}
+		if try == maxRetries-1 {
+			return nil, xerrors.New("max retries exceeded while creating X11 session")
+		}
+		x.logger.Warn(ctx, "failed to create X11 listener; will evict an X11 forwarding session",
+			slog.F("num_current_sessions", x.numSessions()),
+			slog.Error(err))
+		x.evictLeastRecentlyUsedSession()
+	}
+	x.mu.Lock()
+	defer x.mu.Unlock()
+	if x.closing {
+		closeErr := ln.Close()
+		if closeErr != nil {
+			x.logger.Error(ctx, "error closing X11 listener", slog.Error(closeErr))
+		}
+		return nil, xerrors.New("server is closing")
+	}
+	x11Sess := &x11Session{
+		session:  sshSession,
+		display:  display,
+		listener: ln,
+		usedAt:   time.Now(),
+	}
+	x.sessions[x11Sess] = struct{}{}
+	return x11Sess, nil
+}
+
+func (x *x11Forwarder) numSessions() int {
+	x.mu.Lock()
+	defer x.mu.Unlock()
+	return len(x.sessions)
+}
+
+func (x *x11Forwarder) popLeastRecentlyUsedSession() *x11Session {
+	x.mu.Lock()
+	defer x.mu.Unlock()
+	var lru *x11Session
+	for s := range x.sessions {
+		if lru == nil {
+			lru = s
+			continue
+		}
+		if s.usedAt.Before(lru.usedAt) {
+			lru = s
+			continue
+		}
+	}
+	if lru == nil {
+		x.logger.Debug(context.Background(), "tried to pop from empty set of X11 sessions")
+		return nil
+	}
+	delete(x.sessions, lru)
+	return lru
+}
+
+func (x *x11Forwarder) evictLeastRecentlyUsedSession() {
+	lru := x.popLeastRecentlyUsedSession()
+	if lru == nil {
+		return
+	}
+	err := lru.listener.Close()
+	if err != nil {
+		x.logger.Error(context.Background(), "failed to close evicted X11 session listener", slog.Error(err))
+	}
+	// when we evict, we also want to force the SSH session to be closed as well. This is because we intend to reuse
+	// the X11 TCP listener port for a new X11 forwarding session. If we left the SSH session up, then graphical apps
+	// started in that session could potentially connect to an unintended X11 Server (i.e. the display on a different
+	// computer than the one that started the SSH session). Most likely, this session is a zombie anyway if we've
+	// reached the maximum number of X11 forwarding sessions.
+	err = lru.session.Close()
+	if err != nil {
+		x.logger.Error(context.Background(), "failed to close evicted X11 SSH session", slog.Error(err))
+	}
 }
 
 // createX11Listener creates a listener for X11 forwarding, it will use
 // the next available port starting from X11StartPort and displayOffset.
-func createX11Listener(ctx context.Context, displayOffset int) (ln net.Listener, display int, err error) {
-	var lc net.ListenConfig
+func (x *x11Forwarder) createX11Listener(ctx context.Context) (ln net.Listener, display int, err error) {
 	// Look for an open port to listen on.
-	for port := X11StartPort + displayOffset; port < math.MaxUint16; port++ {
-		ln, err = lc.Listen(ctx, "tcp", fmt.Sprintf("localhost:%d", port))
+	for port := X11StartPort + x.displayOffset; port <= X11MaxPort; port++ {
+		if ctx.Err() != nil {
+			return nil, -1, ctx.Err()
+		}
+
+		ln, err = x.network.Listen("tcp", fmt.Sprintf("localhost:%d", port))
 		if err == nil {
 			display = port - X11StartPort
 			return ln, display, nil
@@ -156,6 +328,49 @@ func createX11Listener(ctx context.Context, displayOffset int) (ln net.Listener,
 	return nil, -1, xerrors.Errorf("failed to find open port for X11 listener: %w", err)
 }
 
+// trackConn registers the connection with the x11Forwarder. If the server is
+// closed, the connection is not registered and should be closed.
+//
+//nolint:revive
+func (x *x11Forwarder) trackConn(c net.Conn, add bool) (ok bool) {
+	x.mu.Lock()
+	defer x.mu.Unlock()
+	if add {
+		if x.closing {
+			// Server or listener closed.
+			return false
+		}
+		x.wg.Add(1)
+		x.connections[c] = struct{}{}
+		return true
+	}
+	x.wg.Done()
+	delete(x.connections, c)
+	return true
+}
+
+func (x *x11Forwarder) Close() error {
+	x.mu.Lock()
+	x.closing = true
+
+	for s := range x.sessions {
+		sErr := s.listener.Close()
+		if sErr != nil {
+			x.logger.Debug(context.Background(), "failed to close X11 listener", slog.Error(sErr))
+		}
+	}
+	for c := range x.connections {
+		cErr := c.Close()
+		if cErr != nil {
+			x.logger.Debug(context.Background(), "failed to close X11 connection", slog.Error(cErr))
+		}
+	}
+
+	x.mu.Unlock()
+	x.wg.Wait()
+	return nil
+}
+
 // addXauthEntry adds an Xauthority entry to the Xauthority file.
 // The Xauthority file is located at ~/.Xauthority.
 func addXauthEntry(ctx context.Context, fs afero.Fs, host string, display string, authProtocol string, authCookie string) error {

agent/agentssh/x11_test.go

@@ -3,9 +3,9 @@ package agentssh_test
 import (
 	"bufio"
 	"bytes"
-	"context"
 	"encoding/hex"
 	"fmt"
+	"io"
 	"net"
 	"os"
 	"path/filepath"
@@ -32,10 +32,19 @@ func TestServer_X11(t *testing.T) {
 		t.Skip("X11 forwarding is only supported on Linux")
 	}
 
-	ctx := context.Background()
+	ctx := testutil.Context(t, testutil.WaitShort)
 	logger := testutil.Logger(t)
-	fs := afero.NewOsFs()
-	s, err := agentssh.NewServer(ctx, logger, prometheus.NewRegistry(), fs, agentexec.DefaultExecer, &agentssh.Config{})
+	fs := afero.NewMemMapFs()
+
+	// Use in-process networking for X11 forwarding.
+	inproc := testutil.NewInProcNet()
+
+	// Create server config with custom X11 listener.
+	cfg := &agentssh.Config{
+		X11Net: inproc,
+	}
+
+	s, err := agentssh.NewServer(ctx, logger, prometheus.NewRegistry(), fs, agentexec.DefaultExecer, cfg)
 	require.NoError(t, err)
 	defer s.Close()
 	err = s.UpdateHostSigner(42)
@@ -93,17 +102,15 @@ func TestServer_X11(t *testing.T) {
 
 	x11Chans := c.HandleChannelOpen("x11")
 	payload := "hello world"
-	require.Eventually(t, func() bool {
-		conn, err := net.Dial("tcp", fmt.Sprintf("localhost:%d", agentssh.X11StartPort+displayNumber))
-		if err == nil {
-			_, err = conn.Write([]byte(payload))
-			assert.NoError(t, err)
-			_ = conn.Close()
-		}
-		return err == nil
-	}, testutil.WaitShort, testutil.IntervalFast)
+	go func() {
+		conn, err := inproc.Dial(ctx, testutil.NewAddr("tcp", fmt.Sprintf("localhost:%d", agentssh.X11StartPort+displayNumber)))
+		assert.NoError(t, err)
+		_, err = conn.Write([]byte(payload))
+		assert.NoError(t, err)
+		_ = conn.Close()
+	}()
 
-	x11 := <-x11Chans
+	x11 := testutil.RequireReceive(ctx, t, x11Chans)
 	ch, reqs, err := x11.Accept()
 	require.NoError(t, err)
 	go gossh.DiscardRequests(reqs)
@@ -121,3 +128,211 @@ func TestServer_X11(t *testing.T) {
 	_, err = fs.Stat(filepath.Join(home, ".Xauthority"))
 	require.NoError(t, err)
 }
+
+func TestServer_X11_EvictionLRU(t *testing.T) {
+	t.Parallel()
+	if runtime.GOOS != "linux" {
+		t.Skip("X11 forwarding is only supported on Linux")
+	}
+
+	ctx := testutil.Context(t, testutil.WaitSuperLong)
+	logger := testutil.Logger(t)
+	fs := afero.NewMemMapFs()
+
+	// Use in-process networking for X11 forwarding.
+	inproc := testutil.NewInProcNet()
+
+	cfg := &agentssh.Config{
+		X11Net: inproc,
+	}
+
+	s, err := agentssh.NewServer(ctx, logger, prometheus.NewRegistry(), fs, agentexec.DefaultExecer, cfg)
+	require.NoError(t, err)
+	defer s.Close()
+	err = s.UpdateHostSigner(42)
+	require.NoError(t, err)
+
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	require.NoError(t, err)
+
+	done := testutil.Go(t, func() {
+		err := s.Serve(ln)
+		assert.Error(t, err)
+	})
+
+	c := sshClient(t, ln.Addr().String())
+
+	// block off one port to test x11Forwarder evicts at highest port, not number of listeners.
+	externalListener, err := inproc.Listen("tcp",
+		fmt.Sprintf("localhost:%d", agentssh.X11StartPort+agentssh.X11DefaultDisplayOffset+1))
+	require.NoError(t, err)
+	defer externalListener.Close()
+
+	// Calculate how many simultaneous X11 sessions we can create given the
+	// configured port range.
+
+	startPort := agentssh.X11StartPort + agentssh.X11DefaultDisplayOffset
+	maxSessions := agentssh.X11MaxPort - startPort + 1 - 1 // -1 for the blocked port
+	require.Greater(t, maxSessions, 0, "expected a positive maxSessions value")
+
+	// shellSession holds references to the session and its standard streams so
+	// that the test can keep them open (and optionally interact with them) for
+	// the lifetime of the test. If we don't start the Shell with pipes in place,
+	// the session will be torn down asynchronously during the test.
+	type shellSession struct {
+		sess   *gossh.Session
+		stdin  io.WriteCloser
+		stdout io.Reader
+		stderr io.Reader
+		// scanner is used to read the output of the session, line by line.
+		scanner *bufio.Scanner
+	}
+
+	sessions := make([]shellSession, 0, maxSessions)
+	for i := 0; i < maxSessions; i++ {
+		sess, err := c.NewSession()
+		require.NoError(t, err)
+
+		_, err = sess.SendRequest("x11-req", true, gossh.Marshal(ssh.X11{
+			AuthProtocol: "MIT-MAGIC-COOKIE-1",
+			AuthCookie:   hex.EncodeToString([]byte(fmt.Sprintf("cookie%d", i))),
+			ScreenNumber: uint32(0),
+		}))
+		require.NoError(t, err)
+
+		stdin, err := sess.StdinPipe()
+		require.NoError(t, err)
+		stdout, err := sess.StdoutPipe()
+		require.NoError(t, err)
+		stderr, err := sess.StderrPipe()
+		require.NoError(t, err)
+		require.NoError(t, sess.Shell())
+
+		// The SSH server lazily starts the session. We need to write a command
+		// and read back to ensure the X11 forwarding is started.
+		scanner := bufio.NewScanner(stdout)
+		msg := fmt.Sprintf("ready-%d", i)
+		_, err = stdin.Write([]byte("echo " + msg + "\n"))
+		require.NoError(t, err)
+		// Read until we get the message (first token may be empty due to shell prompt)
+		for scanner.Scan() {
+			line := strings.TrimSpace(scanner.Text())
+			if strings.Contains(line, msg) {
+				break
+			}
+		}
+		require.NoError(t, scanner.Err())
+
+		sessions = append(sessions, shellSession{
+			sess:    sess,
+			stdin:   stdin,
+			stdout:  stdout,
+			stderr:  stderr,
+			scanner: scanner,
+		})
+	}
+
+	// Connect X11 forwarding to the first session. This is used to test that
+	// connecting counts as a use of the display.
+	x11Chans := c.HandleChannelOpen("x11")
+	payload := "hello world"
+	go func() {
+		conn, err := inproc.Dial(ctx, testutil.NewAddr("tcp", fmt.Sprintf("localhost:%d", agentssh.X11StartPort+agentssh.X11DefaultDisplayOffset)))
+		if !assert.NoError(t, err) {
+			return
+		}
+		_, err = conn.Write([]byte(payload))
+		assert.NoError(t, err)
+		_ = conn.Close()
+	}()
+
+	x11 := testutil.RequireReceive(ctx, t, x11Chans)
+	ch, reqs, err := x11.Accept()
+	require.NoError(t, err)
+	go gossh.DiscardRequests(reqs)
+	got := make([]byte, len(payload))
+	_, err = ch.Read(got)
+	require.NoError(t, err)
+	assert.Equal(t, payload, string(got))
+	_ = ch.Close()
+
+	// Create one more session which should evict a session and reuse the display.
+	// The first session was used to connect X11 forwarding, so it should not be evicted.
+	// Therefore, the second session should be evicted and its display reused.
+	extraSess, err := c.NewSession()
+	require.NoError(t, err)
+
+	_, err = extraSess.SendRequest("x11-req", true, gossh.Marshal(ssh.X11{
+		AuthProtocol: "MIT-MAGIC-COOKIE-1",
+		AuthCookie:   hex.EncodeToString([]byte("extra")),
+		ScreenNumber: uint32(0),
+	}))
+	require.NoError(t, err)
+
+	// Ask the remote side for the DISPLAY value so we can extract the display
+	// number that was assigned to this session.
+	out, err := extraSess.Output("echo DISPLAY=$DISPLAY")
+	require.NoError(t, err)
+
+	// Example output line: "DISPLAY=localhost:10.0".
+	var newDisplayNumber int
+	{
+		sc := bufio.NewScanner(bytes.NewReader(out))
+		for sc.Scan() {
+			line := strings.TrimSpace(sc.Text())
+			if strings.HasPrefix(line, "DISPLAY=") {
+				parts := strings.SplitN(line, ":", 2)
+				require.Len(t, parts, 2)
+				displayPart := parts[1]
+				if strings.Contains(displayPart, ".") {
+					displayPart = strings.SplitN(displayPart, ".", 2)[0]
+				}
+				var convErr error
+				newDisplayNumber, convErr = strconv.Atoi(displayPart)
+				require.NoError(t, convErr)
+				break
+			}
+		}
+		require.NoError(t, sc.Err())
+	}
+
+	// The display number reused should correspond to the SECOND session (display offset 12)
+	expectedDisplay := agentssh.X11DefaultDisplayOffset + 2 // +1 was blocked port
+	assert.Equal(t, expectedDisplay, newDisplayNumber, "second session should have been evicted and its display reused")
+
+	// First session should still be alive: send cmd and read output.
+	msgFirst := "still-alive"
+	_, err = sessions[0].stdin.Write([]byte("echo " + msgFirst + "\n"))
+	require.NoError(t, err)
+	for sessions[0].scanner.Scan() {
+		line := strings.TrimSpace(sessions[0].scanner.Text())
+		if strings.Contains(line, msgFirst) {
+			break
+		}
+	}
+	require.NoError(t, sessions[0].scanner.Err())
+
+	// Second session should now be closed.
+	_, err = sessions[1].stdin.Write([]byte("echo dead\n"))
+	require.ErrorIs(t, err, io.EOF)
+	err = sessions[1].sess.Wait()
+	require.Error(t, err)
+
+	// Cleanup.
+	for i, sh := range sessions {
+		if i == 1 {
+			// already closed
+			continue
+		}
+		err = sh.stdin.Close()
+		require.NoError(t, err)
+		err = sh.sess.Wait()
+		require.NoError(t, err)
+	}
+	err = extraSess.Close()
+	require.ErrorIs(t, err, io.EOF)
+
+	err = s.Close()
+	require.NoError(t, err)
+	_ = testutil.TryReceive(ctx, t, done)
+}

agent/api.go

@@ -6,16 +6,13 @@ import (
 	"time"
 
 	"github.com/go-chi/chi/v5"
-
 	"github.com/google/uuid"
 
-	"github.com/coder/coder/v2/agent/agentcontainers"
-	"github.com/coder/coder/v2/agent/proto"
 	"github.com/coder/coder/v2/coderd/httpapi"
 	"github.com/coder/coder/v2/codersdk"
 )
 
-func (a *agent) apiHandler(aAPI proto.DRPCAgentClient26) (http.Handler, func() error) {
+func (a *agent) apiHandler() http.Handler {
 	r := chi.NewRouter()
 	r.Get("/", func(rw http.ResponseWriter, r *http.Request) {
 		httpapi.Write(r.Context(), rw, http.StatusOK, codersdk.Response{
@@ -41,38 +38,18 @@ func (a *agent) apiHandler(aAPI proto.DRPCAgentClient26) (http.Handler, func() e
 	}
 
 	if a.devcontainers {
-		containerAPIOpts := []agentcontainers.Option{
-			agentcontainers.WithExecer(a.execer),
-			agentcontainers.WithCommandEnv(a.sshServer.CommandEnv),
-			agentcontainers.WithScriptLogger(func(logSourceID uuid.UUID) agentcontainers.ScriptLogger {
-				return a.logSender.GetScriptLogger(logSourceID)
-			}),
-			agentcontainers.WithSubAgentClient(agentcontainers.NewSubAgentClientFromAPI(a.logger, aAPI)),
-		}
-		manifest := a.manifest.Load()
-		if manifest != nil {
-			containerAPIOpts = append(containerAPIOpts,
-				agentcontainers.WithManifestInfo(manifest.OwnerName, manifest.WorkspaceName),
-			)
-
-			if len(manifest.Devcontainers) > 0 {
-				containerAPIOpts = append(
-					containerAPIOpts,
-					agentcontainers.WithDevcontainers(manifest.Devcontainers, manifest.Scripts),
-				)
-			}
-		}
-
-		// Append after to allow the agent options to override the default options.
-		containerAPIOpts = append(containerAPIOpts, a.containerAPIOptions...)
-
-		containerAPI := agentcontainers.NewAPI(a.logger.Named("containers"), containerAPIOpts...)
-		r.Mount("/api/v0/containers", containerAPI.Routes())
-		a.containerAPI.Store(containerAPI)
+		r.Mount("/api/v0/containers", a.containerAPI.Routes())
+	} else if manifest := a.manifest.Load(); manifest != nil && manifest.ParentID != uuid.Nil {
+		r.HandleFunc("/api/v0/containers", func(w http.ResponseWriter, r *http.Request) {
+			httpapi.Write(r.Context(), w, http.StatusForbidden, codersdk.Response{
+				Message: "Dev Container feature not supported.",
+				Detail:  "Dev Container integration inside other Dev Containers is explicitly not supported.",
+			})
+		})
 	} else {
 		r.HandleFunc("/api/v0/containers", func(w http.ResponseWriter, r *http.Request) {
 			httpapi.Write(r.Context(), w, http.StatusForbidden, codersdk.Response{
-				Message: "The agent dev containers feature is experimental and not enabled by default.",
+				Message: "Dev Container feature not enabled.",
 				Detail:  "To enable this feature, set CODER_AGENT_DEVCONTAINERS_ENABLE=true in your template.",
 			})
 		})
@@ -89,12 +66,7 @@ func (a *agent) apiHandler(aAPI proto.DRPCAgentClient26) (http.Handler, func() e
 	r.Get("/debug/manifest", a.HandleHTTPDebugManifest)
 	r.Get("/debug/prometheus", promHandler.ServeHTTP)
 
-	return r, func() error {
-		if containerAPI := a.containerAPI.Load(); containerAPI != nil {
-			return containerAPI.Close()
-		}
-		return nil
-	}
+	return r
 }
 
 type listeningPortsHandler struct {

archive/fs/zip.go

@@ -0,0 +1,19 @@
+package archivefs
+
+import (
+	"archive/zip"
+	"io"
+	"io/fs"
+
+	"github.com/spf13/afero"
+	"github.com/spf13/afero/zipfs"
+)
+
+// FromZipReader creates a read-only in-memory FS
+func FromZipReader(r io.ReaderAt, size int64) (fs.FS, error) {
+	zr, err := zip.NewReader(r, size)
+	if err != nil {
+		return nil, err
+	}
+	return afero.NewIOFS(zipfs.New(zr)), nil
+}

biome.jsonc

@@ -0,0 +1,86 @@
+{
+	"vcs": {
+		"enabled": true,
+		"clientKind": "git",
+		"useIgnoreFile": true,
+		"defaultBranch": "main"
+	},
+	"files": {
+		"includes": [
+			"**",
+			"!**/pnpm-lock.yaml"
+		],
+		"ignoreUnknown": true
+	},
+	"linter": {
+		"rules": {
+			"a11y": {
+				"noSvgWithoutTitle": "off",
+				"useButtonType": "off",
+				"useSemanticElements": "off",
+				"noStaticElementInteractions": "off"
+			},
+			"correctness": {
+				"noUnusedImports": "warn",
+				"useUniqueElementIds": "off", // TODO: This is new but we want to fix it
+				"noNestedComponentDefinitions": "off", // TODO: Investigate, since it is used by shadcn components
+				"noUnusedVariables": {
+					"level": "warn",
+					"options": {
+						"ignoreRestSiblings": true
+					}
+				}
+			},
+			"style": {
+				"noNonNullAssertion": "off",
+				"noParameterAssign": "off",
+				"useDefaultParameterLast": "off",
+				"useSelfClosingElements": "off",
+				"useAsConstAssertion": "error",
+				"useEnumInitializers": "error",
+				"useSingleVarDeclarator": "error",
+				"noUnusedTemplateLiteral": "error",
+				"useNumberNamespace": "error",
+				"noInferrableTypes": "error",
+				"noUselessElse": "error",
+				"noRestrictedImports": {
+					"level": "error",
+					"options": {
+						"paths": {
+							"@mui/material": "Use @mui/material/<name> instead. See: https://material-ui.com/guides/minimizing-bundle-size/.",
+							"@mui/icons-material": "Use @mui/icons-material/<name> instead. See: https://material-ui.com/guides/minimizing-bundle-size/.",
+							"@mui/material/Avatar": "Use components/Avatar/Avatar instead.",
+							"@mui/material/Alert": "Use components/Alert/Alert instead.",
+							"@mui/material/Popover": "Use components/Popover/Popover instead.",
+							"@mui/material/Typography": "Use native HTML elements instead. Eg: <span>, <p>, <h1>, etc.",
+							"@mui/material/Box": "Use a <div> instead.",
+							"@mui/material/styles": "Import from @emotion/react instead.",
+							"lodash": "Use lodash/<name> instead."
+						}
+					}
+				}
+			},
+			"suspicious": {
+				"noArrayIndexKey": "off",
+				"noThenProperty": "off",
+				"noTemplateCurlyInString": "off",
+				"useIterableCallbackReturn": "off",
+				"noUnknownAtRules": "off", // Allow Tailwind directives
+				"noConsole": {
+					"level": "error",
+					"options": {
+						"allow": [
+							"error",
+							"info",
+							"warn"
+						]
+					}
+				}
+			},
+			"complexity": {
+				"noImportantStyles": "off" // TODO: check and fix !important styles
+			}
+		}
+	},
+	"$schema": "https://biomejs.dev/schemas/2.2.0/schema.json"
+}

catalog-info.yaml

@@ -0,0 +1,10 @@
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: coder
+  annotations:
+    github.com/project-slug: 'coder/coder'
+spec:
+  type: service
+  lifecycle: production
+  owner: rd

cli/agent.go

@@ -40,22 +40,24 @@ import (
 
 func (r *RootCmd) workspaceAgent() *serpent.Command {
 	var (
-		auth                string
-		logDir              string
-		scriptDataDir       string
-		pprofAddress        string
-		noReap              bool
-		sshMaxTimeout       time.Duration
-		tailnetListenPort   int64
-		prometheusAddress   string
-		debugAddress        string
-		slogHumanPath       string
-		slogJSONPath        string
-		slogStackdriverPath string
-		blockFileTransfer   bool
-		agentHeaderCommand  string
-		agentHeader         []string
-		devcontainers       bool
+		auth                           string
+		logDir                         string
+		scriptDataDir                  string
+		pprofAddress                   string
+		noReap                         bool
+		sshMaxTimeout                  time.Duration
+		tailnetListenPort              int64
+		prometheusAddress              string
+		debugAddress                   string
+		slogHumanPath                  string
+		slogJSONPath                   string
+		slogStackdriverPath            string
+		blockFileTransfer              bool
+		agentHeaderCommand             string
+		agentHeader                    []string
+		devcontainers                  bool
+		devcontainerProjectDiscovery   bool
+		devcontainerDiscoveryAutostart bool
 	)
 	cmd := &serpent.Command{
 		Use:   "agent",
@@ -364,6 +366,8 @@ func (r *RootCmd) workspaceAgent() *serpent.Command {
 					Devcontainers:      devcontainers,
 					DevcontainerAPIOptions: []agentcontainers.Option{
 						agentcontainers.WithSubAgentURL(r.agentURL.String()),
+						agentcontainers.WithProjectDiscovery(devcontainerProjectDiscovery),
+						agentcontainers.WithDiscoveryAutostart(devcontainerDiscoveryAutostart),
 					},
 				})
 
@@ -510,6 +514,20 @@ func (r *RootCmd) workspaceAgent() *serpent.Command {
 			Description: "Allow the agent to automatically detect running devcontainers.",
 			Value:       serpent.BoolOf(&devcontainers),
 		},
+		{
+			Flag:        "devcontainers-project-discovery-enable",
+			Default:     "true",
+			Env:         "CODER_AGENT_DEVCONTAINERS_PROJECT_DISCOVERY_ENABLE",
+			Description: "Allow the agent to search the filesystem for devcontainer projects.",
+			Value:       serpent.BoolOf(&devcontainerProjectDiscovery),
+		},
+		{
+			Flag:        "devcontainers-discovery-autostart-enable",
+			Default:     "false",
+			Env:         "CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE",
+			Description: "Allow the agent to autostart devcontainer projects it discovers based on their configuration.",
+			Value:       serpent.BoolOf(&devcontainerDiscoveryAutostart),
+		},
 	}
 
 	return cmd

cli/agent_test.go

@@ -21,6 +21,7 @@ import (
 	"github.com/coder/coder/v2/coderd/coderdtest"
 	"github.com/coder/coder/v2/coderd/database"
 	"github.com/coder/coder/v2/coderd/database/dbfake"
+	"github.com/coder/coder/v2/coderd/database/dbtestutil"
 	"github.com/coder/coder/v2/codersdk"
 	"github.com/coder/coder/v2/codersdk/workspacesdk"
 	"github.com/coder/coder/v2/provisionersdk/proto"
@@ -67,7 +68,12 @@ func TestWorkspaceAgent(t *testing.T) {
 		t.Parallel()
 		instanceID := "instanceidentifier"
 		certificates, metadataClient := coderdtest.NewAzureInstanceIdentity(t, instanceID)
-		client, db := coderdtest.NewWithDatabase(t, &coderdtest.Options{
+		db, ps := dbtestutil.NewDB(t,
+			dbtestutil.WithDumpOnFailure(),
+		)
+		client := coderdtest.New(t, &coderdtest.Options{
+			Database:          db,
+			Pubsub:            ps,
 			AzureCertificates: certificates,
 		})
 		user := coderdtest.CreateFirstUser(t, client)
@@ -106,7 +112,12 @@ func TestWorkspaceAgent(t *testing.T) {
 		t.Parallel()
 		instanceID := "instanceidentifier"
 		certificates, metadataClient := coderdtest.NewAWSInstanceIdentity(t, instanceID)
-		client, db := coderdtest.NewWithDatabase(t, &coderdtest.Options{
+		db, ps := dbtestutil.NewDB(t,
+			dbtestutil.WithDumpOnFailure(),
+		)
+		client := coderdtest.New(t, &coderdtest.Options{
+			Database:        db,
+			Pubsub:          ps,
 			AWSCertificates: certificates,
 		})
 		user := coderdtest.CreateFirstUser(t, client)
@@ -146,7 +157,12 @@ func TestWorkspaceAgent(t *testing.T) {
 		t.Parallel()
 		instanceID := "instanceidentifier"
 		validator, metadataClient := coderdtest.NewGoogleInstanceIdentity(t, instanceID, false)
-		client, db := coderdtest.NewWithDatabase(t, &coderdtest.Options{
+		db, ps := dbtestutil.NewDB(t,
+			dbtestutil.WithDumpOnFailure(),
+		)
+		client := coderdtest.New(t, &coderdtest.Options{
+			Database:             db,
+			Pubsub:               ps,
 			GoogleTokenValidator: validator,
 		})
 		owner := coderdtest.CreateFirstUser(t, client)

cli/cliui/parameter.go

@@ -38,15 +38,16 @@ func RichParameter(inv *serpent.Invocation, templateVersionParameter codersdk.Te
 		// Move the cursor up a single line for nicer display!
 		_, _ = fmt.Fprint(inv.Stdout, "\033[1A")
 
-		var options []string
-		err = json.Unmarshal([]byte(templateVersionParameter.DefaultValue), &options)
+		var defaults []string
+		err = json.Unmarshal([]byte(templateVersionParameter.DefaultValue), &defaults)
 		if err != nil {
 			return "", err
 		}
 
-		values, err := MultiSelect(inv, MultiSelectOptions{
-			Options:  options,
-			Defaults: options,
+		values, err := RichMultiSelect(inv, RichMultiSelectOptions{
+			Options:           templateVersionParameter.Options,
+			Defaults:          defaults,
+			EnableCustomInput: templateVersionParameter.FormType == "tag-select",
 		})
 		if err == nil {
 			v, err := json.Marshal(&values)

cli/cliui/resources.go

@@ -12,6 +12,7 @@ import (
 	"golang.org/x/mod/semver"
 
 	"github.com/coder/coder/v2/coderd/database/dbtime"
+	"github.com/coder/coder/v2/coderd/util/slice"
 	"github.com/coder/coder/v2/codersdk"
 	"github.com/coder/pretty"
 )
@@ -29,6 +30,7 @@ type WorkspaceResourcesOptions struct {
 	ServerVersion  string
 	ListeningPorts map[uuid.UUID]codersdk.WorkspaceAgentListeningPortsResponse
 	Devcontainers  map[uuid.UUID]codersdk.WorkspaceAgentListContainersResponse
+	ShowDetails    bool
 }
 
 // WorkspaceResources displays the connection status and tree-view of provided resources.
@@ -69,7 +71,11 @@ func WorkspaceResources(writer io.Writer, resources []codersdk.WorkspaceResource
 
 	totalAgents := 0
 	for _, resource := range resources {
-		totalAgents += len(resource.Agents)
+		for _, agent := range resource.Agents {
+			if !agent.ParentID.Valid {
+				totalAgents++
+			}
+		}
 	}
 
 	for _, resource := range resources {
@@ -94,12 +100,15 @@ func WorkspaceResources(writer io.Writer, resources []codersdk.WorkspaceResource
 			"",
 		})
 		// Display all agents associated with the resource.
-		for index, agent := range resource.Agents {
+		agents := slice.Filter(resource.Agents, func(agent codersdk.WorkspaceAgent) bool {
+			return !agent.ParentID.Valid
+		})
+		for index, agent := range agents {
 			tableWriter.AppendRow(renderAgentRow(agent, index, totalAgents, options))
 			for _, row := range renderListeningPorts(options, agent.ID, index, totalAgents) {
 				tableWriter.AppendRow(row)
 			}
-			for _, row := range renderDevcontainers(options, agent.ID, index, totalAgents) {
+			for _, row := range renderDevcontainers(resources, options, agent.ID, index, totalAgents) {
 				tableWriter.AppendRow(row)
 			}
 		}
@@ -125,7 +134,7 @@ func renderAgentRow(agent codersdk.WorkspaceAgent, index, totalAgents int, optio
 	}
 	if !options.HideAccess {
 		sshCommand := "coder ssh " + options.WorkspaceName
-		if totalAgents > 1 {
+		if totalAgents > 1 || len(options.Devcontainers) > 0 {
 			sshCommand += "." + agent.Name
 		}
 		sshCommand = pretty.Sprint(DefaultStyles.Code, sshCommand)
@@ -164,45 +173,129 @@ func renderPortRow(port codersdk.WorkspaceAgentListeningPort, idx, total int) ta
 	return table.Row{sb.String()}
 }
 
-func renderDevcontainers(wro WorkspaceResourcesOptions, agentID uuid.UUID, index, totalAgents int) []table.Row {
+func renderDevcontainers(resources []codersdk.WorkspaceResource, wro WorkspaceResourcesOptions, agentID uuid.UUID, index, totalAgents int) []table.Row {
 	var rows []table.Row
 	if wro.Devcontainers == nil {
 		return []table.Row{}
 	}
 	dc, ok := wro.Devcontainers[agentID]
-	if !ok || len(dc.Containers) == 0 {
+	if !ok || len(dc.Devcontainers) == 0 {
 		return []table.Row{}
 	}
 	rows = append(rows, table.Row{
 		fmt.Sprintf("   %s─ %s", renderPipe(index, totalAgents), "Devcontainers"),
 	})
-	for idx, container := range dc.Containers {
-		rows = append(rows, renderDevcontainerRow(container, idx, len(dc.Containers)))
+	for idx, devcontainer := range dc.Devcontainers {
+		rows = append(rows, renderDevcontainerRow(resources, devcontainer, idx, len(dc.Devcontainers), wro)...)
 	}
 	return rows
 }
 
-func renderDevcontainerRow(container codersdk.WorkspaceAgentContainer, index, total int) table.Row {
-	var row table.Row
-	var sb strings.Builder
-	_, _ = sb.WriteString("      ")
-	_, _ = sb.WriteString(renderPipe(index, total))
-	_, _ = sb.WriteString("─ ")
-	_, _ = sb.WriteString(pretty.Sprintf(DefaultStyles.Code, "%s", container.FriendlyName))
-	row = append(row, sb.String())
-	sb.Reset()
-	if container.Running {
-		_, _ = sb.WriteString(pretty.Sprintf(DefaultStyles.Keyword, "(%s)", container.Status))
-	} else {
-		_, _ = sb.WriteString(pretty.Sprintf(DefaultStyles.Error, "(%s)", container.Status))
+func renderDevcontainerRow(resources []codersdk.WorkspaceResource, devcontainer codersdk.WorkspaceAgentDevcontainer, index, total int, wro WorkspaceResourcesOptions) []table.Row {
+	var rows []table.Row
+
+	// If the devcontainer is running and has an associated agent, we want to
+	// display the agent's details. Otherwise, we just display the devcontainer
+	// name and status.
+	var subAgent *codersdk.WorkspaceAgent
+	displayName := devcontainer.Name
+	if devcontainer.Agent != nil && devcontainer.Status == codersdk.WorkspaceAgentDevcontainerStatusRunning {
+		for _, resource := range resources {
+			if agent, found := slice.Find(resource.Agents, func(agent codersdk.WorkspaceAgent) bool {
+				return agent.ID == devcontainer.Agent.ID
+			}); found {
+				subAgent = &agent
+				break
+			}
+		}
+		if subAgent != nil {
+			displayName = subAgent.Name
+			displayName += fmt.Sprintf(" (%s, %s)", subAgent.OperatingSystem, subAgent.Architecture)
+		}
+	}
+
+	if devcontainer.Container != nil {
+		displayName += " " + pretty.Sprint(DefaultStyles.Keyword, "["+devcontainer.Container.FriendlyName+"]")
+	}
+
+	// Build the main row.
+	row := table.Row{
+		fmt.Sprintf("      %s─ %s", renderPipe(index, total), displayName),
+	}
+
+	// Add status, health, and version columns.
+	if !wro.HideAgentState {
+		if subAgent != nil {
+			row = append(row, renderAgentStatus(*subAgent))
+			row = append(row, renderAgentHealth(*subAgent))
+			row = append(row, renderAgentVersion(subAgent.Version, wro.ServerVersion))
+		} else {
+			row = append(row, renderDevcontainerStatus(devcontainer.Status))
+			row = append(row, "") // No health for devcontainer without agent.
+			row = append(row, "") // No version for devcontainer without agent.
+		}
+	}
+
+	// Add access column.
+	if !wro.HideAccess {
+		if subAgent != nil {
+			accessString := fmt.Sprintf("coder ssh %s.%s", wro.WorkspaceName, subAgent.Name)
+			row = append(row, pretty.Sprint(DefaultStyles.Code, accessString))
+		} else {
+			row = append(row, "") // No access for devcontainers without agent.
+		}
+	}
+
+	rows = append(rows, row)
+
+	// Add error message if present.
+	if errorMessage := devcontainer.Error; errorMessage != "" {
+		// Cap error message length for display.
+		if !wro.ShowDetails && len(errorMessage) > 80 {
+			errorMessage = errorMessage[:79] + "…"
+		}
+		errorRow := table.Row{
+			"         × " + pretty.Sprint(DefaultStyles.Error, errorMessage),
+			"",
+			"",
+			"",
+		}
+		if !wro.HideAccess {
+			errorRow = append(errorRow, "")
+		}
+		rows = append(rows, errorRow)
+	}
+
+	// Add listening ports for the devcontainer agent.
+	if subAgent != nil {
+		portRows := renderListeningPorts(wro, subAgent.ID, index, total)
+		for _, portRow := range portRows {
+			// Adjust indentation for ports under devcontainer agent.
+			if len(portRow) > 0 {
+				if str, ok := portRow[0].(string); ok {
+					portRow[0] = "      " + str // Add extra indentation.
+				}
+			}
+			rows = append(rows, portRow)
+		}
+	}
+
+	return rows
+}
+
+func renderDevcontainerStatus(status codersdk.WorkspaceAgentDevcontainerStatus) string {
+	switch status {
+	case codersdk.WorkspaceAgentDevcontainerStatusRunning:
+		return pretty.Sprint(DefaultStyles.Keyword, "▶ running")
+	case codersdk.WorkspaceAgentDevcontainerStatusStopped:
+		return pretty.Sprint(DefaultStyles.Placeholder, "⏹ stopped")
+	case codersdk.WorkspaceAgentDevcontainerStatusStarting:
+		return pretty.Sprint(DefaultStyles.Warn, "⧗ starting")
+	case codersdk.WorkspaceAgentDevcontainerStatusError:
+		return pretty.Sprint(DefaultStyles.Error, "✘ error")
+	default:
+		return pretty.Sprint(DefaultStyles.Placeholder, "○ "+string(status))
 	}
-	row = append(row, sb.String())
-	sb.Reset()
-	// "health" is not applicable here.
-	row = append(row, sb.String())
-	_, _ = sb.WriteString(container.Image)
-	row = append(row, sb.String())
-	return row
 }
 
 func renderAgentStatus(agent codersdk.WorkspaceAgent) string {

cli/cliui/select.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"os"
 	"os/signal"
+	"slices"
 	"strings"
 	"syscall"
 
@@ -299,6 +300,77 @@ func (m selectModel) filteredOptions() []string {
 	return options
 }
 
+type RichMultiSelectOptions struct {
+	Message           string
+	Options           []codersdk.TemplateVersionParameterOption
+	Defaults          []string
+	EnableCustomInput bool
+}
+
+func RichMultiSelect(inv *serpent.Invocation, richOptions RichMultiSelectOptions) ([]string, error) {
+	var opts []string
+	var defaultOpts []string
+
+	asLine := func(option codersdk.TemplateVersionParameterOption) string {
+		line := option.Name
+		if len(option.Description) > 0 {
+			line += ": " + option.Description
+		}
+		return line
+	}
+
+	var predefinedOpts []string
+	for i, option := range richOptions.Options {
+		opts = append(opts, asLine(option)) // Some options may have description defined.
+
+		// Check if option is selected by default
+		if slices.Contains(richOptions.Defaults, option.Value) {
+			defaultOpts = append(defaultOpts, opts[i])
+			predefinedOpts = append(predefinedOpts, option.Value)
+		}
+	}
+
+	// Check if "defaults" contains extra/custom options, user could select them.
+	for _, def := range richOptions.Defaults {
+		if !slices.Contains(predefinedOpts, def) {
+			opts = append(opts, def)
+			defaultOpts = append(defaultOpts, def)
+		}
+	}
+
+	selected, err := MultiSelect(inv, MultiSelectOptions{
+		Message:           richOptions.Message,
+		Options:           opts,
+		Defaults:          defaultOpts,
+		EnableCustomInput: richOptions.EnableCustomInput,
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	// Check selected option, convert descriptions (line) to values
+	//
+	// The function must return an initialized empty array, since it is later marshaled
+	// into JSON. Otherwise, `var results []string` would be marshaled to "null".
+	// See: https://github.com/golang/go/issues/27589
+	results := []string{}
+	for _, sel := range selected {
+		custom := true
+		for i, option := range richOptions.Options {
+			if asLine(option) == sel {
+				results = append(results, richOptions.Options[i].Value)
+				custom = false
+				break
+			}
+		}
+
+		if custom {
+			results = append(results, sel)
+		}
+	}
+	return results, nil
+}
+
 type MultiSelectOptions struct {
 	Message           string
 	Options           []string

cli/cliui/select_test.go

@@ -52,15 +52,8 @@ func TestRichSelect(t *testing.T) {
 		go func() {
 			resp, err := newRichSelect(ptty, cliui.RichSelectOptions{
 				Options: []codersdk.TemplateVersionParameterOption{
-					{
-						Name:        "A-Name",
-						Value:       "A-Value",
-						Description: "A-Description.",
-					}, {
-						Name:        "B-Name",
-						Value:       "B-Value",
-						Description: "B-Description.",
-					},
+					{Name: "A-Name", Value: "A-Value", Description: "A-Description."},
+					{Name: "B-Name", Value: "B-Value", Description: "B-Description."},
 				},
 			})
 			assert.NoError(t, err)
@@ -86,44 +79,130 @@ func newRichSelect(ptty *ptytest.PTY, opts cliui.RichSelectOptions) (string, err
 	return value, inv.Run()
 }
 
-func TestMultiSelect(t *testing.T) {
+func TestRichMultiSelect(t *testing.T) {
 	t.Parallel()
-	t.Run("MultiSelect", func(t *testing.T) {
-		items := []string{"aaa", "bbb", "ccc"}
 
-		t.Parallel()
-		ptty := ptytest.New(t)
-		msgChan := make(chan []string)
-		go func() {
-			resp, err := newMultiSelect(ptty, items)
-			assert.NoError(t, err)
-			msgChan <- resp
-		}()
-		require.Equal(t, items, <-msgChan)
-	})
+	tests := []struct {
+		name        string
+		options     []codersdk.TemplateVersionParameterOption
+		defaults    []string
+		allowCustom bool
+		want        []string
+	}{
+		{
+			name: "Predefined",
+			options: []codersdk.TemplateVersionParameterOption{
+				{Name: "AAA", Description: "This is AAA", Value: "aaa"},
+				{Name: "BBB", Description: "This is BBB", Value: "bbb"},
+				{Name: "CCC", Description: "This is CCC", Value: "ccc"},
+			},
+			defaults:    []string{"bbb", "ccc"},
+			allowCustom: false,
+			want:        []string{"bbb", "ccc"},
+		},
+		{
+			name: "Custom",
+			options: []codersdk.TemplateVersionParameterOption{
+				{Name: "AAA", Description: "This is AAA", Value: "aaa"},
+				{Name: "BBB", Description: "This is BBB", Value: "bbb"},
+				{Name: "CCC", Description: "This is CCC", Value: "ccc"},
+			},
+			defaults:    []string{"aaa", "bbb"},
+			allowCustom: true,
+			want:        []string{"aaa", "bbb"},
+		},
+		{
+			name: "NoOptionSelected",
+			options: []codersdk.TemplateVersionParameterOption{
+				{Name: "AAA", Description: "This is AAA", Value: "aaa"},
+				{Name: "BBB", Description: "This is BBB", Value: "bbb"},
+				{Name: "CCC", Description: "This is CCC", Value: "ccc"},
+			},
+			defaults:    []string{},
+			allowCustom: false,
+			want:        []string{},
+		},
+	}
 
-	t.Run("MultiSelectWithCustomInput", func(t *testing.T) {
-		t.Parallel()
-		items := []string{"Code", "Chairs", "Whale", "Diamond", "Carrot"}
-		ptty := ptytest.New(t)
-		msgChan := make(chan []string)
-		go func() {
-			resp, err := newMultiSelectWithCustomInput(ptty, items)
-			assert.NoError(t, err)
-			msgChan <- resp
-		}()
-		require.Equal(t, items, <-msgChan)
-	})
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			var selectedItems []string
+			var err error
+			cmd := &serpent.Command{
+				Handler: func(inv *serpent.Invocation) error {
+					selectedItems, err = cliui.RichMultiSelect(inv, cliui.RichMultiSelectOptions{
+						Options:           tt.options,
+						Defaults:          tt.defaults,
+						EnableCustomInput: tt.allowCustom,
+					})
+					return err
+				},
+			}
+
+			doneChan := make(chan struct{})
+			go func() {
+				defer close(doneChan)
+				err := cmd.Invoke().Run()
+				assert.NoError(t, err)
+			}()
+			<-doneChan
+
+			require.Equal(t, tt.want, selectedItems)
+		})
+	}
 }
 
-func newMultiSelectWithCustomInput(ptty *ptytest.PTY, items []string) ([]string, error) {
+func TestMultiSelect(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name        string
+		items       []string
+		allowCustom bool
+		want        []string
+	}{
+		{
+			name:        "MultiSelect",
+			items:       []string{"aaa", "bbb", "ccc"},
+			allowCustom: false,
+			want:        []string{"aaa", "bbb", "ccc"},
+		},
+		{
+			name:        "MultiSelectWithCustomInput",
+			items:       []string{"Code", "Chairs", "Whale", "Diamond", "Carrot"},
+			allowCustom: true,
+			want:        []string{"Code", "Chairs", "Whale", "Diamond", "Carrot"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			ptty := ptytest.New(t)
+			msgChan := make(chan []string)
+
+			go func() {
+				resp, err := newMultiSelect(ptty, tt.items, tt.allowCustom)
+				assert.NoError(t, err)
+				msgChan <- resp
+			}()
+
+			require.Equal(t, tt.want, <-msgChan)
+		})
+	}
+}
+
+func newMultiSelect(pty *ptytest.PTY, items []string, custom bool) ([]string, error) {
 	var values []string
 	cmd := &serpent.Command{
 		Handler: func(inv *serpent.Invocation) error {
 			selectedItems, err := cliui.MultiSelect(inv, cliui.MultiSelectOptions{
 				Options:           items,
 				Defaults:          items,
-				EnableCustomInput: true,
+				EnableCustomInput: custom,
 			})
 			if err == nil {
 				values = selectedItems
@@ -132,25 +211,6 @@ func newMultiSelectWithCustomInput(ptty *ptytest.PTY, items []string) ([]string,
 		},
 	}
 	inv := cmd.Invoke()
-	ptty.Attach(inv)
-	return values, inv.Run()
-}
-
-func newMultiSelect(ptty *ptytest.PTY, items []string) ([]string, error) {
-	var values []string
-	cmd := &serpent.Command{
-		Handler: func(inv *serpent.Invocation) error {
-			selectedItems, err := cliui.MultiSelect(inv, cliui.MultiSelectOptions{
-				Options:  items,
-				Defaults: items,
-			})
-			if err == nil {
-				values = selectedItems
-			}
-			return err
-		},
-	}
-	inv := cmd.Invoke()
-	ptty.Attach(inv)
+	pty.Attach(inv)
 	return values, inv.Run()
 }

cli/configssh.go

@@ -446,7 +446,7 @@ func (r *RootCmd) configSSH() *serpent.Command {
 
 			if !bytes.Equal(configRaw, configModified) {
 				sshDir := filepath.Dir(sshConfigFile)
-				if err := os.MkdirAll(sshDir, 0700); err != nil {
+				if err := os.MkdirAll(sshDir, 0o700); err != nil {
 					return xerrors.Errorf("failed to create directory %q: %w", sshDir, err)
 				}
 

cli/configssh_test.go

@@ -204,10 +204,11 @@ func TestConfigSSH_MissingDirectory(t *testing.T) {
 	_, err = os.Stat(sshConfigPath)
 	require.NoError(t, err, "config file should exist")
 
-	// Check that the directory has proper permissions (0700)
+	// Check that the directory has proper permissions (rwx for owner, none for
+	// group and everyone)
 	sshDirInfo, err := os.Stat(sshDir)
 	require.NoError(t, err)
-	require.Equal(t, os.FileMode(0700), sshDirInfo.Mode().Perm(), "directory should have 0700 permissions")
+	require.Equal(t, os.FileMode(0o700), sshDirInfo.Mode().Perm(), "directory should have rwx------ permissions")
 }
 
 func TestConfigSSH_FileWriteAndOptionsFlow(t *testing.T) {
@@ -358,7 +359,8 @@ func TestConfigSSH_FileWriteAndOptionsFlow(t *testing.T) {
 					strings.Join([]string{
 						headerEnd,
 						"",
-					}, "\n")},
+					}, "\n"),
+				},
 			},
 			args: []string{"--ssh-option", "ForwardAgent=yes"},
 			matches: []match{
@@ -383,7 +385,8 @@ func TestConfigSSH_FileWriteAndOptionsFlow(t *testing.T) {
 					strings.Join([]string{
 						headerEnd,
 						"",
-					}, "\n")},
+					}, "\n"),
+				},
 			},
 			args: []string{"--ssh-option", "ForwardAgent=yes"},
 			matches: []match{

cli/create.go

@@ -2,6 +2,7 @@ package cli
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"io"
 	"slices"
@@ -21,10 +22,23 @@ import (
 	"github.com/coder/serpent"
 )
 
-func (r *RootCmd) create() *serpent.Command {
+// PresetNone represents the special preset value "none".
+// It is used when a user runs `create --preset none`,
+// indicating that the CLI should not apply any preset.
+const PresetNone = "none"
+
+var ErrNoPresetFound = xerrors.New("no preset found")
+
+type CreateOptions struct {
+	BeforeCreate func(ctx context.Context, client *codersdk.Client, template codersdk.Template, templateVersionID uuid.UUID) error
+	AfterCreate  func(ctx context.Context, inv *serpent.Invocation, client *codersdk.Client, workspace codersdk.Workspace) error
+}
+
+func (r *RootCmd) Create(opts CreateOptions) *serpent.Command {
 	var (
 		templateName    string
 		templateVersion string
+		presetName      string
 		startAt         string
 		stopAfter       time.Duration
 		workspaceName   string
@@ -263,11 +277,52 @@ func (r *RootCmd) create() *serpent.Command {
 				}
 			}
 
+			// Get presets for the template version
+			tvPresets, err := client.TemplateVersionPresets(inv.Context(), templateVersionID)
+			if err != nil {
+				return xerrors.Errorf("failed to get presets: %w", err)
+			}
+
+			var preset *codersdk.Preset
+			var presetParameters []codersdk.WorkspaceBuildParameter
+
+			// If the template has no presets, or the user explicitly used --preset none,
+			// skip applying a preset
+			if len(tvPresets) > 0 && strings.ToLower(presetName) != PresetNone {
+				// Attempt to resolve which preset to use
+				preset, err = resolvePreset(tvPresets, presetName)
+				if err != nil {
+					if !errors.Is(err, ErrNoPresetFound) {
+						return xerrors.Errorf("unable to resolve preset: %w", err)
+					}
+					// If no preset found, prompt the user to choose a preset
+					if preset, err = promptPresetSelection(inv, tvPresets); err != nil {
+						return xerrors.Errorf("unable to prompt user for preset: %w", err)
+					}
+				}
+
+				// Convert preset parameters into workspace build parameters
+				presetParameters = presetParameterAsWorkspaceBuildParameters(preset.Parameters)
+				// Inform the user which preset was applied and its parameters
+				displayAppliedPreset(inv, preset, presetParameters)
+			} else {
+				// Inform the user that no preset was applied
+				_, _ = fmt.Fprintf(inv.Stdout, "%s", cliui.Bold("No preset applied."))
+			}
+
+			if opts.BeforeCreate != nil {
+				err = opts.BeforeCreate(inv.Context(), client, template, templateVersionID)
+				if err != nil {
+					return xerrors.Errorf("before create: %w", err)
+				}
+			}
+
 			richParameters, err := prepWorkspaceBuild(inv, client, prepWorkspaceBuildArgs{
 				Action:            WorkspaceCreate,
 				TemplateVersionID: templateVersionID,
 				NewWorkspaceName:  workspaceName,
 
+				PresetParameters:      presetParameters,
 				RichParameterFile:     parameterFlags.richParameterFile,
 				RichParameters:        cliBuildParameters,
 				RichParameterDefaults: cliBuildParameterDefaults,
@@ -291,14 +346,21 @@ func (r *RootCmd) create() *serpent.Command {
 				ttlMillis = ptr.Ref(stopAfter.Milliseconds())
 			}
 
-			workspace, err := client.CreateUserWorkspace(inv.Context(), workspaceOwner, codersdk.CreateWorkspaceRequest{
+			req := codersdk.CreateWorkspaceRequest{
 				TemplateVersionID:   templateVersionID,
 				Name:                workspaceName,
 				AutostartSchedule:   schedSpec,
 				TTLMillis:           ttlMillis,
 				RichParameterValues: richParameters,
 				AutomaticUpdates:    codersdk.AutomaticUpdates(autoUpdates),
-			})
+			}
+
+			// If a preset exists, update the create workspace request's preset ID
+			if preset != nil {
+				req.TemplateVersionPresetID = preset.ID
+			}
+
+			workspace, err := client.CreateUserWorkspace(inv.Context(), workspaceOwner, req)
 			if err != nil {
 				return xerrors.Errorf("create workspace: %w", err)
 			}
@@ -316,6 +378,14 @@ func (r *RootCmd) create() *serpent.Command {
 				cliui.Keyword(workspace.Name),
 				cliui.Timestamp(time.Now()),
 			)
+
+			if opts.AfterCreate != nil {
+				err = opts.AfterCreate(inv.Context(), inv, client, workspace)
+				if err != nil {
+					return err
+				}
+			}
+
 			return nil
 		},
 	}
@@ -333,6 +403,12 @@ func (r *RootCmd) create() *serpent.Command {
 			Description: "Specify a template version name.",
 			Value:       serpent.StringOf(&templateVersion),
 		},
+		serpent.Option{
+			Flag:        "preset",
+			Env:         "CODER_PRESET_NAME",
+			Description: "Specify the name of a template version preset. Use 'none' to explicitly indicate that no preset should be used.",
+			Value:       serpent.StringOf(&presetName),
+		},
 		serpent.Option{
 			Flag:        "start-at",
 			Env:         "CODER_WORKSPACE_START_AT",
@@ -377,12 +453,81 @@ type prepWorkspaceBuildArgs struct {
 	PromptEphemeralParameters bool
 	EphemeralParameters       []codersdk.WorkspaceBuildParameter
 
+	PresetParameters      []codersdk.WorkspaceBuildParameter
 	PromptRichParameters  bool
 	RichParameters        []codersdk.WorkspaceBuildParameter
 	RichParameterFile     string
 	RichParameterDefaults []codersdk.WorkspaceBuildParameter
 }
 
+// resolvePreset returns the preset matching the given presetName (if specified),
+// or the default preset (if any).
+// Returns ErrNoPresetFound if no matching or default preset is found.
+func resolvePreset(presets []codersdk.Preset, presetName string) (*codersdk.Preset, error) {
+	// If preset name is specified, find it
+	if presetName != "" {
+		for _, p := range presets {
+			if p.Name == presetName {
+				return &p, nil
+			}
+		}
+		return nil, xerrors.Errorf("preset %q not found", presetName)
+	}
+
+	// No preset name specified, search for the default preset
+	for _, p := range presets {
+		if p.Default {
+			return &p, nil
+		}
+	}
+
+	// No preset found
+	return nil, ErrNoPresetFound
+}
+
+// promptPresetSelection shows a CLI selection menu of the presets defined in the template version.
+// Returns the selected preset
+func promptPresetSelection(inv *serpent.Invocation, presets []codersdk.Preset) (*codersdk.Preset, error) {
+	presetMap := make(map[string]*codersdk.Preset)
+	var presetOptions []string
+
+	for _, preset := range presets {
+		var option string
+		if preset.Description == "" {
+			option = preset.Name
+		} else {
+			option = fmt.Sprintf("%s: %s", preset.Name, preset.Description)
+		}
+		presetOptions = append(presetOptions, option)
+		presetMap[option] = &preset
+	}
+
+	// Show selection UI
+	_, _ = fmt.Fprintln(inv.Stdout, pretty.Sprint(cliui.DefaultStyles.Wrap, "Select a preset below:"))
+	selected, err := cliui.Select(inv, cliui.SelectOptions{
+		Options:    presetOptions,
+		HideSearch: true,
+	})
+	if err != nil {
+		return nil, xerrors.Errorf("failed to select preset: %w", err)
+	}
+
+	return presetMap[selected], nil
+}
+
+// displayAppliedPreset shows the user which preset was applied and its parameters
+func displayAppliedPreset(inv *serpent.Invocation, preset *codersdk.Preset, parameters []codersdk.WorkspaceBuildParameter) {
+	label := fmt.Sprintf("Preset '%s'", preset.Name)
+	if preset.Default {
+		label += " (default)"
+	}
+
+	_, _ = fmt.Fprintf(inv.Stdout, "%s applied:\n", cliui.Bold(label))
+	for _, param := range parameters {
+		_, _ = fmt.Fprintf(inv.Stdout, "  %s: '%s'\n", cliui.Bold(param.Name), param.Value)
+	}
+}
+
 // prepWorkspaceBuild will ensure a workspace build will succeed on the latest template version.
 // Any missing params will be prompted to the user. It supports rich parameters.
 func prepWorkspaceBuild(inv *serpent.Invocation, client *codersdk.Client, args prepWorkspaceBuildArgs) ([]codersdk.WorkspaceBuildParameter, error) {
@@ -411,6 +556,7 @@ func prepWorkspaceBuild(inv *serpent.Invocation, client *codersdk.Client, args p
 		WithSourceWorkspaceParameters(args.SourceWorkspaceParameters).
 		WithPromptEphemeralParameters(args.PromptEphemeralParameters).
 		WithEphemeralParameters(args.EphemeralParameters).
+		WithPresetParameters(args.PresetParameters).
 		WithPromptRichParameters(args.PromptRichParameters).
 		WithRichParameters(args.RichParameters).
 		WithRichParametersFile(parameterFile).

cli/create_test.go

@@ -12,6 +12,7 @@ import (
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
+	"github.com/coder/coder/v2/cli"
 	"github.com/coder/coder/v2/cli/clitest"
 	"github.com/coder/coder/v2/coderd/coderdtest"
 	"github.com/coder/coder/v2/coderd/externalauth"
@@ -298,7 +299,7 @@ func TestCreate(t *testing.T) {
 	})
 }
 
-func prepareEchoResponses(parameters []*proto.RichParameter) *echo.Responses {
+func prepareEchoResponses(parameters []*proto.RichParameter, presets ...*proto.Preset) *echo.Responses {
 	return &echo.Responses{
 		Parse: echo.ParseComplete,
 		ProvisionPlan: []*proto.Response{
@@ -306,6 +307,7 @@ func prepareEchoResponses(parameters []*proto.RichParameter) *echo.Responses {
 				Type: &proto.Response_Plan{
 					Plan: &proto.PlanComplete{
 						Parameters: parameters,
+						Presets:    presets,
 					},
 				},
 			},
@@ -663,6 +665,642 @@ func TestCreateWithRichParameters(t *testing.T) {
 	})
 }
 
+func TestCreateWithPreset(t *testing.T) {
+	t.Parallel()
+
+	const (
+		firstParameterName        = "first_parameter"
+		firstParameterDisplayName = "First Parameter"
+		firstParameterDescription = "This is the first parameter"
+		firstParameterValue       = "1"
+
+		firstOptionalParameterName         = "first_optional_parameter"
+		firstOptionalParameterDescription  = "This is the first optional parameter"
+		firstOptionalParameterValue        = "1"
+		secondOptionalParameterName        = "second_optional_parameter"
+		secondOptionalParameterDescription = "This is the second optional parameter"
+		secondOptionalParameterValue       = "2"
+
+		thirdParameterName        = "third_parameter"
+		thirdParameterDescription = "This is the third parameter"
+		thirdParameterValue       = "3"
+	)
+
+	echoResponses := func(presets ...*proto.Preset) *echo.Responses {
+		return prepareEchoResponses([]*proto.RichParameter{
+			{
+				Name:         firstParameterName,
+				DisplayName:  firstParameterDisplayName,
+				Description:  firstParameterDescription,
+				Mutable:      true,
+				DefaultValue: firstParameterValue,
+				Options: []*proto.RichParameterOption{
+					{
+						Name:        firstOptionalParameterName,
+						Description: firstOptionalParameterDescription,
+						Value:       firstOptionalParameterValue,
+					},
+					{
+						Name:        secondOptionalParameterName,
+						Description: secondOptionalParameterDescription,
+						Value:       secondOptionalParameterValue,
+					},
+				},
+			},
+			{
+				Name:         thirdParameterName,
+				Description:  thirdParameterDescription,
+				DefaultValue: thirdParameterValue,
+				Mutable:      true,
+			},
+		}, presets...)
+	}
+
+	// This test verifies that when a template has presets,
+	// including a default preset, and the user specifies a `--preset` flag,
+	// the CLI uses the specified preset instead of the default
+	t.Run("PresetFlag", func(t *testing.T) {
+		t.Parallel()
+
+		client := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerDaemon: true})
+		owner := coderdtest.CreateFirstUser(t, client)
+		member, _ := coderdtest.CreateAnotherUser(t, client, owner.OrganizationID)
+
+		// Given: a template and a template version with two presets, including a default
+		defaultPreset := proto.Preset{
+			Name:    "preset-default",
+			Default: true,
+			Parameters: []*proto.PresetParameter{
+				{Name: thirdParameterName, Value: thirdParameterValue},
+			},
+		}
+		preset := proto.Preset{
+			Name: "preset-test",
+			Parameters: []*proto.PresetParameter{
+				{Name: firstParameterName, Value: secondOptionalParameterValue},
+				{Name: thirdParameterName, Value: thirdParameterValue},
+			},
+		}
+		version := coderdtest.CreateTemplateVersion(t, client, owner.OrganizationID, echoResponses(&defaultPreset, &preset))
+		coderdtest.AwaitTemplateVersionJobCompleted(t, client, version.ID)
+		template := coderdtest.CreateTemplate(t, client, owner.OrganizationID, version.ID)
+
+		// When: running the create command with the specified preset
+		workspaceName := "my-workspace"
+		inv, root := clitest.New(t, "create", workspaceName, "--template", template.Name, "-y", "--preset", preset.Name)
+		clitest.SetupConfig(t, member, root)
+		pty := ptytest.New(t).Attach(inv)
+		inv.Stdout = pty.Output()
+		inv.Stderr = pty.Output()
+		err := inv.Run()
+		require.NoError(t, err)
+
+		// Should: display the selected preset as well as its parameters
+		presetName := fmt.Sprintf("Preset '%s' applied:", preset.Name)
+		pty.ExpectMatch(presetName)
+		pty.ExpectMatch(fmt.Sprintf("%s: '%s'", firstParameterName, secondOptionalParameterValue))
+		pty.ExpectMatch(fmt.Sprintf("%s: '%s'", thirdParameterName, thirdParameterValue))
+
+		// Verify if the new workspace uses expected parameters.
+		ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitShort)
+		defer cancel()
+
+		tvPresets, err := client.TemplateVersionPresets(ctx, version.ID)
+		require.NoError(t, err)
+		require.Len(t, tvPresets, 2)
+		var selectedPreset *codersdk.Preset
+		for _, tvPreset := range tvPresets {
+			if tvPreset.Name == preset.Name {
+				selectedPreset = &tvPreset
+			}
+		}
+		require.NotNil(t, selectedPreset)
+
+		workspaces, err := client.Workspaces(ctx, codersdk.WorkspaceFilter{
+			Name: workspaceName,
+		})
+		require.NoError(t, err)
+		require.Len(t, workspaces.Workspaces, 1)
+
+		// Should: create a workspace using the expected template version and the preset-defined parameters
+		workspaceLatestBuild := workspaces.Workspaces[0].LatestBuild
+		require.Equal(t, version.ID, workspaceLatestBuild.TemplateVersionID)
+		require.Equal(t, selectedPreset.ID, *workspaceLatestBuild.TemplateVersionPresetID)
+		buildParameters, err := client.WorkspaceBuildParameters(ctx, workspaceLatestBuild.ID)
+		require.NoError(t, err)
+		require.Len(t, buildParameters, 2)
+		require.Contains(t, buildParameters, codersdk.WorkspaceBuildParameter{Name: firstParameterName, Value: secondOptionalParameterValue})
+		require.Contains(t, buildParameters, codersdk.WorkspaceBuildParameter{Name: thirdParameterName, Value: thirdParameterValue})
+	})
+
+	// This test verifies that when a template has presets,
+	// including a default preset, and the user does not specify the `--preset` flag,
+	// the CLI automatically uses the default preset to create the workspace
+	t.Run("DefaultPreset", func(t *testing.T) {
+		t.Parallel()
+
+		client := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerDaemon: true})
+		owner := coderdtest.CreateFirstUser(t, client)
+		member, _ := coderdtest.CreateAnotherUser(t, client, owner.OrganizationID)
+
+		// Given: a template and a template version with two presets, including a default
+		defaultPreset := proto.Preset{
+			Name:    "preset-default",
+			Default: true,
+			Parameters: []*proto.PresetParameter{
+				{Name: firstParameterName, Value: secondOptionalParameterValue},
+				{Name: thirdParameterName, Value: thirdParameterValue},
+			},
+		}
+		preset := proto.Preset{
+			Name: "preset-test",
+			Parameters: []*proto.PresetParameter{
+				{Name: thirdParameterName, Value: thirdParameterValue},
+			},
+		}
+		version := coderdtest.CreateTemplateVersion(t, client, owner.OrganizationID, echoResponses(&defaultPreset, &preset))
+		coderdtest.AwaitTemplateVersionJobCompleted(t, client, version.ID)
+		template := coderdtest.CreateTemplate(t, client, owner.OrganizationID, version.ID)
+
+		// When: running the create command without a preset
+		workspaceName := "my-workspace"
+		inv, root := clitest.New(t, "create", workspaceName, "--template", template.Name, "-y")
+		clitest.SetupConfig(t, member, root)
+		pty := ptytest.New(t).Attach(inv)
+		inv.Stdout = pty.Output()
+		inv.Stderr = pty.Output()
+		err := inv.Run()
+		require.NoError(t, err)
+
+		// Should: display the default preset as well as its parameters
+		presetName := fmt.Sprintf("Preset '%s' (default) applied:", defaultPreset.Name)
+		pty.ExpectMatch(presetName)
+		pty.ExpectMatch(fmt.Sprintf("%s: '%s'", firstParameterName, secondOptionalParameterValue))
+		pty.ExpectMatch(fmt.Sprintf("%s: '%s'", thirdParameterName, thirdParameterValue))
+
+		// Verify if the new workspace uses expected parameters.
+		ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitShort)
+		defer cancel()
+
+		tvPresets, err := client.TemplateVersionPresets(ctx, version.ID)
+		require.NoError(t, err)
+		require.Len(t, tvPresets, 2)
+		var selectedPreset *codersdk.Preset
+		for _, tvPreset := range tvPresets {
+			if tvPreset.Default {
+				selectedPreset = &tvPreset
+			}
+		}
+		require.NotNil(t, selectedPreset)
+
+		workspaces, err := client.Workspaces(ctx, codersdk.WorkspaceFilter{
+			Name: workspaceName,
+		})
+		require.NoError(t, err)
+		require.Len(t, workspaces.Workspaces, 1)
+
+		// Should: create a workspace using the expected template version and the default preset parameters
+		workspaceLatestBuild := workspaces.Workspaces[0].LatestBuild
+		require.Equal(t, version.ID, workspaceLatestBuild.TemplateVersionID)
+		require.Equal(t, selectedPreset.ID, *workspaceLatestBuild.TemplateVersionPresetID)
+		buildParameters, err := client.WorkspaceBuildParameters(ctx, workspaceLatestBuild.ID)
+		require.NoError(t, err)
+		require.Len(t, buildParameters, 2)
+		require.Contains(t, buildParameters, codersdk.WorkspaceBuildParameter{Name: firstParameterName, Value: secondOptionalParameterValue})
+		require.Contains(t, buildParameters, codersdk.WorkspaceBuildParameter{Name: thirdParameterName, Value: thirdParameterValue})
+	})
+
+	// This test verifies that when a template has presets but no default preset,
+	// and the user does not provide the `--preset` flag,
+	// the CLI prompts the user to select a preset.
+	t.Run("NoDefaultPresetPromptUser", func(t *testing.T) {
+		t.Parallel()
+
+		client := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerDaemon: true})
+		owner := coderdtest.CreateFirstUser(t, client)
+		member, _ := coderdtest.CreateAnotherUser(t, client, owner.OrganizationID)
+
+		// Given: a template and a template version with two presets
+		preset := proto.Preset{
+			Name:        "preset-test",
+			Description: "Preset Test.",
+			Parameters: []*proto.PresetParameter{
+				{Name: firstParameterName, Value: secondOptionalParameterValue},
+				{Name: thirdParameterName, Value: thirdParameterValue},
+			},
+		}
+		version := coderdtest.CreateTemplateVersion(t, client, owner.OrganizationID, echoResponses(&preset))
+		coderdtest.AwaitTemplateVersionJobCompleted(t, client, version.ID)
+		template := coderdtest.CreateTemplate(t, client, owner.OrganizationID, version.ID)
+
+		// When: running the create command without specifying a preset
+		workspaceName := "my-workspace"
+		inv, root := clitest.New(t, "create", workspaceName, "--template", template.Name,
+			"--parameter", fmt.Sprintf("%s=%s", firstParameterName, firstOptionalParameterValue),
+			"--parameter", fmt.Sprintf("%s=%s", thirdParameterName, thirdParameterValue))
+		clitest.SetupConfig(t, member, root)
+		doneChan := make(chan struct{})
+		pty := ptytest.New(t).Attach(inv)
+		go func() {
+			defer close(doneChan)
+			err := inv.Run()
+			assert.NoError(t, err)
+		}()
+
+		// Should: prompt the user for the preset
+		pty.ExpectMatch("Select a preset below:")
+		pty.WriteLine("\n")
+		pty.ExpectMatch("Preset 'preset-test' applied")
+		pty.ExpectMatch("Confirm create?")
+		pty.WriteLine("yes")
+
+		<-doneChan
+
+		// Verify if the new workspace uses expected parameters.
+		ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitShort)
+		defer cancel()
+
+		tvPresets, err := client.TemplateVersionPresets(ctx, version.ID)
+		require.NoError(t, err)
+		require.Len(t, tvPresets, 1)
+
+		workspaces, err := client.Workspaces(ctx, codersdk.WorkspaceFilter{
+			Name: workspaceName,
+		})
+		require.NoError(t, err)
+		require.Len(t, workspaces.Workspaces, 1)
+
+		// Should: create a workspace using the expected template version and the preset-defined parameters
+		workspaceLatestBuild := workspaces.Workspaces[0].LatestBuild
+		require.Equal(t, version.ID, workspaceLatestBuild.TemplateVersionID)
+		require.Equal(t, tvPresets[0].ID, *workspaceLatestBuild.TemplateVersionPresetID)
+		buildParameters, err := client.WorkspaceBuildParameters(ctx, workspaceLatestBuild.ID)
+		require.NoError(t, err)
+		require.Len(t, buildParameters, 2)
+		require.Contains(t, buildParameters, codersdk.WorkspaceBuildParameter{Name: firstParameterName, Value: secondOptionalParameterValue})
+		require.Contains(t, buildParameters, codersdk.WorkspaceBuildParameter{Name: thirdParameterName, Value: thirdParameterValue})
+	})
+
+	// This test verifies that when a template version has no presets,
+	// the CLI does not prompt the user to select a preset and proceeds
+	// with workspace creation without applying any preset.
+	t.Run("TemplateVersionWithoutPresets", func(t *testing.T) {
+		t.Parallel()
+
+		client := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerDaemon: true})
+		owner := coderdtest.CreateFirstUser(t, client)
+		member, _ := coderdtest.CreateAnotherUser(t, client, owner.OrganizationID)
+
+		// Given: a template and a template version without presets
+		version := coderdtest.CreateTemplateVersion(t, client, owner.OrganizationID, echoResponses())
+		coderdtest.AwaitTemplateVersionJobCompleted(t, client, version.ID)
+		template := coderdtest.CreateTemplate(t, client, owner.OrganizationID, version.ID)
+
+		// When: running the create command without a preset
+		workspaceName := "my-workspace"
+		inv, root := clitest.New(t, "create", workspaceName, "--template", template.Name, "-y",
+			"--parameter", fmt.Sprintf("%s=%s", firstParameterName, firstOptionalParameterValue),
+			"--parameter", fmt.Sprintf("%s=%s", thirdParameterName, thirdParameterValue))
+		clitest.SetupConfig(t, member, root)
+		pty := ptytest.New(t).Attach(inv)
+		inv.Stdout = pty.Output()
+		inv.Stderr = pty.Output()
+		err := inv.Run()
+		require.NoError(t, err)
+		pty.ExpectMatch("No preset applied.")
+
+		// Verify if the new workspace uses expected parameters.
+		ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitShort)
+		defer cancel()
+
+		workspaces, err := client.Workspaces(ctx, codersdk.WorkspaceFilter{
+			Name: workspaceName,
+		})
+		require.NoError(t, err)
+		require.Len(t, workspaces.Workspaces, 1)
+
+		// Should: create a workspace using the expected template version and no preset
+		workspaceLatestBuild := workspaces.Workspaces[0].LatestBuild
+		require.Equal(t, version.ID, workspaceLatestBuild.TemplateVersionID)
+		require.Nil(t, workspaceLatestBuild.TemplateVersionPresetID)
+		buildParameters, err := client.WorkspaceBuildParameters(ctx, workspaceLatestBuild.ID)
+		require.NoError(t, err)
+		require.Len(t, buildParameters, 2)
+		require.Contains(t, buildParameters, codersdk.WorkspaceBuildParameter{Name: firstParameterName, Value: firstOptionalParameterValue})
+		require.Contains(t, buildParameters, codersdk.WorkspaceBuildParameter{Name: thirdParameterName, Value: thirdParameterValue})
+	})
+
+	// This test verifies that when the user provides `--preset none`,
+	// the CLI skips applying any preset, even if the template version has a default preset.
+	// The workspace should be created without using any preset-defined parameters.
+	t.Run("PresetFlagNone", func(t *testing.T) {
+		t.Parallel()
+
+		client := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerDaemon: true})
+		owner := coderdtest.CreateFirstUser(t, client)
+		member, _ := coderdtest.CreateAnotherUser(t, client, owner.OrganizationID)
+
+		// Given: a template and a template version with a default preset
+		preset := proto.Preset{
+			Name:    "preset-test",
+			Default: true,
+			Parameters: []*proto.PresetParameter{
+				{Name: firstParameterName, Value: secondOptionalParameterValue},
+				{Name: thirdParameterName, Value: thirdParameterValue},
+			},
+		}
+		version := coderdtest.CreateTemplateVersion(t, client, owner.OrganizationID, echoResponses(&preset))
+		coderdtest.AwaitTemplateVersionJobCompleted(t, client, version.ID)
+		template := coderdtest.CreateTemplate(t, client, owner.OrganizationID, version.ID)
+
+		// When: running the create command with flag '--preset none'
+		workspaceName := "my-workspace"
+		inv, root := clitest.New(t, "create", workspaceName, "--template", template.Name, "-y", "--preset", cli.PresetNone,
+			"--parameter", fmt.Sprintf("%s=%s", firstParameterName, firstOptionalParameterValue),
+			"--parameter", fmt.Sprintf("%s=%s", thirdParameterName, thirdParameterValue))
+		clitest.SetupConfig(t, member, root)
+		pty := ptytest.New(t).Attach(inv)
+		inv.Stdout = pty.Output()
+		inv.Stderr = pty.Output()
+		err := inv.Run()
+		require.NoError(t, err)
+		pty.ExpectMatch("No preset applied.")
+
+		// Verify that the new workspace doesn't use the preset parameters.
+		ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitShort)
+		defer cancel()
+
+		tvPresets, err := client.TemplateVersionPresets(ctx, version.ID)
+		require.NoError(t, err)
+		require.Len(t, tvPresets, 1)
+
+		workspaces, err := client.Workspaces(ctx, codersdk.WorkspaceFilter{
+			Name: workspaceName,
+		})
+		require.NoError(t, err)
+		require.Len(t, workspaces.Workspaces, 1)
+
+		// Should: create a workspace using the expected template version and no preset
+		workspaceLatestBuild := workspaces.Workspaces[0].LatestBuild
+		require.Equal(t, version.ID, workspaceLatestBuild.TemplateVersionID)
+		require.Nil(t, workspaceLatestBuild.TemplateVersionPresetID)
+		buildParameters, err := client.WorkspaceBuildParameters(ctx, workspaceLatestBuild.ID)
+		require.NoError(t, err)
+		require.Len(t, buildParameters, 2)
+		require.Contains(t, buildParameters, codersdk.WorkspaceBuildParameter{Name: firstParameterName, Value: firstOptionalParameterValue})
+		require.Contains(t, buildParameters, codersdk.WorkspaceBuildParameter{Name: thirdParameterName, Value: thirdParameterValue})
+	})
+
+	// This test verifies that the CLI returns an appropriate error
+	// when a user provides a `--preset` value that does not correspond
+	// to any existing preset in the template version.
+	t.Run("FailsWhenPresetDoesNotExist", func(t *testing.T) {
+		t.Parallel()
+
+		client := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerDaemon: true})
+		owner := coderdtest.CreateFirstUser(t, client)
+		member, _ := coderdtest.CreateAnotherUser(t, client, owner.OrganizationID)
+
+		// Given: a template and a template version where the preset defines values for all required parameters
+		preset := proto.Preset{
+			Name: "preset-test",
+			Parameters: []*proto.PresetParameter{
+				{Name: firstParameterName, Value: secondOptionalParameterValue},
+				{Name: thirdParameterName, Value: thirdParameterValue},
+			},
+		}
+		version := coderdtest.CreateTemplateVersion(t, client, owner.OrganizationID, echoResponses(&preset))
+		coderdtest.AwaitTemplateVersionJobCompleted(t, client, version.ID)
+		template := coderdtest.CreateTemplate(t, client, owner.OrganizationID, version.ID)
+
+		// When: running the create command with a non-existent preset
+		workspaceName := "my-workspace"
+		inv, root := clitest.New(t, "create", workspaceName, "--template", template.Name, "-y", "--preset", "invalid-preset")
+		clitest.SetupConfig(t, member, root)
+		pty := ptytest.New(t).Attach(inv)
+		inv.Stdout = pty.Output()
+		inv.Stderr = pty.Output()
+		err := inv.Run()
+
+		// Should: fail with an error indicating the preset was not found
+		require.Contains(t, err.Error(), "preset \"invalid-preset\" not found")
+	})
+
+	// This test verifies that when both a preset and a user-provided
+	// `--parameter` flag define a value for the same parameter,
+	// the preset's value takes precedence over the user's.
+	//
+	// The preset defines one parameter (A), and two `--parameter` flags provide A and B.
+	// The workspace should be created using:
+	// - the value of parameter A from the preset (overriding the parameter flag's value),
+	// - and the value of parameter B from the parameter flag.
+	t.Run("PresetOverridesParameterFlagValues", func(t *testing.T) {
+		t.Parallel()
+
+		client := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerDaemon: true})
+		owner := coderdtest.CreateFirstUser(t, client)
+		member, _ := coderdtest.CreateAnotherUser(t, client, owner.OrganizationID)
+
+		// Given: a template version with a preset that defines one parameter
+		preset := proto.Preset{
+			Name: "preset-test",
+			Parameters: []*proto.PresetParameter{
+				{Name: firstParameterName, Value: secondOptionalParameterValue},
+			},
+		}
+		version := coderdtest.CreateTemplateVersion(t, client, owner.OrganizationID, echoResponses(&preset))
+		coderdtest.AwaitTemplateVersionJobCompleted(t, client, version.ID)
+		template := coderdtest.CreateTemplate(t, client, owner.OrganizationID, version.ID)
+
+		// When: creating a workspace with a preset and passing overlapping and additional parameters via `--parameter`
+		workspaceName := "my-workspace"
+		inv, root := clitest.New(t, "create", workspaceName, "--template", template.Name, "-y",
+			"--preset", preset.Name,
+			"--parameter", fmt.Sprintf("%s=%s", firstParameterName, firstOptionalParameterValue),
+			"--parameter", fmt.Sprintf("%s=%s", thirdParameterName, thirdParameterValue))
+		clitest.SetupConfig(t, member, root)
+		pty := ptytest.New(t).Attach(inv)
+		inv.Stdout = pty.Output()
+		inv.Stderr = pty.Output()
+		err := inv.Run()
+		require.NoError(t, err)
+
+		// Should: display the selected preset as well as its parameter
+		presetName := fmt.Sprintf("Preset '%s' applied:", preset.Name)
+		pty.ExpectMatch(presetName)
+		pty.ExpectMatch(fmt.Sprintf("%s: '%s'", firstParameterName, secondOptionalParameterValue))
+
+		// Verify if the new workspace uses expected parameters.
+		ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitShort)
+		defer cancel()
+
+		tvPresets, err := client.TemplateVersionPresets(ctx, version.ID)
+		require.NoError(t, err)
+		require.Len(t, tvPresets, 1)
+
+		workspaces, err := client.Workspaces(ctx, codersdk.WorkspaceFilter{
+			Name: workspaceName,
+		})
+		require.NoError(t, err)
+		require.Len(t, workspaces.Workspaces, 1)
+
+		// Should: include both parameters, one from the preset and one from the `--parameter` flag
+		workspaceLatestBuild := workspaces.Workspaces[0].LatestBuild
+		require.Equal(t, version.ID, workspaceLatestBuild.TemplateVersionID)
+		require.Equal(t, tvPresets[0].ID, *workspaceLatestBuild.TemplateVersionPresetID)
+		buildParameters, err := client.WorkspaceBuildParameters(ctx, workspaceLatestBuild.ID)
+		require.NoError(t, err)
+		require.Len(t, buildParameters, 2)
+		require.Contains(t, buildParameters, codersdk.WorkspaceBuildParameter{Name: firstParameterName, Value: secondOptionalParameterValue})
+		require.Contains(t, buildParameters, codersdk.WorkspaceBuildParameter{Name: thirdParameterName, Value: thirdParameterValue})
+	})
+
+	// This test verifies that when both a preset and a user-provided
+	// `--rich-parameter-file` define a value for the same parameter,
+	// the preset's value takes precedence over the one in the file.
+	//
+	// The preset defines one parameter (A), and the parameter file provides two parameters (A and B).
+	// The workspace should be created using:
+	// - the value of parameter A from the preset (overriding the file's value),
+	// - and the value of parameter B from the file.
+	t.Run("PresetOverridesParameterFileValues", func(t *testing.T) {
+		t.Parallel()
+
+		client := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerDaemon: true})
+		owner := coderdtest.CreateFirstUser(t, client)
+		member, _ := coderdtest.CreateAnotherUser(t, client, owner.OrganizationID)
+
+		// Given: a template version with a preset that defines one parameter
+		preset := proto.Preset{
+			Name: "preset-test",
+			Parameters: []*proto.PresetParameter{
+				{Name: firstParameterName, Value: secondOptionalParameterValue},
+			},
+		}
+		version := coderdtest.CreateTemplateVersion(t, client, owner.OrganizationID, echoResponses(&preset))
+		coderdtest.AwaitTemplateVersionJobCompleted(t, client, version.ID)
+		template := coderdtest.CreateTemplate(t, client, owner.OrganizationID, version.ID)
+
+		// When: creating a workspace with the preset and passing the second required parameter via `--rich-parameter-file`
+		workspaceName := "my-workspace"
+		tempDir := t.TempDir()
+		removeTmpDirUntilSuccessAfterTest(t, tempDir)
+		parameterFile, _ := os.CreateTemp(tempDir, "testParameterFile*.yaml")
+		_, _ = parameterFile.WriteString(
+			firstParameterName + ": " + firstOptionalParameterValue + "\n" +
+				thirdParameterName + ": " + thirdParameterValue)
+		inv, root := clitest.New(t, "create", workspaceName, "--template", template.Name, "-y",
+			"--preset", preset.Name,
+			"--rich-parameter-file", parameterFile.Name())
+		clitest.SetupConfig(t, member, root)
+		pty := ptytest.New(t).Attach(inv)
+		inv.Stdout = pty.Output()
+		inv.Stderr = pty.Output()
+		err := inv.Run()
+		require.NoError(t, err)
+
+		// Should: display the selected preset as well as its parameter
+		presetName := fmt.Sprintf("Preset '%s' applied:", preset.Name)
+		pty.ExpectMatch(presetName)
+		pty.ExpectMatch(fmt.Sprintf("%s: '%s'", firstParameterName, secondOptionalParameterValue))
+
+		// Verify if the new workspace uses expected parameters.
+		ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitShort)
+		defer cancel()
+
+		tvPresets, err := client.TemplateVersionPresets(ctx, version.ID)
+		require.NoError(t, err)
+		require.Len(t, tvPresets, 1)
+
+		workspaces, err := client.Workspaces(ctx, codersdk.WorkspaceFilter{
+			Name: workspaceName,
+		})
+		require.NoError(t, err)
+		require.Len(t, workspaces.Workspaces, 1)
+
+		// Should: include both parameters, one from the preset and one from the `--rich-parameter-file` flag
+		workspaceLatestBuild := workspaces.Workspaces[0].LatestBuild
+		require.Equal(t, version.ID, workspaceLatestBuild.TemplateVersionID)
+		require.Equal(t, tvPresets[0].ID, *workspaceLatestBuild.TemplateVersionPresetID)
+		buildParameters, err := client.WorkspaceBuildParameters(ctx, workspaceLatestBuild.ID)
+		require.NoError(t, err)
+		require.Len(t, buildParameters, 2)
+		require.Contains(t, buildParameters, codersdk.WorkspaceBuildParameter{Name: firstParameterName, Value: secondOptionalParameterValue})
+		require.Contains(t, buildParameters, codersdk.WorkspaceBuildParameter{Name: thirdParameterName, Value: thirdParameterValue})
+	})
+
+	// This test verifies that when a preset provides only some parameters,
+	// and the remaining ones are not provided via flags,
+	// the CLI prompts the user for input to fill in the missing parameters.
+	t.Run("PromptsForMissingParametersWhenPresetIsIncomplete", func(t *testing.T) {
+		t.Parallel()
+
+		client := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerDaemon: true})
+		owner := coderdtest.CreateFirstUser(t, client)
+		member, _ := coderdtest.CreateAnotherUser(t, client, owner.OrganizationID)
+
+		// Given: a template version with a preset that defines one parameter
+		preset := proto.Preset{
+			Name: "preset-test",
+			Parameters: []*proto.PresetParameter{
+				{Name: firstParameterName, Value: secondOptionalParameterValue},
+			},
+		}
+		version := coderdtest.CreateTemplateVersion(t, client, owner.OrganizationID, echoResponses(&preset))
+		coderdtest.AwaitTemplateVersionJobCompleted(t, client, version.ID)
+		template := coderdtest.CreateTemplate(t, client, owner.OrganizationID, version.ID)
+
+		// When: running the create command with the specified preset
+		workspaceName := "my-workspace"
+		inv, root := clitest.New(t, "create", workspaceName, "--template", template.Name, "--preset", preset.Name)
+		clitest.SetupConfig(t, member, root)
+		doneChan := make(chan struct{})
+		pty := ptytest.New(t).Attach(inv)
+		go func() {
+			defer close(doneChan)
+			err := inv.Run()
+			assert.NoError(t, err)
+		}()
+
+		// Should: display the selected preset as well as its parameters
+		presetName := fmt.Sprintf("Preset '%s' applied:", preset.Name)
+		pty.ExpectMatch(presetName)
+		pty.ExpectMatch(fmt.Sprintf("%s: '%s'", firstParameterName, secondOptionalParameterValue))
+
+		// Should: prompt for the missing parameter
+		pty.ExpectMatch(thirdParameterDescription)
+		pty.WriteLine(thirdParameterValue)
+		pty.ExpectMatch("Confirm create?")
+		pty.WriteLine("yes")
+
+		<-doneChan
+
+		// Verify if the new workspace uses expected parameters.
+		ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
+		defer cancel()
+
+		tvPresets, err := client.TemplateVersionPresets(ctx, version.ID)
+		require.NoError(t, err)
+		require.Len(t, tvPresets, 1)
+
+		workspaces, err := client.Workspaces(ctx, codersdk.WorkspaceFilter{
+			Name: workspaceName,
+		})
+		require.NoError(t, err)
+		require.Len(t, workspaces.Workspaces, 1)
+
+		// Should: create a workspace using the expected template version and the preset-defined parameters
+		workspaceLatestBuild := workspaces.Workspaces[0].LatestBuild
+		require.Equal(t, version.ID, workspaceLatestBuild.TemplateVersionID)
+		require.Equal(t, tvPresets[0].ID, *workspaceLatestBuild.TemplateVersionPresetID)
+		buildParameters, err := client.WorkspaceBuildParameters(ctx, workspaceLatestBuild.ID)
+		require.NoError(t, err)
+		require.Len(t, buildParameters, 2)
+		require.Contains(t, buildParameters, codersdk.WorkspaceBuildParameter{Name: firstParameterName, Value: secondOptionalParameterValue})
+		require.Contains(t, buildParameters, codersdk.WorkspaceBuildParameter{Name: thirdParameterName, Value: thirdParameterValue})
+	})
+}
+
 func TestCreateValidateRichParameters(t *testing.T) {
 	t.Parallel()
 

cli/delete_test.go

@@ -111,7 +111,6 @@ func TestDelete(t *testing.T) {
 		// The API checks if the user has any workspaces, so we cannot delete a user
 		// this way.
 		ctx := testutil.Context(t, testutil.WaitShort)
-		// nolint:gocritic // Unit test
 		err := api.Database.UpdateUserDeletedByID(dbauthz.AsSystemRestricted(ctx), deleteMeUser.ID)
 		require.NoError(t, err)
 
@@ -233,9 +232,6 @@ func TestDelete(t *testing.T) {
 			t.Skip("this test requires postgres")
 		}
 
-		clock := quartz.NewMock(t)
-		ctx := testutil.Context(t, testutil.WaitSuperLong)
-
 		// Setup
 		db, pb := dbtestutil.NewDB(t, dbtestutil.WithDumpOnFailure())
 		client, _ := coderdtest.NewWithProvisionerCloser(t, &coderdtest.Options{
@@ -301,6 +297,9 @@ func TestDelete(t *testing.T) {
 			t.Run(tc.name, func(t *testing.T) {
 				t.Parallel()
 
+				clock := quartz.NewMock(t)
+				ctx := testutil.Context(t, testutil.WaitSuperLong)
+
 				// Create one prebuilt workspace (owned by system user) and one normal workspace (owned by a user)
 				// Each workspace is persisted in the DB along with associated workspace jobs and builds.
 				dbPrebuiltWorkspace := setupTestDBWorkspace(t, clock, db, pb, orgID, database.PrebuildsSystemUserID, template.ID, version.ID, preset.ID)

cli/exp.go

@@ -16,6 +16,7 @@ func (r *RootCmd) expCmd() *serpent.Command {
 			r.mcpCommand(),
 			r.promptExample(),
 			r.rptyCommand(),
+			r.tasksCommand(),
 		},
 	}
 	return cmd

cli/exp_mcp.go

@@ -127,6 +127,7 @@ func (r *RootCmd) mcpConfigureClaudeCode() *serpent.Command {
 		appStatusSlug    string
 		testBinaryName   string
 		aiAgentAPIURL    url.URL
+		claudeUseBedrock string
 
 		deprecatedCoderMCPClaudeAPIKey string
 	)
@@ -154,14 +155,15 @@ func (r *RootCmd) mcpConfigureClaudeCode() *serpent.Command {
 				configureClaudeEnv[envAgentURL] = agentClient.SDK.URL.String()
 				configureClaudeEnv[envAgentToken] = agentClient.SDK.SessionToken()
 			}
-			if claudeAPIKey == "" {
-				if deprecatedCoderMCPClaudeAPIKey == "" {
-					cliui.Warnf(inv.Stderr, "CLAUDE_API_KEY is not set.")
-				} else {
-					cliui.Warnf(inv.Stderr, "CODER_MCP_CLAUDE_API_KEY is deprecated, use CLAUDE_API_KEY instead")
-					claudeAPIKey = deprecatedCoderMCPClaudeAPIKey
-				}
+
+			if deprecatedCoderMCPClaudeAPIKey != "" {
+				cliui.Warnf(inv.Stderr, "CODER_MCP_CLAUDE_API_KEY is deprecated, use CLAUDE_API_KEY instead")
+				claudeAPIKey = deprecatedCoderMCPClaudeAPIKey
 			}
+			if claudeAPIKey == "" && claudeUseBedrock != "1" {
+				cliui.Warnf(inv.Stderr, "CLAUDE_API_KEY is not set.")
+			}
+
 			if appStatusSlug != "" {
 				configureClaudeEnv[envAppStatusSlug] = appStatusSlug
 			}
@@ -280,6 +282,14 @@ func (r *RootCmd) mcpConfigureClaudeCode() *serpent.Command {
 				Value:       serpent.StringOf(&testBinaryName),
 				Hidden:      true,
 			},
+			{
+				Name:        "claude-code-use-bedrock",
+				Description: "Use Amazon Bedrock.",
+				Env:         "CLAUDE_CODE_USE_BEDROCK",
+				Flag:        "claude-code-use-bedrock",
+				Value:       serpent.StringOf(&claudeUseBedrock),
+				Hidden:      true,
+			},
 		},
 	}
 	return cmd
@@ -362,11 +372,19 @@ func (*RootCmd) mcpConfigureCursor() *serpent.Command {
 }
 
 type taskReport struct {
-	link         string
-	messageID    int64
+	// link is optional.
+	link string
+	// messageID must be set if this update is from a *user* message. A user
+	// message only happens when interacting via the AI AgentAPI (as opposed to
+	// interacting with the terminal directly).
+	messageID *int64
+	// selfReported must be set if the update is directly from the AI agent
+	// (as opposed to the screen watcher).
 	selfReported bool
-	state        codersdk.WorkspaceAppStatusState
-	summary      string
+	// state must always be set.
+	state codersdk.WorkspaceAppStatusState
+	// summary is optional.
+	summary string
 }
 
 type mcpServer struct {
@@ -388,31 +406,48 @@ func (r *RootCmd) mcpServer() *serpent.Command {
 	return &serpent.Command{
 		Use: "server",
 		Handler: func(inv *serpent.Invocation) error {
-			// lastUserMessageID is the ID of the last *user* message that we saw.  A
-			// user message only happens when interacting via the AI AgentAPI (as
-			// opposed to interacting with the terminal directly).
-			var lastUserMessageID int64
 			var lastReport taskReport
 			// Create a queue that skips duplicates and preserves summaries.
 			queue := cliutil.NewQueue[taskReport](512).WithPredicate(func(report taskReport) (taskReport, bool) {
-				// Use "working" status if this is a new user message.  If this is not a
-				// new user message, and the status is "working" and not self-reported
-				// (meaning it came from the screen watcher), then it means one of two
-				// things:
-				// 1. The AI agent is still working, so there is nothing to update.
-				// 2. The AI agent stopped working, then the user has interacted with
-				//    the terminal directly.  For now, we are ignoring these updates.
-				//    This risks missing cases where the user manually submits a new
-				//    prompt and the AI agent becomes active and does not update itself,
-				//    but it avoids spamming useless status updates as the user is
-				//    typing, so the tradeoff is worth it.  In the future, if we can
-				//    reliably distinguish between user and AI agent activity, we can
-				//    change this.
-				if report.messageID > lastUserMessageID {
-					report.state = codersdk.WorkspaceAppStatusStateWorking
-				} else if report.state == codersdk.WorkspaceAppStatusStateWorking && !report.selfReported {
+				// Avoid queuing empty statuses (this would probably indicate a
+				// developer error)
+				if report.state == "" {
 					return report, false
 				}
+				// If this is a user message, discard if it is not new.
+				if report.messageID != nil && lastReport.messageID != nil &&
+					*lastReport.messageID >= *report.messageID {
+					return report, false
+				}
+				// If this is not a user message, and the status is "working" and not
+				// self-reported (meaning it came from the screen watcher), then it
+				// means one of two things:
+				//
+				// 1. The AI agent is not working; the user is interacting with the
+				//    terminal directly.
+				// 2. The AI agent is working.
+				//
+				// At the moment, we have no way to tell the difference between these
+				// two states. In the future, if we can reliably distinguish between
+				// user and AI agent activity, we can change this.
+				//
+				// If this is our first update, we assume it is the AI agent working and
+				// accept the update.
+				//
+				// Otherwise we discard the update.  This risks missing cases where the
+				// user manually submits a new prompt and the AI agent becomes active
+				// (and does not update itself), but it avoids spamming useless status
+				// updates as the user is typing, so the tradeoff is worth it.
+				if report.messageID == nil &&
+					report.state == codersdk.WorkspaceAppStatusStateWorking &&
+					!report.selfReported && lastReport.state != "" {
+					return report, false
+				}
+				// Keep track of the last message ID so we can tell when a message is
+				// new or if it has been re-emitted.
+				if report.messageID == nil {
+					report.messageID = lastReport.messageID
+				}
 				// Preserve previous message and URI if there was no message.
 				if report.summary == "" {
 					report.summary = lastReport.summary
@@ -600,7 +635,8 @@ func (s *mcpServer) startWatcher(ctx context.Context, inv *serpent.Invocation) {
 				case agentapi.EventMessageUpdate:
 					if ev.Role == agentapi.RoleUser {
 						err := s.queue.Push(taskReport{
-							messageID: ev.Id,
+							messageID: &ev.Id,
+							state:     codersdk.WorkspaceAppStatusStateWorking,
 						})
 						if err != nil {
 							cliui.Warnf(inv.Stderr, "Failed to queue update: %s", err)
@@ -650,10 +686,18 @@ func (s *mcpServer) startServer(ctx context.Context, inv *serpent.Invocation, in
 	// Add tool dependencies.
 	toolOpts := []func(*toolsdk.Deps){
 		toolsdk.WithTaskReporter(func(args toolsdk.ReportTaskArgs) error {
+			// The agent does not reliably report its status correctly.  If AgentAPI
+			// is enabled, we will always set the status to "working" when we get an
+			// MCP message, and rely on the screen watcher to eventually catch the
+			// idle state.
+			state := codersdk.WorkspaceAppStatusStateWorking
+			if s.aiAgentAPIClient == nil {
+				state = codersdk.WorkspaceAppStatusState(args.State)
+			}
 			return s.queue.Push(taskReport{
 				link:         args.Link,
 				selfReported: true,
-				state:        codersdk.WorkspaceAppStatusState(args.State),
+				state:        state,
 				summary:      args.Summary,
 			})
 		}),

cli/exp_mcp_test.go

@@ -763,220 +763,351 @@ func TestExpMcpReporter(t *testing.T) {
 		<-cmdDone
 	})
 
-	t.Run("OK", func(t *testing.T) {
-		t.Parallel()
+	makeStatusEvent := func(status agentapi.AgentStatus) *codersdk.ServerSentEvent {
+		return &codersdk.ServerSentEvent{
+			Type: ServerSentEventTypeStatusChange,
+			Data: agentapi.EventStatusChange{
+				Status: status,
+			},
+		}
+	}
 
-		// Create a test deployment and workspace.
-		client, db := coderdtest.NewWithDatabase(t, nil)
-		user := coderdtest.CreateFirstUser(t, client)
-		client, user2 := coderdtest.CreateAnotherUser(t, client, user.OrganizationID)
+	makeMessageEvent := func(id int64, role agentapi.ConversationRole) *codersdk.ServerSentEvent {
+		return &codersdk.ServerSentEvent{
+			Type: ServerSentEventTypeMessageUpdate,
+			Data: agentapi.EventMessageUpdate{
+				Id:   id,
+				Role: role,
+			},
+		}
+	}
 
-		r := dbfake.WorkspaceBuild(t, db, database.WorkspaceTable{
-			OrganizationID: user.OrganizationID,
-			OwnerID:        user2.ID,
-		}).WithAgent(func(a []*proto.Agent) []*proto.Agent {
-			a[0].Apps = []*proto.App{
+	type test struct {
+		// event simulates an event from the screen watcher.
+		event *codersdk.ServerSentEvent
+		// state, summary, and uri simulate a tool call from the AI agent.
+		state    codersdk.WorkspaceAppStatusState
+		summary  string
+		uri      string
+		expected *codersdk.WorkspaceAppStatus
+	}
+
+	runs := []struct {
+		name            string
+		tests           []test
+		disableAgentAPI bool
+	}{
+		// In this run the AI agent starts with a state change but forgets to update
+		// that it finished.
+		{
+			name: "Active",
+			tests: []test{
+				// First the AI agent updates with a state change.
 				{
-					Slug: "vscode",
+					state:   codersdk.WorkspaceAppStatusStateWorking,
+					summary: "doing work",
+					uri:     "https://dev.coder.com",
+					expected: &codersdk.WorkspaceAppStatus{
+						State:   codersdk.WorkspaceAppStatusStateWorking,
+						Message: "doing work",
+						URI:     "https://dev.coder.com",
+					},
 				},
-			}
-			return a
-		}).Do()
-
-		makeStatusEvent := func(status agentapi.AgentStatus) *codersdk.ServerSentEvent {
-			return &codersdk.ServerSentEvent{
-				Type: ServerSentEventTypeStatusChange,
-				Data: agentapi.EventStatusChange{
-					Status: status,
+				// Terminal goes quiet but the AI agent forgot the update, and it is
+				// caught by the screen watcher.  Message and URI are preserved.
+				{
+					event: makeStatusEvent(agentapi.StatusStable),
+					expected: &codersdk.WorkspaceAppStatus{
+						State:   codersdk.WorkspaceAppStatusStateIdle,
+						Message: "doing work",
+						URI:     "https://dev.coder.com",
+					},
 				},
-			}
-		}
-
-		makeMessageEvent := func(id int64, role agentapi.ConversationRole) *codersdk.ServerSentEvent {
-			return &codersdk.ServerSentEvent{
-				Type: ServerSentEventTypeMessageUpdate,
-				Data: agentapi.EventMessageUpdate{
-					Id:   id,
-					Role: role,
+				// A stable update now from the watcher should be discarded, as it is a
+				// duplicate.
+				{
+					event: makeStatusEvent(agentapi.StatusStable),
 				},
-			}
-		}
+				// Terminal becomes active again according to the screen watcher, but no
+				// new user message.  This could be the AI agent being active again, but
+				// it could also be the user messing around.  We will prefer not updating
+				// the status so the "working" update here should be skipped.
+				//
+				// TODO: How do we test the no-op updates?  This update is skipped
+				// because of the logic mentioned above, but how do we prove this update
+				// was skipped because of that and not that the next update was skipped
+				// because it is a duplicate state?  We could mock the queue?
+				{
+					event: makeStatusEvent(agentapi.StatusRunning),
+				},
+				// Agent messages are ignored.
+				{
+					event: makeMessageEvent(0, agentapi.RoleAgent),
+				},
+				// The watcher reports the screen is active again...
+				{
+					event: makeStatusEvent(agentapi.StatusRunning),
+				},
+				// ... but this time we have a new user message so we know there is AI
+				// agent activity.  This time the "working" update will not be skipped.
+				{
+					event: makeMessageEvent(1, agentapi.RoleUser),
+					expected: &codersdk.WorkspaceAppStatus{
+						State:   codersdk.WorkspaceAppStatusStateWorking,
+						Message: "doing work",
+						URI:     "https://dev.coder.com",
+					},
+				},
+				// Watcher reports stable again.
+				{
+					event: makeStatusEvent(agentapi.StatusStable),
+					expected: &codersdk.WorkspaceAppStatus{
+						State:   codersdk.WorkspaceAppStatusStateIdle,
+						Message: "doing work",
+						URI:     "https://dev.coder.com",
+					},
+				},
+			},
+		},
+		// In this run the AI agent never sends any state changes.
+		{
+			name: "Inactive",
+			tests: []test{
+				// The "working" status from the watcher should be accepted, even though
+				// there is no new user message, because it is the first update.
+				{
+					event: makeStatusEvent(agentapi.StatusRunning),
+					expected: &codersdk.WorkspaceAppStatus{
+						State:   codersdk.WorkspaceAppStatusStateWorking,
+						Message: "",
+						URI:     "",
+					},
+				},
+				// Stable update should be accepted.
+				{
+					event: makeStatusEvent(agentapi.StatusStable),
+					expected: &codersdk.WorkspaceAppStatus{
+						State:   codersdk.WorkspaceAppStatusStateIdle,
+						Message: "",
+						URI:     "",
+					},
+				},
+				// Zero ID should be accepted.
+				{
+					event: makeMessageEvent(0, agentapi.RoleUser),
+					expected: &codersdk.WorkspaceAppStatus{
+						State:   codersdk.WorkspaceAppStatusStateWorking,
+						Message: "",
+						URI:     "",
+					},
+				},
+				// Stable again.
+				{
+					event: makeStatusEvent(agentapi.StatusStable),
+					expected: &codersdk.WorkspaceAppStatus{
+						State:   codersdk.WorkspaceAppStatusStateIdle,
+						Message: "",
+						URI:     "",
+					},
+				},
+				// Next ID.
+				{
+					event: makeMessageEvent(1, agentapi.RoleUser),
+					expected: &codersdk.WorkspaceAppStatus{
+						State:   codersdk.WorkspaceAppStatusStateWorking,
+						Message: "",
+						URI:     "",
+					},
+				},
+			},
+		},
+		// We ignore the state from the agent and assume "working".
+		{
+			name: "IgnoreAgentState",
+			// AI agent reports that it is finished but the summary says it is doing
+			// work.
+			tests: []test{
+				{
+					state:   codersdk.WorkspaceAppStatusStateIdle,
+					summary: "doing work",
+					expected: &codersdk.WorkspaceAppStatus{
+						State:   codersdk.WorkspaceAppStatusStateWorking,
+						Message: "doing work",
+					},
+				},
+				// AI agent reports finished again, with a matching summary.  We still
+				// assume it is working.
+				{
+					state:   codersdk.WorkspaceAppStatusStateIdle,
+					summary: "finished",
+					expected: &codersdk.WorkspaceAppStatus{
+						State:   codersdk.WorkspaceAppStatusStateWorking,
+						Message: "finished",
+					},
+				},
+				// Once the watcher reports stable, then we record idle.
+				{
+					event: makeStatusEvent(agentapi.StatusStable),
+					expected: &codersdk.WorkspaceAppStatus{
+						State:   codersdk.WorkspaceAppStatusStateIdle,
+						Message: "finished",
+					},
+				},
+			},
+		},
+		// When AgentAPI is not being used, we accept agent state updates as-is.
+		{
+			name: "KeepAgentState",
+			tests: []test{
+				{
+					state:   codersdk.WorkspaceAppStatusStateWorking,
+					summary: "doing work",
+					expected: &codersdk.WorkspaceAppStatus{
+						State:   codersdk.WorkspaceAppStatusStateWorking,
+						Message: "doing work",
+					},
+				},
+				{
+					state:   codersdk.WorkspaceAppStatusStateIdle,
+					summary: "finished",
+					expected: &codersdk.WorkspaceAppStatus{
+						State:   codersdk.WorkspaceAppStatusStateIdle,
+						Message: "finished",
+					},
+				},
+			},
+			disableAgentAPI: true,
+		},
+	}
 
-		ctx, cancel := context.WithCancel(testutil.Context(t, testutil.WaitShort))
+	for _, run := range runs {
+		run := run
+		t.Run(run.name, func(t *testing.T) {
+			t.Parallel()
 
-		// Mock the AI AgentAPI server.
-		listening := make(chan func(sse codersdk.ServerSentEvent) error)
-		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-			send, closed, err := httpapi.ServerSentEventSender(w, r)
-			if err != nil {
-				httpapi.Write(ctx, w, http.StatusInternalServerError, codersdk.Response{
-					Message: "Internal error setting up server-sent events.",
-					Detail:  err.Error(),
-				})
-				return
-			}
-			// Send initial message.
-			send(*makeMessageEvent(0, agentapi.RoleAgent))
-			listening <- send
-			<-closed
-		}))
-		t.Cleanup(srv.Close)
-		aiAgentAPIURL := srv.URL
+			ctx, cancel := context.WithCancel(testutil.Context(t, testutil.WaitShort))
 
-		// Watch the workspace for changes.
-		watcher, err := client.WatchWorkspace(ctx, r.Workspace.ID)
-		require.NoError(t, err)
-		var lastAppStatus codersdk.WorkspaceAppStatus
-		nextUpdate := func() codersdk.WorkspaceAppStatus {
-			for {
-				select {
-				case <-ctx.Done():
-					require.FailNow(t, "timed out waiting for status update")
-				case w, ok := <-watcher:
-					require.True(t, ok, "watch channel closed")
-					if w.LatestAppStatus != nil && w.LatestAppStatus.ID != lastAppStatus.ID {
-						lastAppStatus = *w.LatestAppStatus
-						return lastAppStatus
+			// Create a test deployment and workspace.
+			client, db := coderdtest.NewWithDatabase(t, nil)
+			user := coderdtest.CreateFirstUser(t, client)
+			client, user2 := coderdtest.CreateAnotherUser(t, client, user.OrganizationID)
+
+			r := dbfake.WorkspaceBuild(t, db, database.WorkspaceTable{
+				OrganizationID: user.OrganizationID,
+				OwnerID:        user2.ID,
+			}).WithAgent(func(a []*proto.Agent) []*proto.Agent {
+				a[0].Apps = []*proto.App{
+					{
+						Slug: "vscode",
+					},
+				}
+				return a
+			}).Do()
+
+			// Watch the workspace for changes.
+			watcher, err := client.WatchWorkspace(ctx, r.Workspace.ID)
+			require.NoError(t, err)
+			var lastAppStatus codersdk.WorkspaceAppStatus
+			nextUpdate := func() codersdk.WorkspaceAppStatus {
+				for {
+					select {
+					case <-ctx.Done():
+						require.FailNow(t, "timed out waiting for status update")
+					case w, ok := <-watcher:
+						require.True(t, ok, "watch channel closed")
+						if w.LatestAppStatus != nil && w.LatestAppStatus.ID != lastAppStatus.ID {
+							t.Logf("Got status update: %s > %s", lastAppStatus.State, w.LatestAppStatus.State)
+							lastAppStatus = *w.LatestAppStatus
+							return lastAppStatus
+						}
 					}
 				}
 			}
-		}
 
-		inv, _ := clitest.New(t,
-			"exp", "mcp", "server",
-			// We need the agent credentials, AI AgentAPI url, and a slug for reporting.
-			"--agent-url", client.URL.String(),
-			"--agent-token", r.AgentToken,
-			"--app-status-slug", "vscode",
-			"--ai-agentapi-url", aiAgentAPIURL,
-			"--allowed-tools=coder_report_task",
-		)
-		inv = inv.WithContext(ctx)
-
-		pty := ptytest.New(t)
-		inv.Stdin = pty.Input()
-		inv.Stdout = pty.Output()
-		stderr := ptytest.New(t)
-		inv.Stderr = stderr.Output()
-
-		// Run the MCP server.
-		cmdDone := make(chan struct{})
-		go func() {
-			defer close(cmdDone)
-			err := inv.Run()
-			assert.NoError(t, err)
-		}()
-
-		// Initialize.
-		payload := `{"jsonrpc":"2.0","id":1,"method":"initialize"}`
-		pty.WriteLine(payload)
-		_ = pty.ReadLine(ctx) // ignore echo
-		_ = pty.ReadLine(ctx) // ignore init response
-
-		sender := <-listening
-
-		tests := []struct {
-			// event simulates an event from the screen watcher.
-			event *codersdk.ServerSentEvent
-			// state, summary, and uri simulate a tool call from the AI agent.
-			state    codersdk.WorkspaceAppStatusState
-			summary  string
-			uri      string
-			expected *codersdk.WorkspaceAppStatus
-		}{
-			// First the AI agent updates with a state change.
-			{
-				state:   codersdk.WorkspaceAppStatusStateWorking,
-				summary: "doing work",
-				uri:     "https://dev.coder.com",
-				expected: &codersdk.WorkspaceAppStatus{
-					State:   codersdk.WorkspaceAppStatusStateWorking,
-					Message: "doing work",
-					URI:     "https://dev.coder.com",
-				},
-			},
-			// Terminal goes quiet but the AI agent forgot the update, and it is
-			// caught by the screen watcher.  Message and URI are preserved.
-			{
-				event: makeStatusEvent(agentapi.StatusStable),
-				expected: &codersdk.WorkspaceAppStatus{
-					State:   codersdk.WorkspaceAppStatusStateIdle,
-					Message: "doing work",
-					URI:     "https://dev.coder.com",
-				},
-			},
-			// A completed update at this point from the watcher should be discarded.
-			{
-				event: makeStatusEvent(agentapi.StatusStable),
-			},
-			// Terminal becomes active again according to the screen watcher, but no
-			// new user message.  This could be the AI agent being active again, but
-			// it could also be the user messing around.  We will prefer not updating
-			// the status so the "working" update here should be skipped.
-			{
-				event: makeStatusEvent(agentapi.StatusRunning),
-			},
-			// Agent messages are ignored.
-			{
-				event: makeMessageEvent(1, agentapi.RoleAgent),
-			},
-			// AI agent reports that it failed and URI is blank.
-			{
-				state:   codersdk.WorkspaceAppStatusStateFailure,
-				summary: "oops",
-				expected: &codersdk.WorkspaceAppStatus{
-					State:   codersdk.WorkspaceAppStatusStateFailure,
-					Message: "oops",
-					URI:     "",
-				},
-			},
-			// The watcher reports the screen is active again...
-			{
-				event: makeStatusEvent(agentapi.StatusRunning),
-			},
-			// ... but this time we have a new user message so we know there is AI
-			// agent activity.  This time the "working" update will not be skipped.
-			{
-				event: makeMessageEvent(2, agentapi.RoleUser),
-				expected: &codersdk.WorkspaceAppStatus{
-					State:   codersdk.WorkspaceAppStatusStateWorking,
-					Message: "oops",
-					URI:     "",
-				},
-			},
-			// Watcher reports stable again.
-			{
-				event: makeStatusEvent(agentapi.StatusStable),
-				expected: &codersdk.WorkspaceAppStatus{
-					State:   codersdk.WorkspaceAppStatusStateIdle,
-					Message: "oops",
-					URI:     "",
-				},
-			},
-		}
-		for _, test := range tests {
-			if test.event != nil {
-				err := sender(*test.event)
-				require.NoError(t, err)
-			} else {
-				// Call the tool and ensure it works.
-				payload := fmt.Sprintf(`{"jsonrpc":"2.0","id":3,"method":"tools/call", "params": {"name": "coder_report_task", "arguments": {"state": %q, "summary": %q, "link": %q}}}`, test.state, test.summary, test.uri)
-				pty.WriteLine(payload)
-				_ = pty.ReadLine(ctx) // ignore echo
-				output := pty.ReadLine(ctx)
-				require.NotEmpty(t, output, "did not receive a response from coder_report_task")
-				// Ensure it is valid JSON.
-				_, err = json.Marshal(output)
-				require.NoError(t, err, "did not receive valid JSON from coder_report_task")
+			args := []string{
+				"exp", "mcp", "server",
+				// We need the agent credentials, AI AgentAPI url (if not
+				// disabled), and a slug for reporting.
+				"--agent-url", client.URL.String(),
+				"--agent-token", r.AgentToken,
+				"--app-status-slug", "vscode",
+				"--allowed-tools=coder_report_task",
 			}
-			if test.expected != nil {
-				got := nextUpdate()
-				require.Equal(t, got.State, test.expected.State)
-				require.Equal(t, got.Message, test.expected.Message)
-				require.Equal(t, got.URI, test.expected.URI)
+
+			// Mock the AI AgentAPI server.
+			listening := make(chan func(sse codersdk.ServerSentEvent) error)
+			if !run.disableAgentAPI {
+				srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+					send, closed, err := httpapi.ServerSentEventSender(w, r)
+					if err != nil {
+						httpapi.Write(ctx, w, http.StatusInternalServerError, codersdk.Response{
+							Message: "Internal error setting up server-sent events.",
+							Detail:  err.Error(),
+						})
+						return
+					}
+					// Send initial message.
+					send(*makeMessageEvent(0, agentapi.RoleAgent))
+					listening <- send
+					<-closed
+				}))
+				t.Cleanup(srv.Close)
+				aiAgentAPIURL := srv.URL
+				args = append(args, "--ai-agentapi-url", aiAgentAPIURL)
 			}
-		}
-		cancel()
-		<-cmdDone
-	})
+
+			inv, _ := clitest.New(t, args...)
+			inv = inv.WithContext(ctx)
+
+			pty := ptytest.New(t)
+			inv.Stdin = pty.Input()
+			inv.Stdout = pty.Output()
+			stderr := ptytest.New(t)
+			inv.Stderr = stderr.Output()
+
+			// Run the MCP server.
+			cmdDone := make(chan struct{})
+			go func() {
+				defer close(cmdDone)
+				err := inv.Run()
+				assert.NoError(t, err)
+			}()
+
+			// Initialize.
+			payload := `{"jsonrpc":"2.0","id":1,"method":"initialize"}`
+			pty.WriteLine(payload)
+			_ = pty.ReadLine(ctx) // ignore echo
+			_ = pty.ReadLine(ctx) // ignore init response
+
+			var sender func(sse codersdk.ServerSentEvent) error
+			if !run.disableAgentAPI {
+				sender = <-listening
+			}
+
+			for _, test := range run.tests {
+				if test.event != nil {
+					err := sender(*test.event)
+					require.NoError(t, err)
+				} else {
+					// Call the tool and ensure it works.
+					payload := fmt.Sprintf(`{"jsonrpc":"2.0","id":3,"method":"tools/call", "params": {"name": "coder_report_task", "arguments": {"state": %q, "summary": %q, "link": %q}}}`, test.state, test.summary, test.uri)
+					pty.WriteLine(payload)
+					_ = pty.ReadLine(ctx) // ignore echo
+					output := pty.ReadLine(ctx)
+					require.NotEmpty(t, output, "did not receive a response from coder_report_task")
+					// Ensure it is valid JSON.
+					_, err = json.Marshal(output)
+					require.NoError(t, err, "did not receive valid JSON from coder_report_task")
+				}
+				if test.expected != nil {
+					got := nextUpdate()
+					require.Equal(t, got.State, test.expected.State)
+					require.Equal(t, got.Message, test.expected.Message)
+					require.Equal(t, got.URI, test.expected.URI)
+				}
+			}
+			cancel()
+			<-cmdDone
+		})
+	}
 }

cli/exp_prompts.go

@@ -174,6 +174,20 @@ func (RootCmd) promptExample() *serpent.Command {
 				_, _ = fmt.Fprintf(inv.Stdout, "%q are nice choices.\n", strings.Join(multiSelectValues, ", "))
 				return multiSelectError
 			}, useThingsOption, enableCustomInputOption),
+			promptCmd("rich-multi-select", func(inv *serpent.Invocation) error {
+				if len(multiSelectValues) == 0 {
+					multiSelectValues, multiSelectError = cliui.MultiSelect(inv, cliui.MultiSelectOptions{
+						Message: "Select some things:",
+						Options: []string{
+							"Apples", "Plums", "Grapes", "Oranges", "Bananas",
+						},
+						Defaults:          []string{"Grapes", "Plums"},
+						EnableCustomInput: enableCustomInput,
+					})
+				}
+				_, _ = fmt.Fprintf(inv.Stdout, "%q are nice choices.\n", strings.Join(multiSelectValues, ", "))
+				return multiSelectError
+			}, useThingsOption, enableCustomInputOption),
 			promptCmd("rich-parameter", func(inv *serpent.Invocation) error {
 				value, err := cliui.RichSelect(inv, cliui.RichSelectOptions{
 					Options: []codersdk.TemplateVersionParameterOption{

cli/exp_rpty.go

@@ -97,7 +97,7 @@ func handleRPTY(inv *serpent.Invocation, client *codersdk.Client, args handleRPT
 		reconnectID = uuid.New()
 	}
 
-	ws, agt, err := getWorkspaceAndAgent(ctx, inv, client, true, args.NamedWorkspace)
+	ws, agt, _, err := GetWorkspaceAndAgent(ctx, inv, client, true, args.NamedWorkspace)
 	if err != nil {
 		return err
 	}

cli/exp_rpty_test.go

@@ -118,6 +118,7 @@ func TestExpRpty(t *testing.T) {
 		_ = agenttest.New(t, client.URL, agentToken, func(o *agent.Options) {
 			o.Devcontainers = true
 			o.DevcontainerAPIOptions = append(o.DevcontainerAPIOptions,
+				agentcontainers.WithProjectDiscovery(false),
 				agentcontainers.WithContainerLabelIncludeFilter(wantLabel, "true"),
 			)
 		})

cli/exp_task.go

@@ -0,0 +1,22 @@
+package cli
+
+import (
+	"github.com/coder/serpent"
+)
+
+func (r *RootCmd) tasksCommand() *serpent.Command {
+	cmd := &serpent.Command{
+		Use:     "task",
+		Aliases: []string{"tasks"},
+		Short:   "Experimental task commands.",
+		Handler: func(i *serpent.Invocation) error {
+			return i.Command.HelpHandler(i)
+		},
+		Children: []*serpent.Command{
+			r.taskList(),
+			r.taskCreate(),
+			r.taskStatus(),
+		},
+	}
+	return cmd
+}

cli/exp_task_status.go

@@ -0,0 +1,171 @@
+package cli
+
+import (
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/google/uuid"
+	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/v2/cli/cliui"
+	"github.com/coder/coder/v2/codersdk"
+	"github.com/coder/serpent"
+)
+
+func (r *RootCmd) taskStatus() *serpent.Command {
+	var (
+		client    = new(codersdk.Client)
+		formatter = cliui.NewOutputFormatter(
+			cliui.TableFormat(
+				[]taskStatusRow{},
+				[]string{
+					"state changed",
+					"status",
+					"state",
+					"message",
+				},
+			),
+			cliui.ChangeFormatterData(
+				cliui.JSONFormat(),
+				func(data any) (any, error) {
+					rows, ok := data.([]taskStatusRow)
+					if !ok {
+						return nil, xerrors.Errorf("expected []taskStatusRow, got %T", data)
+					}
+					if len(rows) != 1 {
+						return nil, xerrors.Errorf("expected exactly 1 row, got %d", len(rows))
+					}
+					return rows[0], nil
+				},
+			),
+		)
+		watchArg         bool
+		watchIntervalArg time.Duration
+	)
+	cmd := &serpent.Command{
+		Short:   "Show the status of a task.",
+		Use:     "status",
+		Aliases: []string{"stat"},
+		Options: serpent.OptionSet{
+			{
+				Default:     "false",
+				Description: "Watch the task status output. This will stream updates to the terminal until the underlying workspace is stopped.",
+				Flag:        "watch",
+				Name:        "watch",
+				Value:       serpent.BoolOf(&watchArg),
+			},
+			{
+				Default:     "1s",
+				Description: "Interval to poll the task for updates. Only used in tests.",
+				Hidden:      true,
+				Flag:        "watch-interval",
+				Name:        "watch-interval",
+				Value:       serpent.DurationOf(&watchIntervalArg),
+			},
+		},
+		Middleware: serpent.Chain(
+			serpent.RequireNArgs(1),
+			r.InitClient(client),
+		),
+		Handler: func(i *serpent.Invocation) error {
+			ctx := i.Context()
+			ec := codersdk.NewExperimentalClient(client)
+			identifier := i.Args[0]
+
+			taskID, err := uuid.Parse(identifier)
+			if err != nil {
+				// Try to resolve the task as a named workspace
+				// TODO: right now tasks are still "workspaces" under the hood.
+				// We should update this once we have a proper task model.
+				ws, err := namedWorkspace(ctx, client, identifier)
+				if err != nil {
+					return err
+				}
+				taskID = ws.ID
+			}
+			task, err := ec.TaskByID(ctx, taskID)
+			if err != nil {
+				return err
+			}
+
+			out, err := formatter.Format(ctx, toStatusRow(task))
+			if err != nil {
+				return xerrors.Errorf("format task status: %w", err)
+			}
+			_, _ = fmt.Fprintln(i.Stdout, out)
+
+			if !watchArg {
+				return nil
+			}
+
+			lastStatus := task.Status
+			lastState := task.CurrentState
+			t := time.NewTicker(watchIntervalArg)
+			defer t.Stop()
+			// TODO: implement streaming updates instead of polling
+			for range t.C {
+				task, err := ec.TaskByID(ctx, taskID)
+				if err != nil {
+					return err
+				}
+				if lastStatus == task.Status && taskStatusEqual(lastState, task.CurrentState) {
+					continue
+				}
+				out, err := formatter.Format(ctx, toStatusRow(task))
+				if err != nil {
+					return xerrors.Errorf("format task status: %w", err)
+				}
+				// hack: skip the extra column header from formatter
+				if formatter.FormatID() != cliui.JSONFormat().ID() {
+					out = strings.SplitN(out, "\n", 2)[1]
+				}
+				_, _ = fmt.Fprintln(i.Stdout, out)
+
+				if task.Status == codersdk.WorkspaceStatusStopped {
+					return nil
+				}
+				lastStatus = task.Status
+				lastState = task.CurrentState
+			}
+			return nil
+		},
+	}
+	formatter.AttachOptions(&cmd.Options)
+	return cmd
+}
+
+func taskStatusEqual(s1, s2 *codersdk.TaskStateEntry) bool {
+	if s1 == nil && s2 == nil {
+		return true
+	}
+	if s1 == nil || s2 == nil {
+		return false
+	}
+	return s1.State == s2.State
+}
+
+type taskStatusRow struct {
+	codersdk.Task `table:"-"`
+	ChangedAgo    string    `json:"-" table:"state changed,default_sort"`
+	Timestamp     time.Time `json:"-" table:"-"`
+	TaskStatus    string    `json:"-" table:"status"`
+	TaskState     string    `json:"-" table:"state"`
+	Message       string    `json:"-" table:"message"`
+}
+
+func toStatusRow(task codersdk.Task) []taskStatusRow {
+	tsr := taskStatusRow{
+		Task:       task,
+		ChangedAgo: time.Since(task.UpdatedAt).Truncate(time.Second).String() + " ago",
+		Timestamp:  task.UpdatedAt,
+		TaskStatus: string(task.Status),
+	}
+	if task.CurrentState != nil {
+		tsr.ChangedAgo = time.Since(task.CurrentState.Timestamp).Truncate(time.Second).String() + " ago"
+		tsr.Timestamp = task.CurrentState.Timestamp
+		tsr.TaskState = string(task.CurrentState.State)
+		tsr.Message = task.CurrentState.Message
+	}
+	return []taskStatusRow{tsr}
+}

cli/exp_task_status_test.go

@@ -0,0 +1,270 @@
+package cli_test
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/google/go-cmp/cmp"
+	"github.com/google/uuid"
+	"github.com/stretchr/testify/assert"
+	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/v2/cli/clitest"
+	"github.com/coder/coder/v2/coderd/httpapi"
+	"github.com/coder/coder/v2/codersdk"
+	"github.com/coder/coder/v2/testutil"
+)
+
+func Test_TaskStatus(t *testing.T) {
+	t.Parallel()
+
+	for _, tc := range []struct {
+		args         []string
+		expectOutput string
+		expectError  string
+		hf           func(context.Context, time.Time) func(http.ResponseWriter, *http.Request)
+	}{
+		{
+			args:        []string{"doesnotexist"},
+			expectError: httpapi.ResourceNotFoundResponse.Message,
+			hf: func(ctx context.Context, _ time.Time) func(w http.ResponseWriter, r *http.Request) {
+				return func(w http.ResponseWriter, r *http.Request) {
+					switch r.URL.Path {
+					case "/api/v2/users/me/workspace/doesnotexist":
+						httpapi.ResourceNotFound(w)
+					default:
+						t.Errorf("unexpected path: %s", r.URL.Path)
+					}
+				}
+			},
+		},
+		{
+			args:        []string{"err-fetching-workspace"},
+			expectError: assert.AnError.Error(),
+			hf: func(ctx context.Context, _ time.Time) func(w http.ResponseWriter, r *http.Request) {
+				return func(w http.ResponseWriter, r *http.Request) {
+					switch r.URL.Path {
+					case "/api/v2/users/me/workspace/err-fetching-workspace":
+						httpapi.Write(ctx, w, http.StatusOK, codersdk.Workspace{
+							ID: uuid.MustParse("11111111-1111-1111-1111-111111111111"),
+						})
+					case "/api/experimental/tasks/me/11111111-1111-1111-1111-111111111111":
+						httpapi.InternalServerError(w, assert.AnError)
+					default:
+						t.Errorf("unexpected path: %s", r.URL.Path)
+					}
+				}
+			},
+		},
+		{
+			args: []string{"exists"},
+			expectOutput: `STATE CHANGED  STATUS   STATE    MESSAGE
+0s ago         running  working  Thinking furiously...`,
+			hf: func(ctx context.Context, now time.Time) func(w http.ResponseWriter, r *http.Request) {
+				return func(w http.ResponseWriter, r *http.Request) {
+					switch r.URL.Path {
+					case "/api/v2/users/me/workspace/exists":
+						httpapi.Write(ctx, w, http.StatusOK, codersdk.Workspace{
+							ID: uuid.MustParse("11111111-1111-1111-1111-111111111111"),
+						})
+					case "/api/experimental/tasks/me/11111111-1111-1111-1111-111111111111":
+						httpapi.Write(ctx, w, http.StatusOK, codersdk.Task{
+							ID:        uuid.MustParse("11111111-1111-1111-1111-111111111111"),
+							Status:    codersdk.WorkspaceStatusRunning,
+							CreatedAt: now,
+							UpdatedAt: now,
+							CurrentState: &codersdk.TaskStateEntry{
+								State:     codersdk.TaskStateWorking,
+								Timestamp: now,
+								Message:   "Thinking furiously...",
+							},
+						})
+					default:
+						t.Errorf("unexpected path: %s", r.URL.Path)
+					}
+				}
+			},
+		},
+		{
+			args: []string{"exists", "--watch"},
+			expectOutput: `
+STATE CHANGED  STATUS   STATE  MESSAGE
+4s ago         running
+3s ago         running  working  Reticulating splines...
+2s ago         running  completed  Splines reticulated successfully!
+2s ago         stopping  completed  Splines reticulated successfully!
+2s ago         stopped  completed  Splines reticulated successfully!`,
+			hf: func(ctx context.Context, now time.Time) func(http.ResponseWriter, *http.Request) {
+				var calls atomic.Int64
+				return func(w http.ResponseWriter, r *http.Request) {
+					defer calls.Add(1)
+					switch r.URL.Path {
+					case "/api/v2/users/me/workspace/exists":
+						httpapi.Write(ctx, w, http.StatusOK, codersdk.Workspace{
+							ID: uuid.MustParse("11111111-1111-1111-1111-111111111111"),
+						})
+					case "/api/experimental/tasks/me/11111111-1111-1111-1111-111111111111":
+						switch calls.Load() {
+						case 0:
+							httpapi.Write(ctx, w, http.StatusOK, codersdk.Task{
+								ID:        uuid.MustParse("11111111-1111-1111-1111-111111111111"),
+								Status:    codersdk.WorkspaceStatusPending,
+								CreatedAt: now.Add(-5 * time.Second),
+								UpdatedAt: now.Add(-5 * time.Second),
+							})
+						case 1:
+							httpapi.Write(ctx, w, http.StatusOK, codersdk.Task{
+								ID:        uuid.MustParse("11111111-1111-1111-1111-111111111111"),
+								Status:    codersdk.WorkspaceStatusRunning,
+								CreatedAt: now.Add(-5 * time.Second),
+								UpdatedAt: now.Add(-4 * time.Second),
+							})
+						case 2:
+							httpapi.Write(ctx, w, http.StatusOK, codersdk.Task{
+								ID:        uuid.MustParse("11111111-1111-1111-1111-111111111111"),
+								Status:    codersdk.WorkspaceStatusRunning,
+								CreatedAt: now.Add(-5 * time.Second),
+								UpdatedAt: now.Add(-4 * time.Second),
+								CurrentState: &codersdk.TaskStateEntry{
+									State:     codersdk.TaskStateWorking,
+									Timestamp: now.Add(-3 * time.Second),
+									Message:   "Reticulating splines...",
+								},
+							})
+						case 3:
+							httpapi.Write(ctx, w, http.StatusOK, codersdk.Task{
+								ID:        uuid.MustParse("11111111-1111-1111-1111-111111111111"),
+								Status:    codersdk.WorkspaceStatusRunning,
+								CreatedAt: now.Add(-5 * time.Second),
+								UpdatedAt: now.Add(-4 * time.Second),
+								CurrentState: &codersdk.TaskStateEntry{
+									State:     codersdk.TaskStateCompleted,
+									Timestamp: now.Add(-2 * time.Second),
+									Message:   "Splines reticulated successfully!",
+								},
+							})
+						case 4:
+							httpapi.Write(ctx, w, http.StatusOK, codersdk.Task{
+								ID:        uuid.MustParse("11111111-1111-1111-1111-111111111111"),
+								Status:    codersdk.WorkspaceStatusStopping,
+								CreatedAt: now.Add(-5 * time.Second),
+								UpdatedAt: now.Add(-1 * time.Second),
+								CurrentState: &codersdk.TaskStateEntry{
+									State:     codersdk.TaskStateCompleted,
+									Timestamp: now.Add(-2 * time.Second),
+									Message:   "Splines reticulated successfully!",
+								},
+							})
+						case 5:
+							httpapi.Write(ctx, w, http.StatusOK, codersdk.Task{
+								ID:        uuid.MustParse("11111111-1111-1111-1111-111111111111"),
+								Status:    codersdk.WorkspaceStatusStopped,
+								CreatedAt: now.Add(-5 * time.Second),
+								UpdatedAt: now,
+								CurrentState: &codersdk.TaskStateEntry{
+									State:     codersdk.TaskStateCompleted,
+									Timestamp: now.Add(-2 * time.Second),
+									Message:   "Splines reticulated successfully!",
+								},
+							})
+						default:
+							httpapi.InternalServerError(w, xerrors.New("too many calls!"))
+							return
+						}
+					default:
+						httpapi.InternalServerError(w, xerrors.Errorf("unexpected path: %q", r.URL.Path))
+					}
+				}
+			},
+		},
+		{
+			args: []string{"exists", "--output", "json"},
+			expectOutput: `{
+  "id": "11111111-1111-1111-1111-111111111111",
+  "organization_id": "00000000-0000-0000-0000-000000000000",
+  "owner_id": "00000000-0000-0000-0000-000000000000",
+  "name": "",
+  "template_id": "00000000-0000-0000-0000-000000000000",
+  "workspace_id": null,
+  "initial_prompt": "",
+  "status": "running",
+  "current_state": {
+    "timestamp": "2025-08-26T12:34:57Z",
+    "state": "working",
+    "message": "Thinking furiously...",
+    "uri": ""
+  },
+  "created_at": "2025-08-26T12:34:56Z",
+  "updated_at": "2025-08-26T12:34:56Z"
+}`,
+			hf: func(ctx context.Context, _ time.Time) func(w http.ResponseWriter, r *http.Request) {
+				ts := time.Date(2025, 8, 26, 12, 34, 56, 0, time.UTC)
+				return func(w http.ResponseWriter, r *http.Request) {
+					switch r.URL.Path {
+					case "/api/v2/users/me/workspace/exists":
+						httpapi.Write(ctx, w, http.StatusOK, codersdk.Workspace{
+							ID: uuid.MustParse("11111111-1111-1111-1111-111111111111"),
+						})
+					case "/api/experimental/tasks/me/11111111-1111-1111-1111-111111111111":
+						httpapi.Write(ctx, w, http.StatusOK, codersdk.Task{
+							ID:        uuid.MustParse("11111111-1111-1111-1111-111111111111"),
+							Status:    codersdk.WorkspaceStatusRunning,
+							CreatedAt: ts,
+							UpdatedAt: ts,
+							CurrentState: &codersdk.TaskStateEntry{
+								State:     codersdk.TaskStateWorking,
+								Timestamp: ts.Add(time.Second),
+								Message:   "Thinking furiously...",
+							},
+						})
+					default:
+						t.Errorf("unexpected path: %s", r.URL.Path)
+					}
+				}
+			},
+		},
+	} {
+		t.Run(strings.Join(tc.args, ","), func(t *testing.T) {
+			t.Parallel()
+
+			var (
+				ctx    = testutil.Context(t, testutil.WaitShort)
+				now    = time.Now().UTC() // TODO: replace with quartz
+				srv    = httptest.NewServer(http.HandlerFunc(tc.hf(ctx, now)))
+				client = new(codersdk.Client)
+				sb     = strings.Builder{}
+				args   = []string{"exp", "task", "status", "--watch-interval", testutil.IntervalFast.String()}
+			)
+
+			t.Cleanup(srv.Close)
+			client.URL = testutil.MustURL(t, srv.URL)
+			args = append(args, tc.args...)
+			inv, root := clitest.New(t, args...)
+			inv.Stdout = &sb
+			inv.Stderr = &sb
+			clitest.SetupConfig(t, client, root)
+			err := inv.WithContext(ctx).Run()
+			if tc.expectError == "" {
+				assert.NoError(t, err)
+			} else {
+				assert.ErrorContains(t, err, tc.expectError)
+			}
+			if diff := tableDiff(tc.expectOutput, sb.String()); diff != "" {
+				t.Errorf("unexpected output diff (-want +got):\n%s", diff)
+			}
+		})
+	}
+}
+
+func tableDiff(want, got string) string {
+	var gotTrimmed strings.Builder
+	for _, line := range strings.Split(got, "\n") {
+		_, _ = gotTrimmed.WriteString(strings.TrimRight(line, " ") + "\n")
+	}
+	return cmp.Diff(strings.TrimSpace(want), strings.TrimSpace(gotTrimmed.String()))
+}

cli/exp_taskcreate.go

@@ -0,0 +1,128 @@
+package cli
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/google/uuid"
+	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/v2/cli/cliui"
+	"github.com/coder/coder/v2/codersdk"
+	"github.com/coder/serpent"
+)
+
+func (r *RootCmd) taskCreate() *serpent.Command {
+	var (
+		orgContext = NewOrganizationContext()
+		client     = new(codersdk.Client)
+
+		templateName        string
+		templateVersionName string
+		presetName          string
+		taskInput           string
+	)
+
+	cmd := &serpent.Command{
+		Use:   "create [template]",
+		Short: "Create an experimental task",
+		Middleware: serpent.Chain(
+			serpent.RequireRangeArgs(0, 1),
+			r.InitClient(client),
+		),
+		Options: serpent.OptionSet{
+			{
+				Flag:     "input",
+				Env:      "CODER_TASK_INPUT",
+				Value:    serpent.StringOf(&taskInput),
+				Required: true,
+			},
+			{
+				Env:   "CODER_TASK_TEMPLATE_NAME",
+				Value: serpent.StringOf(&templateName),
+			},
+			{
+				Env:   "CODER_TASK_TEMPLATE_VERSION",
+				Value: serpent.StringOf(&templateVersionName),
+			},
+			{
+				Flag:    "preset",
+				Env:     "CODER_TASK_PRESET_NAME",
+				Value:   serpent.StringOf(&presetName),
+				Default: PresetNone,
+			},
+		},
+		Handler: func(inv *serpent.Invocation) error {
+			var (
+				ctx       = inv.Context()
+				expClient = codersdk.NewExperimentalClient(client)
+
+				templateVersionID       uuid.UUID
+				templateVersionPresetID uuid.UUID
+			)
+
+			organization, err := orgContext.Selected(inv, client)
+			if err != nil {
+				return xerrors.Errorf("get current organization: %w", err)
+			}
+
+			if len(inv.Args) > 0 {
+				templateName, templateVersionName, _ = strings.Cut(inv.Args[0], "@")
+			}
+
+			if templateName == "" {
+				return xerrors.Errorf("template name not provided")
+			}
+
+			if templateVersionName != "" {
+				templateVersion, err := client.TemplateVersionByOrganizationAndName(ctx, organization.ID, templateName, templateVersionName)
+				if err != nil {
+					return xerrors.Errorf("get template version: %w", err)
+				}
+
+				templateVersionID = templateVersion.ID
+			} else {
+				template, err := client.TemplateByName(ctx, organization.ID, templateName)
+				if err != nil {
+					return xerrors.Errorf("get template: %w", err)
+				}
+
+				templateVersionID = template.ActiveVersionID
+			}
+
+			if presetName != PresetNone {
+				templatePresets, err := client.TemplateVersionPresets(ctx, templateVersionID)
+				if err != nil {
+					return xerrors.Errorf("get template presets: %w", err)
+				}
+
+				preset, err := resolvePreset(templatePresets, presetName)
+				if err != nil {
+					return xerrors.Errorf("resolve preset: %w", err)
+				}
+
+				templateVersionPresetID = preset.ID
+			}
+
+			workspace, err := expClient.CreateTask(ctx, codersdk.Me, codersdk.CreateTaskRequest{
+				TemplateVersionID:       templateVersionID,
+				TemplateVersionPresetID: templateVersionPresetID,
+				Prompt:                  taskInput,
+			})
+			if err != nil {
+				return xerrors.Errorf("create task: %w", err)
+			}
+
+			_, _ = fmt.Fprintf(
+				inv.Stdout,
+				"The task %s has been created at %s!\n",
+				cliui.Keyword(workspace.Name),
+				cliui.Timestamp(workspace.CreatedAt),
+			)
+
+			return nil
+		},
+	}
+	orgContext.AttachOptions(cmd)
+	return cmd
+}

cli/exp_taskcreate_test.go

@@ -0,0 +1,266 @@
+package cli_test
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/coder/coder/v2/cli/clitest"
+	"github.com/coder/coder/v2/cli/cliui"
+	"github.com/coder/coder/v2/coderd/httpapi"
+	"github.com/coder/coder/v2/codersdk"
+	"github.com/coder/coder/v2/testutil"
+	"github.com/coder/serpent"
+)
+
+func TestTaskCreate(t *testing.T) {
+	t.Parallel()
+
+	var (
+		taskCreatedAt = time.Now()
+
+		organizationID          = uuid.New()
+		anotherOrganizationID   = uuid.New()
+		templateID              = uuid.New()
+		templateVersionID       = uuid.New()
+		templateVersionPresetID = uuid.New()
+	)
+
+	templateAndVersionFoundHandler := func(t *testing.T, ctx context.Context, orgID uuid.UUID, templateName, templateVersionName, presetName, prompt string) http.HandlerFunc {
+		t.Helper()
+
+		return func(w http.ResponseWriter, r *http.Request) {
+			switch r.URL.Path {
+			case "/api/v2/users/me/organizations":
+				httpapi.Write(ctx, w, http.StatusOK, []codersdk.Organization{
+					{MinimalOrganization: codersdk.MinimalOrganization{
+						ID: orgID,
+					}},
+				})
+			case fmt.Sprintf("/api/v2/organizations/%s/templates/my-template/versions/my-template-version", orgID):
+				httpapi.Write(ctx, w, http.StatusOK, codersdk.TemplateVersion{
+					ID: templateVersionID,
+				})
+			case fmt.Sprintf("/api/v2/organizations/%s/templates/my-template", orgID):
+				httpapi.Write(ctx, w, http.StatusOK, codersdk.Template{
+					ID:              templateID,
+					ActiveVersionID: templateVersionID,
+				})
+			case fmt.Sprintf("/api/v2/templateversions/%s/presets", templateVersionID):
+				httpapi.Write(ctx, w, http.StatusOK, []codersdk.Preset{
+					{
+						ID:   templateVersionPresetID,
+						Name: presetName,
+					},
+				})
+			case "/api/experimental/tasks/me":
+				var req codersdk.CreateTaskRequest
+				if !httpapi.Read(ctx, w, r, &req) {
+					return
+				}
+
+				assert.Equal(t, prompt, req.Prompt, "prompt mismatch")
+				assert.Equal(t, templateVersionID, req.TemplateVersionID, "template version mismatch")
+
+				if presetName == "" {
+					assert.Equal(t, uuid.Nil, req.TemplateVersionPresetID, "expected no template preset id")
+				} else {
+					assert.Equal(t, templateVersionPresetID, req.TemplateVersionPresetID, "template version preset id mismatch")
+				}
+
+				httpapi.Write(ctx, w, http.StatusCreated, codersdk.Workspace{
+					Name:      "task-wild-goldfish-27",
+					CreatedAt: taskCreatedAt,
+				})
+			default:
+				t.Errorf("unexpected path: %s", r.URL.Path)
+			}
+		}
+	}
+
+	tests := []struct {
+		args         []string
+		env          []string
+		expectError  string
+		expectOutput string
+		handler      func(t *testing.T, ctx context.Context) http.HandlerFunc
+	}{
+		{
+			args:         []string{"my-template@my-template-version", "--input", "my custom prompt", "--org", organizationID.String()},
+			expectOutput: fmt.Sprintf("The task %s has been created at %s!", cliui.Keyword("task-wild-goldfish-27"), cliui.Timestamp(taskCreatedAt)),
+			handler: func(t *testing.T, ctx context.Context) http.HandlerFunc {
+				return templateAndVersionFoundHandler(t, ctx, organizationID, "my-template", "my-template-version", "", "my custom prompt")
+			},
+		},
+		{
+			args:         []string{"my-template", "--input", "my custom prompt", "--org", organizationID.String()},
+			env:          []string{"CODER_TASK_TEMPLATE_VERSION=my-template-version"},
+			expectOutput: fmt.Sprintf("The task %s has been created at %s!", cliui.Keyword("task-wild-goldfish-27"), cliui.Timestamp(taskCreatedAt)),
+			handler: func(t *testing.T, ctx context.Context) http.HandlerFunc {
+				return templateAndVersionFoundHandler(t, ctx, organizationID, "my-template", "my-template-version", "", "my custom prompt")
+			},
+		},
+		{
+			args:         []string{"--input", "my custom prompt", "--org", organizationID.String()},
+			env:          []string{"CODER_TASK_TEMPLATE_NAME=my-template", "CODER_TASK_TEMPLATE_VERSION=my-template-version"},
+			expectOutput: fmt.Sprintf("The task %s has been created at %s!", cliui.Keyword("task-wild-goldfish-27"), cliui.Timestamp(taskCreatedAt)),
+			handler: func(t *testing.T, ctx context.Context) http.HandlerFunc {
+				return templateAndVersionFoundHandler(t, ctx, organizationID, "my-template", "my-template-version", "", "my custom prompt")
+			},
+		},
+		{
+			env:          []string{"CODER_TASK_TEMPLATE_NAME=my-template", "CODER_TASK_TEMPLATE_VERSION=my-template-version", "CODER_TASK_INPUT=my custom prompt", "CODER_ORGANIZATION=" + organizationID.String()},
+			expectOutput: fmt.Sprintf("The task %s has been created at %s!", cliui.Keyword("task-wild-goldfish-27"), cliui.Timestamp(taskCreatedAt)),
+			handler: func(t *testing.T, ctx context.Context) http.HandlerFunc {
+				return templateAndVersionFoundHandler(t, ctx, organizationID, "my-template", "my-template-version", "", "my custom prompt")
+			},
+		},
+		{
+			args:         []string{"my-template", "--input", "my custom prompt", "--org", organizationID.String()},
+			expectOutput: fmt.Sprintf("The task %s has been created at %s!", cliui.Keyword("task-wild-goldfish-27"), cliui.Timestamp(taskCreatedAt)),
+			handler: func(t *testing.T, ctx context.Context) http.HandlerFunc {
+				return templateAndVersionFoundHandler(t, ctx, organizationID, "my-template", "", "", "my custom prompt")
+			},
+		},
+		{
+			args:         []string{"my-template", "--input", "my custom prompt", "--preset", "my-preset", "--org", organizationID.String()},
+			expectOutput: fmt.Sprintf("The task %s has been created at %s!", cliui.Keyword("task-wild-goldfish-27"), cliui.Timestamp(taskCreatedAt)),
+			handler: func(t *testing.T, ctx context.Context) http.HandlerFunc {
+				return templateAndVersionFoundHandler(t, ctx, organizationID, "my-template", "", "my-preset", "my custom prompt")
+			},
+		},
+		{
+			args:         []string{"my-template", "--input", "my custom prompt"},
+			env:          []string{"CODER_TASK_PRESET_NAME=my-preset"},
+			expectOutput: fmt.Sprintf("The task %s has been created at %s!", cliui.Keyword("task-wild-goldfish-27"), cliui.Timestamp(taskCreatedAt)),
+			handler: func(t *testing.T, ctx context.Context) http.HandlerFunc {
+				return templateAndVersionFoundHandler(t, ctx, organizationID, "my-template", "", "my-preset", "my custom prompt")
+			},
+		},
+		{
+			args:        []string{"my-template", "--input", "my custom prompt", "--preset", "not-real-preset"},
+			expectError: `preset "not-real-preset" not found`,
+			handler: func(t *testing.T, ctx context.Context) http.HandlerFunc {
+				return templateAndVersionFoundHandler(t, ctx, organizationID, "my-template", "", "my-preset", "my custom prompt")
+			},
+		},
+		{
+			args:        []string{"my-template@not-real-template-version", "--input", "my custom prompt"},
+			expectError: httpapi.ResourceNotFoundResponse.Message,
+			handler: func(t *testing.T, ctx context.Context) http.HandlerFunc {
+				return func(w http.ResponseWriter, r *http.Request) {
+					switch r.URL.Path {
+					case "/api/v2/users/me/organizations":
+						httpapi.Write(ctx, w, http.StatusOK, []codersdk.Organization{
+							{MinimalOrganization: codersdk.MinimalOrganization{
+								ID: organizationID,
+							}},
+						})
+					case fmt.Sprintf("/api/v2/organizations/%s/templates/my-template/versions/not-real-template-version", organizationID):
+						httpapi.ResourceNotFound(w)
+					default:
+						t.Errorf("unexpected path: %s", r.URL.Path)
+					}
+				}
+			},
+		},
+		{
+			args:        []string{"not-real-template", "--input", "my custom prompt", "--org", organizationID.String()},
+			expectError: httpapi.ResourceNotFoundResponse.Message,
+			handler: func(t *testing.T, ctx context.Context) http.HandlerFunc {
+				return func(w http.ResponseWriter, r *http.Request) {
+					switch r.URL.Path {
+					case "/api/v2/users/me/organizations":
+						httpapi.Write(ctx, w, http.StatusOK, []codersdk.Organization{
+							{MinimalOrganization: codersdk.MinimalOrganization{
+								ID: organizationID,
+							}},
+						})
+					case fmt.Sprintf("/api/v2/organizations/%s/templates/not-real-template", organizationID):
+						httpapi.ResourceNotFound(w)
+					default:
+						t.Errorf("unexpected path: %s", r.URL.Path)
+					}
+				}
+			},
+		},
+		{
+			args:        []string{"template-in-different-org", "--input", "my-custom-prompt", "--org", anotherOrganizationID.String()},
+			expectError: httpapi.ResourceNotFoundResponse.Message,
+			handler: func(t *testing.T, ctx context.Context) http.HandlerFunc {
+				return func(w http.ResponseWriter, r *http.Request) {
+					switch r.URL.Path {
+					case "/api/v2/users/me/organizations":
+						httpapi.Write(ctx, w, http.StatusOK, []codersdk.Organization{
+							{MinimalOrganization: codersdk.MinimalOrganization{
+								ID: anotherOrganizationID,
+							}},
+						})
+					case fmt.Sprintf("/api/v2/organizations/%s/templates/template-in-different-org", anotherOrganizationID):
+						httpapi.ResourceNotFound(w)
+					default:
+						t.Errorf("unexpected path: %s", r.URL.Path)
+					}
+				}
+			},
+		},
+		{
+			args:        []string{"no-org", "--input", "my-custom-prompt"},
+			expectError: "Must select an organization with --org=<org_name>",
+			handler: func(t *testing.T, ctx context.Context) http.HandlerFunc {
+				return func(w http.ResponseWriter, r *http.Request) {
+					switch r.URL.Path {
+					case "/api/v2/users/me/organizations":
+						httpapi.Write(ctx, w, http.StatusOK, []codersdk.Organization{})
+					default:
+						t.Errorf("unexpected path: %s", r.URL.Path)
+					}
+				}
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(strings.Join(tt.args, ","), func(t *testing.T) {
+			t.Parallel()
+
+			var (
+				ctx    = testutil.Context(t, testutil.WaitShort)
+				srv    = httptest.NewServer(tt.handler(t, ctx))
+				client = new(codersdk.Client)
+				args   = []string{"exp", "task", "create"}
+				sb     strings.Builder
+				err    error
+			)
+
+			t.Cleanup(srv.Close)
+
+			client.URL, err = url.Parse(srv.URL)
+			require.NoError(t, err)
+
+			inv, root := clitest.New(t, append(args, tt.args...)...)
+			inv.Environ = serpent.ParseEnviron(tt.env, "")
+			inv.Stdout = &sb
+			inv.Stderr = &sb
+			clitest.SetupConfig(t, client, root)
+
+			err = inv.WithContext(ctx).Run()
+			if tt.expectError == "" {
+				assert.NoError(t, err)
+			} else {
+				assert.ErrorContains(t, err, tt.expectError)
+			}
+
+			assert.Contains(t, sb.String(), tt.expectOutput)
+		})
+	}
+}