feat: purge expired api keys in dbpurge (#20863) (#21040)

Backport of https://github.com/coder/coder/pull/20863

.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
@@ -350,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
@@ -387,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
@@ -409,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.
@@ -476,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
@@ -484,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 }}
@@ -501,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
@@ -572,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
@@ -615,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
@@ -634,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
@@ -656,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
 
@@ -671,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 }}
@@ -691,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 }}
@@ -739,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
 
@@ -769,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"
@@ -784,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
@@ -803,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:
@@ -815,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
 
@@ -825,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
@@ -846,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
@@ -878,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
@@ -895,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.
@@ -905,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

@@ -460,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
@@ -478,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
@@ -489,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
@@ -504,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:
@@ -528,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:
@@ -549,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
@@ -588,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)
@@ -638,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
@@ -681,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 \
@@ -888,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
@@ -929,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

@@ -98,7 +98,7 @@ type Client interface {
 	ConnectRPC26(ctx context.Context) (
 		proto.DRPCAgentClient26, tailnetproto.DRPCTailnetClient26, error,
 	)
-	RewriteDERPMap(derpMap *tailcfg.DERPMap)
+	tailnet.DERPMapRewriter
 }
 
 type Agent interface {
@@ -336,18 +336,16 @@ func (a *agent) init() {
 	// will not report anywhere.
 	a.scriptRunner.RegisterMetrics(a.prometheusRegistry)
 
-	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)
-			}),
-		}
-		containerAPIOpts = append(containerAPIOpts, a.containerAPIOptions...)
-
-		a.containerAPI = agentcontainers.NewAPI(a.logger.Named("containers"), containerAPIOpts...)
+	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"),
@@ -565,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.
@@ -793,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.
@@ -828,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()
 
@@ -1089,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))
@@ -1163,7 +1171,7 @@ func (a *agent) handleManifest(manifestOK *checkpoint) func(ctx context.Context,
 				scripts             = manifest.Scripts
 				devcontainerScripts map[uuid.UUID]codersdk.WorkspaceAgentScript
 			)
-			if a.containerAPI != nil {
+			if a.devcontainers {
 				// 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
@@ -1171,7 +1179,7 @@ func (a *agent) handleManifest(manifestOK *checkpoint) func(ctx context.Context,
 				// return existing devcontainers but actual container detection
 				// and creation will be deferred.
 				a.containerAPI.Init(
-					agentcontainers.WithManifestInfo(manifest.OwnerName, manifest.WorkspaceName, manifest.AgentName),
+					agentcontainers.WithManifestInfo(manifest.OwnerName, manifest.WorkspaceName, manifest.AgentName, manifest.Directory),
 					agentcontainers.WithDevcontainers(manifest.Devcontainers, manifest.Scripts),
 					agentcontainers.WithSubAgentClient(agentcontainers.NewSubAgentClientFromAPI(a.logger, aAPI)),
 				)
@@ -1198,7 +1206,7 @@ func (a *agent) handleManifest(manifestOK *checkpoint) func(ctx context.Context,
 				// autostarted devcontainer will be included in this time.
 				err := a.scriptRunner.Execute(a.gracefulCtx, agentscripts.ExecuteStartScripts)
 
-				if a.containerAPI != nil {
+				if a.devcontainers {
 					// Start the container API after the startup scripts have
 					// been executed to ensure that the required tools can be
 					// installed.
@@ -1929,10 +1937,8 @@ func (a *agent) Close() error {
 		a.logger.Error(a.hardCtx, "script runner close", slog.Error(err))
 	}
 
-	if a.containerAPI != nil {
-		if err := a.containerAPI.Close(); err != nil {
-			a.logger.Error(a.hardCtx, "container API 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

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,10 +60,12 @@ type API struct {
 	cancel                      context.CancelFunc
 	watcherDone                 chan struct{}
 	updaterDone                 chan struct{}
+	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
@@ -68,12 +77,17 @@ type API struct {
 	subAgentURL                 string
 	subAgentEnv                 []string
 
-	ownerName     string
-	workspaceName string
-	parentAgent   string
+	projectDiscovery   bool // If we should perform project discovery or not.
+	discoveryAutostart bool // If we should autostart discovered projects.
+
+	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.
@@ -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,11 +204,12 @@ func WithSubAgentEnv(env ...string) Option {
 
 // WithManifestInfo sets the owner name, and workspace name
 // for the sub-agent.
-func WithManifestInfo(owner, workspace, parentAgent 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
 	}
 }
 
@@ -257,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 {
@@ -327,6 +367,9 @@ 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)
@@ -368,6 +411,12 @@ func (api *API) Start() {
 		return
 	}
 
+	if api.projectDiscovery && api.agentDirectory != "" {
+		api.discoverDone = make(chan struct{})
+
+		go api.discover()
+	}
+
 	api.watcherDone = make(chan struct{})
 	api.updaterDone = make(chan struct{})
 
@@ -375,6 +424,162 @@ func (api *API) Start() {
 	go api.updaterLoop()
 }
 
+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() {
 	defer close(api.watcherDone)
 	defer api.logger.Debug(api.ctx, "watcher loop stopped")
@@ -449,6 +654,7 @@ func (api *API) updaterLoop() {
 	// 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)
 		var sent bool
@@ -466,9 +672,15 @@ func (api *API) updaterLoop() {
 			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")
@@ -528,6 +740,7 @@ func (api *API) Routes() http.Handler {
 	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/{devcontainer}", func(r chi.Router) {
@@ -537,6 +750,92 @@ func (api *API) Routes() http.Handler {
 	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()
@@ -576,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
@@ -626,17 +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 || container.Labels[DevcontainerIsTestRunLabel] == "true" {
-			var ok bool
+		if len(api.containerLabelIncludeFilter) > 0 {
+			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
 			}
@@ -717,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 = ""
 				}
 			}
 
@@ -943,7 +1268,10 @@ 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.broadcastUpdatesLocked()
+
 	go func() {
 		_ = api.CreateDevcontainer(dc.WorkspaceFolder, dc.ConfigPath, WithRemoveExistingContainer())
 	}()
@@ -1032,6 +1360,7 @@ func (api *API) CreateDevcontainer(workspaceFolder, configPath string, opts ...D
 		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()
@@ -1055,8 +1384,10 @@ func (api *API) CreateDevcontainer(workspaceFolder, configPath string, opts ...D
 		}
 	}
 	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
@@ -1523,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)
@@ -1531,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
@@ -1686,6 +2018,9 @@ func (api *API) Close() error {
 	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/devcontainercli.go

@@ -91,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 {
@@ -106,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)
 		}
 	}
 }
@@ -185,8 +186,8 @@ func WithReadConfigOutput(stdout, stderr io.Writer) DevcontainerCLIReadConfigOpt
 	}
 }
 
-func applyDevcontainerCLIUpOptions(opts []DevcontainerCLIUpOptions) devcontainerCLIUpConfig {
-	conf := devcontainerCLIUpConfig{stdout: io.Discard, stderr: io.Discard}
+func applyDevcontainerCLIUpOptions(opts []DevcontainerCLIUpOptions) DevcontainerCLIUpConfig {
+	conf := DevcontainerCLIUpConfig{Stdout: io.Discard, Stderr: io.Discard}
 	for _, opt := range opts {
 		if opt != nil {
 			opt(&conf)
@@ -195,8 +196,8 @@ func applyDevcontainerCLIUpOptions(opts []DevcontainerCLIUpOptions) devcontainer
 	return conf
 }
 
-func applyDevcontainerCLIExecOptions(opts []DevcontainerCLIExecOptions) devcontainerCLIExecConfig {
-	conf := devcontainerCLIExecConfig{stdout: io.Discard, stderr: io.Discard}
+func applyDevcontainerCLIExecOptions(opts []DevcontainerCLIExecOptions) DevcontainerCLIExecConfig {
+	conf := DevcontainerCLIExecConfig{Stdout: io.Discard, Stderr: io.Discard}
 	for _, opt := range opts {
 		if opt != nil {
 			opt(&conf)
@@ -241,7 +242,7 @@ 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.
@@ -251,14 +252,14 @@ func (d *devcontainerCLI) Up(ctx context.Context, workspaceFolder, configPath st
 		&devcontainerCLILogWriter{
 			ctx:    ctx,
 			logger: logger.With(slog.F("stdout", true)),
-			writer: conf.stdout,
+			writer: conf.Stdout,
 		},
 	)
 	// Stream stderr logs and provided writer if any.
 	cmd.Stderr = &devcontainerCLILogWriter{
 		ctx:    ctx,
 		logger: logger.With(slog.F("stderr", true)),
-		writer: conf.stderr,
+		writer: conf.Stderr,
 	}
 
 	if err := cmd.Run(); err != nil {
@@ -293,17 +294,17 @@ 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...)
 
-	c.Stdout = io.MultiWriter(conf.stdout, &devcontainerCLILogWriter{
+	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{
+	c.Stderr = io.MultiWriter(conf.Stderr, &devcontainerCLILogWriter{
 		ctx:    ctx,
 		logger: logger.With(slog.F("stderr", true)),
 		writer: io.Discard,

agent/agentcontainers/devcontainercli_test.go

@@ -593,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")

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/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

@@ -149,7 +149,6 @@ 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, ExecuteCronScripts)
 			if err != nil {
@@ -224,7 +223,6 @@ func (r *Runner) Execute(ctx context.Context, option ExecuteOption) error {
 			continue
 		}
 
-		script := script
 		eg.Go(func() error {
 			err := r.trackRun(ctx, script, option)
 			if err != nil {

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 {
@@ -131,9 +137,10 @@ type Server struct {
 	// 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
 
@@ -190,6 +197,20 @@ func NewServer(ctx context.Context, logger slog.Logger, prometheusRegistry *prom
 		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{
@@ -457,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")
@@ -590,7 +611,9 @@ func (s *Server) startNonPTYSession(logger slog.Logger, session ssh.Session, mag
 	// and SSH server close may be delayed.
 	cmd.SysProcAttr = cmdSysProcAttr()
 
-	// to match OpenSSH, we don't actually tear a non-TTY command down, even if the session ends.
+	// 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
 
@@ -1154,6 +1177,9 @@ func (s *Server) Close() error {
 
 	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/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,6 +6,7 @@ import (
 	"time"
 
 	"github.com/go-chi/chi/v5"
+	"github.com/google/uuid"
 
 	"github.com/coder/coder/v2/coderd/httpapi"
 	"github.com/coder/coder/v2/codersdk"
@@ -36,12 +37,19 @@ func (a *agent) apiHandler() http.Handler {
 		cacheDuration: cacheDuration,
 	}
 
-	if a.containerAPI != nil {
+	if a.devcontainers {
 		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.",
 			})
 		})

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

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)
+		})
+	}
+}

cli/exp_tasklist.go

@@ -0,0 +1,142 @@
+package cli
+
+import (
+	"fmt"
+	"strings"
+	"time"
+
+	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/v2/cli/cliui"
+	"github.com/coder/coder/v2/codersdk"
+	"github.com/coder/serpent"
+)
+
+type taskListRow struct {
+	Task codersdk.Task `table:"t,recursive_inline"`
+
+	StateChangedAgo string `table:"state changed"`
+}
+
+func taskListRowFromTask(now time.Time, t codersdk.Task) taskListRow {
+	var stateAgo string
+	if t.CurrentState != nil {
+		stateAgo = now.UTC().Sub(t.CurrentState.Timestamp).Truncate(time.Second).String() + " ago"
+	}
+
+	return taskListRow{
+		Task: t,
+
+		StateChangedAgo: stateAgo,
+	}
+}
+
+func (r *RootCmd) taskList() *serpent.Command {
+	var (
+		statusFilter string
+		all          bool
+		user         string
+
+		client    = new(codersdk.Client)
+		formatter = cliui.NewOutputFormatter(
+			cliui.TableFormat(
+				[]taskListRow{},
+				[]string{
+					"id",
+					"name",
+					"status",
+					"state",
+					"state changed",
+					"message",
+				},
+			),
+			cliui.ChangeFormatterData(
+				cliui.JSONFormat(),
+				func(data any) (any, error) {
+					rows, ok := data.([]taskListRow)
+					if !ok {
+						return nil, xerrors.Errorf("expected []taskListRow, got %T", data)
+					}
+					out := make([]codersdk.Task, len(rows))
+					for i := range rows {
+						out[i] = rows[i].Task
+					}
+					return out, nil
+				},
+			),
+		)
+	)
+
+	cmd := &serpent.Command{
+		Use:     "list",
+		Short:   "List experimental tasks",
+		Aliases: []string{"ls"},
+		Middleware: serpent.Chain(
+			serpent.RequireNArgs(0),
+			r.InitClient(client),
+		),
+		Options: serpent.OptionSet{
+			{
+				Name:        "status",
+				Description: "Filter by task status (e.g. running, failed, etc).",
+				Flag:        "status",
+				Default:     "",
+				Value:       serpent.StringOf(&statusFilter),
+			},
+			{
+				Name:          "all",
+				Description:   "List tasks for all users you can view.",
+				Flag:          "all",
+				FlagShorthand: "a",
+				Default:       "false",
+				Value:         serpent.BoolOf(&all),
+			},
+			{
+				Name:        "user",
+				Description: "List tasks for the specified user (username, \"me\").",
+				Flag:        "user",
+				Default:     "",
+				Value:       serpent.StringOf(&user),
+			},
+		},
+		Handler: func(inv *serpent.Invocation) error {
+			ctx := inv.Context()
+			exp := codersdk.NewExperimentalClient(client)
+
+			targetUser := strings.TrimSpace(user)
+			if targetUser == "" && !all {
+				targetUser = codersdk.Me
+			}
+
+			tasks, err := exp.Tasks(ctx, &codersdk.TasksFilter{
+				Owner:  targetUser,
+				Status: statusFilter,
+			})
+			if err != nil {
+				return xerrors.Errorf("list tasks: %w", err)
+			}
+
+			// If no rows and not JSON, show a friendly message.
+			if len(tasks) == 0 && formatter.FormatID() != cliui.JSONFormat().ID() {
+				_, _ = fmt.Fprintln(inv.Stderr, "No tasks found.")
+				return nil
+			}
+
+			rows := make([]taskListRow, len(tasks))
+			now := time.Now()
+			for i := range tasks {
+				rows[i] = taskListRowFromTask(now, tasks[i])
+			}
+
+			out, err := formatter.Format(ctx, rows)
+			if err != nil {
+				return xerrors.Errorf("format tasks: %w", err)
+			}
+			_, _ = fmt.Fprintln(inv.Stdout, out)
+			return nil
+		},
+	}
+
+	formatter.AttachOptions(&cmd.Options)
+	return cmd
+}

cli/exp_tasklist_test.go

@@ -0,0 +1,278 @@
+package cli_test
+
+import (
+	"bytes"
+	"context"
+	"database/sql"
+	"encoding/json"
+	"io"
+	"testing"
+
+	"github.com/google/uuid"
+	"github.com/stretchr/testify/require"
+
+	"cdr.dev/slog"
+	"cdr.dev/slog/sloggers/sloghuman"
+
+	"github.com/coder/coder/v2/cli/clitest"
+	"github.com/coder/coder/v2/coderd/coderdtest"
+	"github.com/coder/coder/v2/coderd/database"
+	"github.com/coder/coder/v2/coderd/database/dbauthz"
+	"github.com/coder/coder/v2/coderd/database/dbfake"
+	"github.com/coder/coder/v2/coderd/database/dbgen"
+	"github.com/coder/coder/v2/coderd/util/slice"
+	"github.com/coder/coder/v2/codersdk"
+	"github.com/coder/coder/v2/pty/ptytest"
+	"github.com/coder/coder/v2/testutil"
+)
+
+// makeAITask creates an AI-task workspace.
+func makeAITask(t *testing.T, db database.Store, orgID, adminID, ownerID uuid.UUID, transition database.WorkspaceTransition, prompt string) (workspace database.WorkspaceTable) {
+	t.Helper()
+
+	tv := dbfake.TemplateVersion(t, db).
+		Seed(database.TemplateVersion{
+			OrganizationID: orgID,
+			CreatedBy:      adminID,
+			HasAITask: sql.NullBool{
+				Bool:  true,
+				Valid: true,
+			},
+		}).Do()
+
+	ws := database.WorkspaceTable{
+		OrganizationID: orgID,
+		OwnerID:        ownerID,
+		TemplateID:     tv.Template.ID,
+	}
+	build := dbfake.WorkspaceBuild(t, db, ws).
+		Seed(database.WorkspaceBuild{
+			TemplateVersionID: tv.TemplateVersion.ID,
+			Transition:        transition,
+		}).WithAgent().Do()
+	dbgen.WorkspaceBuildParameters(t, db, []database.WorkspaceBuildParameter{
+		{
+			WorkspaceBuildID: build.Build.ID,
+			Name:             codersdk.AITaskPromptParameterName,
+			Value:            prompt,
+		},
+	})
+	agents, err := db.GetWorkspaceAgentsByWorkspaceAndBuildNumber(
+		dbauthz.AsSystemRestricted(context.Background()),
+		database.GetWorkspaceAgentsByWorkspaceAndBuildNumberParams{
+			WorkspaceID: build.Workspace.ID,
+			BuildNumber: build.Build.BuildNumber,
+		},
+	)
+	require.NoError(t, err)
+	require.NotEmpty(t, agents)
+	agentID := agents[0].ID
+
+	// Create a workspace app and set it as the sidebar app.
+	app := dbgen.WorkspaceApp(t, db, database.WorkspaceApp{
+		AgentID:     agentID,
+		Slug:        "task-sidebar",
+		DisplayName: "Task Sidebar",
+		External:    false,
+	})
+
+	// Update build flags to reference the sidebar app and HasAITask=true.
+	err = db.UpdateWorkspaceBuildFlagsByID(
+		dbauthz.AsSystemRestricted(context.Background()),
+		database.UpdateWorkspaceBuildFlagsByIDParams{
+			ID:               build.Build.ID,
+			HasAITask:        sql.NullBool{Bool: true, Valid: true},
+			HasExternalAgent: sql.NullBool{Bool: false, Valid: false},
+			SidebarAppID:     uuid.NullUUID{UUID: app.ID, Valid: true},
+			UpdatedAt:        build.Build.UpdatedAt,
+		},
+	)
+	require.NoError(t, err)
+
+	return build.Workspace
+}
+
+func TestExpTaskList(t *testing.T) {
+	t.Parallel()
+
+	t.Run("NoTasks_Table", func(t *testing.T) {
+		t.Parallel()
+
+		// Quiet logger to reduce noise.
+		quiet := slog.Make(sloghuman.Sink(io.Discard))
+		client, _ := coderdtest.NewWithDatabase(t, &coderdtest.Options{Logger: &quiet})
+		owner := coderdtest.CreateFirstUser(t, client)
+		memberClient, _ := coderdtest.CreateAnotherUser(t, client, owner.OrganizationID)
+
+		inv, root := clitest.New(t, "exp", "task", "list")
+		clitest.SetupConfig(t, memberClient, root)
+
+		pty := ptytest.New(t).Attach(inv)
+		ctx := testutil.Context(t, testutil.WaitShort)
+
+		err := inv.WithContext(ctx).Run()
+		require.NoError(t, err)
+
+		pty.ExpectMatch("No tasks found.")
+	})
+
+	t.Run("Single_Table", func(t *testing.T) {
+		t.Parallel()
+
+		// Quiet logger to reduce noise.
+		quiet := slog.Make(sloghuman.Sink(io.Discard))
+		client, db := coderdtest.NewWithDatabase(t, &coderdtest.Options{Logger: &quiet})
+		owner := coderdtest.CreateFirstUser(t, client)
+		memberClient, memberUser := coderdtest.CreateAnotherUser(t, client, owner.OrganizationID)
+
+		wantPrompt := "build me a web app"
+		ws := makeAITask(t, db, owner.OrganizationID, owner.UserID, memberUser.ID, database.WorkspaceTransitionStart, wantPrompt)
+
+		inv, root := clitest.New(t, "exp", "task", "list", "--column", "id,name,status,initial prompt")
+		clitest.SetupConfig(t, memberClient, root)
+
+		pty := ptytest.New(t).Attach(inv)
+		ctx := testutil.Context(t, testutil.WaitShort)
+
+		err := inv.WithContext(ctx).Run()
+		require.NoError(t, err)
+
+		// Validate the table includes the task and status.
+		pty.ExpectMatch(ws.Name)
+		pty.ExpectMatch("running")
+		pty.ExpectMatch(wantPrompt)
+	})
+
+	t.Run("StatusFilter_JSON", func(t *testing.T) {
+		t.Parallel()
+
+		// Quiet logger to reduce noise.
+		quiet := slog.Make(sloghuman.Sink(io.Discard))
+		client, db := coderdtest.NewWithDatabase(t, &coderdtest.Options{Logger: &quiet})
+		owner := coderdtest.CreateFirstUser(t, client)
+		memberClient, memberUser := coderdtest.CreateAnotherUser(t, client, owner.OrganizationID)
+
+		// Create two AI tasks: one running, one stopped.
+		running := makeAITask(t, db, owner.OrganizationID, owner.UserID, memberUser.ID, database.WorkspaceTransitionStart, "keep me running")
+		stopped := makeAITask(t, db, owner.OrganizationID, owner.UserID, memberUser.ID, database.WorkspaceTransitionStop, "stop me please")
+
+		// Use JSON output to reliably validate filtering.
+		inv, root := clitest.New(t, "exp", "task", "list", "--status=stopped", "--output=json")
+		clitest.SetupConfig(t, memberClient, root)
+
+		ctx := testutil.Context(t, testutil.WaitShort)
+		var stdout bytes.Buffer
+		inv.Stdout = &stdout
+		inv.Stderr = &stdout
+
+		err := inv.WithContext(ctx).Run()
+		require.NoError(t, err)
+
+		var tasks []codersdk.Task
+		require.NoError(t, json.Unmarshal(stdout.Bytes(), &tasks))
+
+		// Only the stopped task is returned.
+		require.Len(t, tasks, 1, "expected one task after filtering")
+		require.Equal(t, stopped.ID, tasks[0].ID)
+		require.NotEqual(t, running.ID, tasks[0].ID)
+	})
+
+	t.Run("UserFlag_Me_Table", func(t *testing.T) {
+		t.Parallel()
+
+		quiet := slog.Make(sloghuman.Sink(io.Discard))
+		client, db := coderdtest.NewWithDatabase(t, &coderdtest.Options{Logger: &quiet})
+		owner := coderdtest.CreateFirstUser(t, client)
+		_, memberUser := coderdtest.CreateAnotherUser(t, client, owner.OrganizationID)
+
+		_ = makeAITask(t, db, owner.OrganizationID, owner.UserID, memberUser.ID, database.WorkspaceTransitionStart, "other-task")
+		ws := makeAITask(t, db, owner.OrganizationID, owner.UserID, owner.UserID, database.WorkspaceTransitionStart, "me-task")
+
+		inv, root := clitest.New(t, "exp", "task", "list", "--user", "me")
+		//nolint:gocritic // Owner client is intended here smoke test the member task not showing up.
+		clitest.SetupConfig(t, client, root)
+
+		pty := ptytest.New(t).Attach(inv)
+		ctx := testutil.Context(t, testutil.WaitShort)
+
+		err := inv.WithContext(ctx).Run()
+		require.NoError(t, err)
+
+		pty.ExpectMatch(ws.Name)
+	})
+}
+
+func TestExpTaskList_OwnerCanListOthers(t *testing.T) {
+	t.Parallel()
+
+	// Quiet logger to reduce noise.
+	quiet := slog.Make(sloghuman.Sink(io.Discard))
+	ownerClient, db := coderdtest.NewWithDatabase(t, &coderdtest.Options{Logger: &quiet})
+	owner := coderdtest.CreateFirstUser(t, ownerClient)
+
+	// Create two additional members in the owner's organization.
+	_, memberAUser := coderdtest.CreateAnotherUser(t, ownerClient, owner.OrganizationID)
+	_, memberBUser := coderdtest.CreateAnotherUser(t, ownerClient, owner.OrganizationID)
+
+	// Seed an AI task for member A and B.
+	_ = makeAITask(t, db, owner.OrganizationID, owner.UserID, memberAUser.ID, database.WorkspaceTransitionStart, "member-A-task")
+	_ = makeAITask(t, db, owner.OrganizationID, owner.UserID, memberBUser.ID, database.WorkspaceTransitionStart, "member-B-task")
+
+	t.Run("OwnerListsSpecificUserWithUserFlag_JSON", func(t *testing.T) {
+		t.Parallel()
+
+		// As the owner, list only member A tasks.
+		inv, root := clitest.New(t, "exp", "task", "list", "--user", memberAUser.Username, "--output=json")
+		//nolint:gocritic // Owner client is intended here to allow member tasks to be listed.
+		clitest.SetupConfig(t, ownerClient, root)
+
+		var stdout bytes.Buffer
+		inv.Stdout = &stdout
+
+		ctx := testutil.Context(t, testutil.WaitShort)
+
+		err := inv.WithContext(ctx).Run()
+		require.NoError(t, err)
+
+		var tasks []codersdk.Task
+		require.NoError(t, json.Unmarshal(stdout.Bytes(), &tasks))
+
+		// At least one task to belong to member A.
+		require.NotEmpty(t, tasks, "expected at least one task for member A")
+		// All tasks should belong to member A.
+		for _, task := range tasks {
+			require.Equal(t, memberAUser.ID, task.OwnerID, "expected only member A tasks")
+		}
+	})
+
+	t.Run("OwnerListsAllWithAllFlag_JSON", func(t *testing.T) {
+		t.Parallel()
+
+		// As the owner, list all tasks to verify both member tasks are present.
+		// Use JSON output to reliably validate filtering.
+		inv, root := clitest.New(t, "exp", "task", "list", "--all", "--output=json")
+		//nolint:gocritic // Owner client is intended here to allow all tasks to be listed.
+		clitest.SetupConfig(t, ownerClient, root)
+
+		var stdout bytes.Buffer
+		inv.Stdout = &stdout
+
+		ctx := testutil.Context(t, testutil.WaitShort)
+
+		err := inv.WithContext(ctx).Run()
+		require.NoError(t, err)
+
+		var tasks []codersdk.Task
+		require.NoError(t, json.Unmarshal(stdout.Bytes(), &tasks))
+
+		// Expect at least two tasks and ensure both owners (member A and member B) are represented.
+		require.GreaterOrEqual(t, len(tasks), 2, "expected two or more tasks in --all listing")
+
+		// Use slice.Find for concise existence checks.
+		_, foundA := slice.Find(tasks, func(t codersdk.Task) bool { return t.OwnerID == memberAUser.ID })
+		_, foundB := slice.Find(tasks, func(t codersdk.Task) bool { return t.OwnerID == memberBUser.ID })
+
+		require.True(t, foundA, "expected at least one task for member A in --all listing")
+		require.True(t, foundB, "expected at least one task for member B in --all listing")
+	})
+}

cli/list.go

@@ -18,7 +18,7 @@ import (
 // workspaceListRow is the type provided to the OutputFormatter. This is a bit
 // dodgy but it's the only way to do complex display code for one format vs. the
 // other.
-type workspaceListRow struct {
+type WorkspaceListRow struct {
 	// For JSON format:
 	codersdk.Workspace `table:"-"`
 
@@ -40,7 +40,7 @@ type workspaceListRow struct {
 	DailyCost        string    `json:"-" table:"daily cost"`
 }
 
-func workspaceListRowFromWorkspace(now time.Time, workspace codersdk.Workspace) workspaceListRow {
+func WorkspaceListRowFromWorkspace(now time.Time, workspace codersdk.Workspace) WorkspaceListRow {
 	status := codersdk.WorkspaceDisplayStatus(workspace.LatestBuild.Job.Status, workspace.LatestBuild.Transition)
 
 	lastBuilt := now.UTC().Sub(workspace.LatestBuild.Job.CreatedAt).Truncate(time.Second)
@@ -55,7 +55,7 @@ func workspaceListRowFromWorkspace(now time.Time, workspace codersdk.Workspace)
 		favIco = "★"
 	}
 	workspaceName := favIco + " " + workspace.OwnerName + "/" + workspace.Name
-	return workspaceListRow{
+	return WorkspaceListRow{
 		Favorite:         workspace.Favorite,
 		Workspace:        workspace,
 		WorkspaceName:    workspaceName,
@@ -80,7 +80,7 @@ func (r *RootCmd) list() *serpent.Command {
 		filter    cliui.WorkspaceFilter
 		formatter = cliui.NewOutputFormatter(
 			cliui.TableFormat(
-				[]workspaceListRow{},
+				[]WorkspaceListRow{},
 				[]string{
 					"workspace",
 					"template",
@@ -107,7 +107,7 @@ func (r *RootCmd) list() *serpent.Command {
 			r.InitClient(client),
 		),
 		Handler: func(inv *serpent.Invocation) error {
-			res, err := queryConvertWorkspaces(inv.Context(), client, filter.Filter(), workspaceListRowFromWorkspace)
+			res, err := QueryConvertWorkspaces(inv.Context(), client, filter.Filter(), WorkspaceListRowFromWorkspace)
 			if err != nil {
 				return err
 			}
@@ -137,9 +137,9 @@ func (r *RootCmd) list() *serpent.Command {
 // queryConvertWorkspaces is a helper function for converting
 // codersdk.Workspaces to a different type.
 // It's used by the list command to convert workspaces to
-// workspaceListRow, and by the schedule command to
+// WorkspaceListRow, and by the schedule command to
 // convert workspaces to scheduleListRow.
-func queryConvertWorkspaces[T any](ctx context.Context, client *codersdk.Client, filter codersdk.WorkspaceFilter, convertF func(time.Time, codersdk.Workspace) T) ([]T, error) {
+func QueryConvertWorkspaces[T any](ctx context.Context, client *codersdk.Client, filter codersdk.WorkspaceFilter, convertF func(time.Time, codersdk.Workspace) T) ([]T, error) {
 	var empty []T
 	workspaces, err := client.Workspaces(ctx, filter)
 	if err != nil {

cli/open.go

@@ -11,7 +11,9 @@ import (
 	"runtime"
 	"slices"
 	"strings"
+	"time"
 
+	"github.com/google/uuid"
 	"github.com/skratchdot/open-golang/open"
 	"golang.org/x/xerrors"
 
@@ -42,7 +44,6 @@ func (r *RootCmd) openVSCode() *serpent.Command {
 		generateToken    bool
 		testOpenError    bool
 		appearanceConfig codersdk.AppearanceConfig
-		containerName    string
 	)
 
 	client := new(codersdk.Client)
@@ -71,7 +72,7 @@ func (r *RootCmd) openVSCode() *serpent.Command {
 			// need to wait for the agent to start.
 			workspaceQuery := inv.Args[0]
 			autostart := true
-			workspace, workspaceAgent, err := getWorkspaceAndAgent(ctx, inv, client, autostart, workspaceQuery)
+			workspace, workspaceAgent, otherWorkspaceAgents, err := GetWorkspaceAndAgent(ctx, inv, client, autostart, workspaceQuery)
 			if err != nil {
 				return xerrors.Errorf("get workspace and agent: %w", err)
 			}
@@ -79,6 +80,70 @@ func (r *RootCmd) openVSCode() *serpent.Command {
 			workspaceName := workspace.Name + "." + workspaceAgent.Name
 			insideThisWorkspace := insideAWorkspace && inWorkspaceName == workspaceName
 
+			// To properly work with devcontainers, VS Code has to connect to
+			// parent workspace agent. It will then proceed to enter the
+			// container given the correct parameters. There is inherently no
+			// dependency on the devcontainer agent in this scenario, but
+			// relying on it simplifies the logic and ensures the devcontainer
+			// is ready. To eliminate the dependency we would need to know that
+			// a sub-agent that hasn't been created yet may be a devcontainer,
+			// and thus will be created at a later time as well as expose the
+			// container folder on the API response.
+			var parentWorkspaceAgent codersdk.WorkspaceAgent
+			var devcontainer codersdk.WorkspaceAgentDevcontainer
+			if workspaceAgent.ParentID.Valid {
+				// This is likely a devcontainer agent, so we need to find the
+				// parent workspace agent as well as the devcontainer.
+				for _, otherAgent := range otherWorkspaceAgents {
+					if otherAgent.ID == workspaceAgent.ParentID.UUID {
+						parentWorkspaceAgent = otherAgent
+						break
+					}
+				}
+				if parentWorkspaceAgent.ID == uuid.Nil {
+					return xerrors.Errorf("parent workspace agent %s not found", workspaceAgent.ParentID.UUID)
+				}
+
+				printedWaiting := false
+				for {
+					resp, err := client.WorkspaceAgentListContainers(ctx, parentWorkspaceAgent.ID, nil)
+					if err != nil {
+						return xerrors.Errorf("list parent workspace agent containers: %w", err)
+					}
+
+					for _, dc := range resp.Devcontainers {
+						if dc.Agent.ID == workspaceAgent.ID {
+							devcontainer = dc
+							break
+						}
+					}
+					if devcontainer.ID == uuid.Nil {
+						cliui.Warnf(inv.Stderr, "Devcontainer %q not found, opening as a regular workspace...", workspaceAgent.Name)
+						parentWorkspaceAgent = codersdk.WorkspaceAgent{} // Reset to empty, so we don't use it later.
+						break
+					}
+
+					// Precondition, the devcontainer must be running to enter
+					// it. Once running, devcontainer.Container will be set.
+					if devcontainer.Status == codersdk.WorkspaceAgentDevcontainerStatusRunning {
+						break
+					}
+					if devcontainer.Status != codersdk.WorkspaceAgentDevcontainerStatusStarting {
+						return xerrors.Errorf("devcontainer %q is in unexpected status %q, expected %q or %q",
+							devcontainer.Name, devcontainer.Status,
+							codersdk.WorkspaceAgentDevcontainerStatusRunning,
+							codersdk.WorkspaceAgentDevcontainerStatusStarting,
+						)
+					}
+
+					if !printedWaiting {
+						_, _ = fmt.Fprintf(inv.Stderr, "Waiting for devcontainer %q status to change from %q to %q...\n", devcontainer.Name, devcontainer.Status, codersdk.WorkspaceAgentDevcontainerStatusRunning)
+						printedWaiting = true
+					}
+					time.Sleep(5 * time.Second) // Wait a bit before retrying.
+				}
+			}
+
 			if !insideThisWorkspace {
 				// Wait for the agent to connect, we don't care about readiness
 				// otherwise (e.g. wait).
@@ -99,6 +164,9 @@ func (r *RootCmd) openVSCode() *serpent.Command {
 				// the created state, so we need to wait for that to happen.
 				// However, if no directory is set, the expanded directory will
 				// not be set either.
+				//
+				// Note that this is irrelevant for devcontainer sub agents, as
+				// they always have a directory set.
 				if workspaceAgent.Directory != "" {
 					workspace, workspaceAgent, err = waitForAgentCond(ctx, client, workspace, workspaceAgent, func(_ codersdk.WorkspaceAgent) bool {
 						return workspaceAgent.LifecycleState != codersdk.WorkspaceAgentLifecycleCreated
@@ -114,41 +182,6 @@ func (r *RootCmd) openVSCode() *serpent.Command {
 				directory = inv.Args[1]
 			}
 
-			if containerName != "" {
-				containers, err := client.WorkspaceAgentListContainers(ctx, workspaceAgent.ID, map[string]string{"devcontainer.local_folder": ""})
-				if err != nil {
-					return xerrors.Errorf("list workspace agent containers: %w", err)
-				}
-
-				var foundContainer bool
-
-				for _, container := range containers.Containers {
-					if container.FriendlyName != containerName {
-						continue
-					}
-
-					foundContainer = true
-
-					if directory == "" {
-						localFolder, ok := container.Labels["devcontainer.local_folder"]
-						if !ok {
-							return xerrors.New("container missing `devcontainer.local_folder` label")
-						}
-
-						directory, ok = container.Volumes[localFolder]
-						if !ok {
-							return xerrors.New("container missing volume for `devcontainer.local_folder`")
-						}
-					}
-
-					break
-				}
-
-				if !foundContainer {
-					return xerrors.New("no container found")
-				}
-			}
-
 			directory, err = resolveAgentAbsPath(workspaceAgent.ExpandedDirectory, directory, workspaceAgent.OperatingSystem, insideThisWorkspace)
 			if err != nil {
 				return xerrors.Errorf("resolve agent path: %w", err)
@@ -174,14 +207,16 @@ func (r *RootCmd) openVSCode() *serpent.Command {
 				u  *url.URL
 				qp url.Values
 			)
-			if containerName != "" {
+			if devcontainer.ID != uuid.Nil {
 				u, qp = buildVSCodeWorkspaceDevContainerLink(
 					token,
 					client.URL.String(),
 					workspace,
-					workspaceAgent,
-					containerName,
+					parentWorkspaceAgent,
+					devcontainer.Container.FriendlyName,
 					directory,
+					devcontainer.WorkspaceFolder,
+					devcontainer.ConfigPath,
 				)
 			} else {
 				u, qp = buildVSCodeWorkspaceLink(
@@ -247,13 +282,6 @@ func (r *RootCmd) openVSCode() *serpent.Command {
 			),
 			Value: serpent.BoolOf(&generateToken),
 		},
-		{
-			Flag:          "container",
-			FlagShorthand: "c",
-			Description:   "Container name to connect to in the workspace.",
-			Value:         serpent.StringOf(&containerName),
-			Hidden:        true, // Hidden until this features is at least in beta.
-		},
 		{
 			Flag:        "test.open-error",
 			Description: "Don't run the open command.",
@@ -288,7 +316,7 @@ func (r *RootCmd) openApp() *serpent.Command {
 			}
 
 			workspaceName := inv.Args[0]
-			ws, agt, err := getWorkspaceAndAgent(ctx, inv, client, false, workspaceName)
+			ws, agt, _, err := GetWorkspaceAndAgent(ctx, inv, client, false, workspaceName)
 			if err != nil {
 				var sdkErr *codersdk.Error
 				if errors.As(err, &sdkErr) && sdkErr.StatusCode() == http.StatusNotFound {
@@ -430,8 +458,14 @@ func buildVSCodeWorkspaceDevContainerLink(
 	workspaceAgent codersdk.WorkspaceAgent,
 	containerName string,
 	containerFolder string,
+	localWorkspaceFolder string,
+	localConfigFile string,
 ) (*url.URL, url.Values) {
 	containerFolder = filepath.ToSlash(containerFolder)
+	localWorkspaceFolder = filepath.ToSlash(localWorkspaceFolder)
+	if localConfigFile != "" {
+		localConfigFile = filepath.ToSlash(localConfigFile)
+	}
 
 	qp := url.Values{}
 	qp.Add("url", clientURL)
@@ -440,6 +474,8 @@ func buildVSCodeWorkspaceDevContainerLink(
 	qp.Add("agent", workspaceAgent.Name)
 	qp.Add("devContainerName", containerName)
 	qp.Add("devContainerFolder", containerFolder)
+	qp.Add("localWorkspaceFolder", localWorkspaceFolder)
+	qp.Add("localConfigFile", localConfigFile)
 
 	if token != "" {
 		qp.Add("token", token)
@@ -469,7 +505,7 @@ func waitForAgentCond(ctx context.Context, client *codersdk.Client, workspace co
 	}
 
 	for workspace = range wc {
-		workspaceAgent, err = getWorkspaceAgent(workspace, workspaceAgent.Name)
+		workspaceAgent, _, err = getWorkspaceAgent(workspace, workspaceAgent.Name)
 		if err != nil {
 			return workspace, workspaceAgent, xerrors.Errorf("get workspace agent: %w", err)
 		}

cli/open_test.go

@@ -1,8 +1,10 @@
 package cli_test
 
 import (
+	"context"
 	"net/url"
 	"os"
+	"path"
 	"path/filepath"
 	"runtime"
 	"strings"
@@ -11,11 +13,11 @@ import (
 	"github.com/google/uuid"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
-	"go.uber.org/mock/gomock"
+	"golang.org/x/xerrors"
 
 	"github.com/coder/coder/v2/agent"
 	"github.com/coder/coder/v2/agent/agentcontainers"
-	"github.com/coder/coder/v2/agent/agentcontainers/acmock"
+	"github.com/coder/coder/v2/agent/agentcontainers/watcher"
 	"github.com/coder/coder/v2/agent/agenttest"
 	"github.com/coder/coder/v2/cli/clitest"
 	"github.com/coder/coder/v2/coderd/coderdtest"
@@ -289,6 +291,60 @@ func TestOpenVSCode_NoAgentDirectory(t *testing.T) {
 	}
 }
 
+type fakeContainerCLI struct {
+	resp codersdk.WorkspaceAgentListContainersResponse
+}
+
+func (f *fakeContainerCLI) List(ctx context.Context) (codersdk.WorkspaceAgentListContainersResponse, error) {
+	return f.resp, nil
+}
+
+func (*fakeContainerCLI) DetectArchitecture(ctx context.Context, containerID string) (string, error) {
+	return runtime.GOARCH, nil
+}
+
+func (*fakeContainerCLI) Copy(ctx context.Context, containerID, src, dst string) error {
+	return nil
+}
+
+func (*fakeContainerCLI) ExecAs(ctx context.Context, containerID, user string, args ...string) ([]byte, error) {
+	return nil, nil
+}
+
+type fakeDevcontainerCLI struct {
+	config    agentcontainers.DevcontainerConfig
+	execAgent func(ctx context.Context, token string) error
+}
+
+func (f *fakeDevcontainerCLI) ReadConfig(ctx context.Context, workspaceFolder, configFile string, env []string, opts ...agentcontainers.DevcontainerCLIReadConfigOptions) (agentcontainers.DevcontainerConfig, error) {
+	return f.config, nil
+}
+
+func (f *fakeDevcontainerCLI) Exec(ctx context.Context, workspaceFolder, configFile string, name string, args []string, opts ...agentcontainers.DevcontainerCLIExecOptions) error {
+	var opt agentcontainers.DevcontainerCLIExecConfig
+	for _, o := range opts {
+		o(&opt)
+	}
+	var token string
+	for _, arg := range opt.Args {
+		if strings.HasPrefix(arg, "CODER_AGENT_TOKEN=") {
+			token = strings.TrimPrefix(arg, "CODER_AGENT_TOKEN=")
+			break
+		}
+	}
+	if token == "" {
+		return xerrors.New("no agent token provided in args")
+	}
+	if f.execAgent == nil {
+		return nil
+	}
+	return f.execAgent(ctx, token)
+}
+
+func (*fakeDevcontainerCLI) Up(ctx context.Context, workspaceFolder, configFile string, opts ...agentcontainers.DevcontainerCLIUpOptions) (string, error) {
+	return "", nil
+}
+
 func TestOpenVSCodeDevContainer(t *testing.T) {
 	t.Parallel()
 
@@ -296,56 +352,85 @@ func TestOpenVSCodeDevContainer(t *testing.T) {
 		t.Skip("DevContainers are only supported for agents on Linux")
 	}
 
-	agentName := "agent1"
-	agentDir, err := filepath.Abs(filepath.FromSlash("/tmp"))
-	require.NoError(t, err)
+	parentAgentName := "agent1"
 
+	devcontainerID := uuid.New()
+	devcontainerName := "wilson"
+	workspaceFolder := "/home/coder/wilson"
+	configFile := path.Join(workspaceFolder, ".devcontainer", "devcontainer.json")
+
+	containerID := uuid.NewString()
 	containerName := testutil.GetRandomName(t)
-	containerFolder := "/workspace/coder"
-
-	ctrl := gomock.NewController(t)
-	mccli := acmock.NewMockContainerCLI(ctrl)
-	mccli.EXPECT().List(gomock.Any()).Return(
-		codersdk.WorkspaceAgentListContainersResponse{
-			Containers: []codersdk.WorkspaceAgentContainer{
-				{
-					ID:           uuid.NewString(),
-					CreatedAt:    dbtime.Now(),
-					FriendlyName: containerName,
-					Image:        "busybox:latest",
-					Labels: map[string]string{
-						"devcontainer.local_folder": "/home/coder/coder",
-					},
-					Running: true,
-					Status:  "running",
-					Volumes: map[string]string{
-						"/home/coder/coder": containerFolder,
-					},
-				},
-			},
-		}, nil,
-	).AnyTimes()
+	containerFolder := "/workspaces/wilson"
 
 	client, workspace, agentToken := setupWorkspaceForAgent(t, func(agents []*proto.Agent) []*proto.Agent {
-		agents[0].Directory = agentDir
-		agents[0].Name = agentName
+		agents[0].Name = parentAgentName
 		agents[0].OperatingSystem = runtime.GOOS
 		return agents
 	})
 
+	fCCLI := &fakeContainerCLI{
+		resp: codersdk.WorkspaceAgentListContainersResponse{
+			Containers: []codersdk.WorkspaceAgentContainer{
+				{
+					ID:           containerID,
+					CreatedAt:    dbtime.Now(),
+					FriendlyName: containerName,
+					Image:        "busybox:latest",
+					Labels: map[string]string{
+						agentcontainers.DevcontainerLocalFolderLabel: workspaceFolder,
+						agentcontainers.DevcontainerConfigFileLabel:  configFile,
+						agentcontainers.DevcontainerIsTestRunLabel:   "true",
+						"coder.test": t.Name(),
+					},
+					Running: true,
+					Status:  "running",
+				},
+			},
+		},
+	}
+	fDCCLI := &fakeDevcontainerCLI{
+		config: agentcontainers.DevcontainerConfig{
+			Workspace: agentcontainers.DevcontainerWorkspace{
+				WorkspaceFolder: containerFolder,
+			},
+		},
+		execAgent: func(ctx context.Context, token string) error {
+			t.Logf("Starting devcontainer subagent with token: %s", token)
+			_ = agenttest.New(t, client.URL, token)
+			<-ctx.Done()
+			return ctx.Err()
+		},
+	}
+
 	_ = agenttest.New(t, client.URL, agentToken, func(o *agent.Options) {
 		o.Devcontainers = true
 		o.DevcontainerAPIOptions = append(o.DevcontainerAPIOptions,
-			agentcontainers.WithContainerCLI(mccli),
-			agentcontainers.WithContainerLabelIncludeFilter("this.label.does.not.exist.ignore.devcontainers", "true"),
+			agentcontainers.WithProjectDiscovery(false),
+			agentcontainers.WithContainerCLI(fCCLI),
+			agentcontainers.WithDevcontainerCLI(fDCCLI),
+			agentcontainers.WithWatcher(watcher.NewNoop()),
+			agentcontainers.WithDevcontainers(
+				[]codersdk.WorkspaceAgentDevcontainer{{
+					ID:              devcontainerID,
+					Name:            devcontainerName,
+					WorkspaceFolder: workspaceFolder,
+					Status:          codersdk.WorkspaceAgentDevcontainerStatusStopped,
+				}},
+				[]codersdk.WorkspaceAgentScript{{
+					ID:          devcontainerID,
+					LogSourceID: uuid.New(),
+				}},
+			),
+			agentcontainers.WithContainerLabelIncludeFilter("coder.test", t.Name()),
 		)
 	})
-	_ = coderdtest.NewWorkspaceAgentWaiter(t, client, workspace.ID).Wait()
+	coderdtest.NewWorkspaceAgentWaiter(t, client, workspace.ID).AgentNames([]string{parentAgentName, devcontainerName}).Wait()
 
 	insideWorkspaceEnv := map[string]string{
 		"CODER":                      "true",
 		"CODER_WORKSPACE_NAME":       workspace.Name,
-		"CODER_WORKSPACE_AGENT_NAME": agentName,
+		"CODER_WORKSPACE_AGENT_NAME": devcontainerName,
 	}
 
 	wd, err := os.Getwd()
@@ -361,215 +446,47 @@ func TestOpenVSCodeDevContainer(t *testing.T) {
 	}{
 		{
 			name:      "nonexistent container",
-			args:      []string{"--test.open-error", workspace.Name, "--container", containerName + "bad"},
+			args:      []string{"--test.open-error", workspace.Name + "." + devcontainerName + "bad"},
 			wantError: true,
 		},
 		{
 			name:      "ok",
-			args:      []string{"--test.open-error", workspace.Name, "--container", containerName},
-			wantDir:   containerFolder,
+			args:      []string{"--test.open-error", workspace.Name + "." + devcontainerName},
 			wantError: false,
 		},
 		{
 			name:      "ok with absolute path",
-			args:      []string{"--test.open-error", workspace.Name, "--container", containerName, containerFolder},
-			wantDir:   containerFolder,
+			args:      []string{"--test.open-error", workspace.Name + "." + devcontainerName, containerFolder},
 			wantError: false,
 		},
 		{
 			name:      "ok with relative path",
-			args:      []string{"--test.open-error", workspace.Name, "--container", containerName, "my/relative/path"},
-			wantDir:   filepath.Join(agentDir, filepath.FromSlash("my/relative/path")),
+			args:      []string{"--test.open-error", workspace.Name + "." + devcontainerName, "my/relative/path"},
+			wantDir:   path.Join(containerFolder, "my/relative/path"),
 			wantError: false,
 		},
 		{
 			name:      "ok with token",
-			args:      []string{"--test.open-error", workspace.Name, "--container", containerName, "--generate-token"},
-			wantDir:   containerFolder,
+			args:      []string{"--test.open-error", workspace.Name + "." + devcontainerName, "--generate-token"},
 			wantError: false,
 			wantToken: true,
 		},
 		// Inside workspace, does not require --test.open-error
-		{
-			name:    "ok inside workspace",
-			env:     insideWorkspaceEnv,
-			args:    []string{workspace.Name, "--container", containerName},
-			wantDir: containerFolder,
-		},
-		{
-			name:    "ok inside workspace relative path",
-			env:     insideWorkspaceEnv,
-			args:    []string{workspace.Name, "--container", containerName, "foo"},
-			wantDir: filepath.Join(wd, "foo"),
-		},
-		{
-			name:      "ok inside workspace token",
-			env:       insideWorkspaceEnv,
-			args:      []string{workspace.Name, "--container", containerName, "--generate-token"},
-			wantDir:   containerFolder,
-			wantToken: true,
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			t.Parallel()
-
-			inv, root := clitest.New(t, append([]string{"open", "vscode"}, tt.args...)...)
-			clitest.SetupConfig(t, client, root)
-
-			pty := ptytest.New(t)
-			inv.Stdin = pty.Input()
-			inv.Stdout = pty.Output()
-
-			ctx := testutil.Context(t, testutil.WaitLong)
-			inv = inv.WithContext(ctx)
-
-			for k, v := range tt.env {
-				inv.Environ.Set(k, v)
-			}
-
-			w := clitest.StartWithWaiter(t, inv)
-
-			if tt.wantError {
-				w.RequireError()
-				return
-			}
-
-			me, err := client.User(ctx, codersdk.Me)
-			require.NoError(t, err)
-
-			line := pty.ReadLine(ctx)
-			u, err := url.ParseRequestURI(line)
-			require.NoError(t, err, "line: %q", line)
-
-			qp := u.Query()
-			assert.Equal(t, client.URL.String(), qp.Get("url"))
-			assert.Equal(t, me.Username, qp.Get("owner"))
-			assert.Equal(t, workspace.Name, qp.Get("workspace"))
-			assert.Equal(t, agentName, qp.Get("agent"))
-			assert.Equal(t, containerName, qp.Get("devContainerName"))
-
-			if tt.wantDir != "" {
-				assert.Equal(t, tt.wantDir, qp.Get("devContainerFolder"))
-			} else {
-				assert.Equal(t, containerFolder, qp.Get("devContainerFolder"))
-			}
-
-			if tt.wantToken {
-				assert.NotEmpty(t, qp.Get("token"))
-			} else {
-				assert.Empty(t, qp.Get("token"))
-			}
-
-			w.RequireSuccess()
-		})
-	}
-}
-
-func TestOpenVSCodeDevContainer_NoAgentDirectory(t *testing.T) {
-	t.Parallel()
-
-	if runtime.GOOS != "linux" {
-		t.Skip("DevContainers are only supported for agents on Linux")
-	}
-
-	agentName := "agent1"
-
-	containerName := testutil.GetRandomName(t)
-	containerFolder := "/workspace/coder"
-
-	ctrl := gomock.NewController(t)
-	mccli := acmock.NewMockContainerCLI(ctrl)
-	mccli.EXPECT().List(gomock.Any()).Return(
-		codersdk.WorkspaceAgentListContainersResponse{
-			Containers: []codersdk.WorkspaceAgentContainer{
-				{
-					ID:           uuid.NewString(),
-					CreatedAt:    dbtime.Now(),
-					FriendlyName: containerName,
-					Image:        "busybox:latest",
-					Labels: map[string]string{
-						"devcontainer.local_folder": "/home/coder/coder",
-					},
-					Running: true,
-					Status:  "running",
-					Volumes: map[string]string{
-						"/home/coder/coder": containerFolder,
-					},
-				},
-			},
-		}, nil,
-	).AnyTimes()
-
-	client, workspace, agentToken := setupWorkspaceForAgent(t, func(agents []*proto.Agent) []*proto.Agent {
-		agents[0].Name = agentName
-		agents[0].OperatingSystem = runtime.GOOS
-		return agents
-	})
-
-	_ = agenttest.New(t, client.URL, agentToken, func(o *agent.Options) {
-		o.Devcontainers = true
-		o.DevcontainerAPIOptions = append(o.DevcontainerAPIOptions,
-			agentcontainers.WithContainerCLI(mccli),
-			agentcontainers.WithContainerLabelIncludeFilter("this.label.does.not.exist.ignore.devcontainers", "true"),
-		)
-	})
-	_ = coderdtest.NewWorkspaceAgentWaiter(t, client, workspace.ID).Wait()
-
-	insideWorkspaceEnv := map[string]string{
-		"CODER":                      "true",
-		"CODER_WORKSPACE_NAME":       workspace.Name,
-		"CODER_WORKSPACE_AGENT_NAME": agentName,
-	}
-
-	wd, err := os.Getwd()
-	require.NoError(t, err)
-
-	tests := []struct {
-		name      string
-		env       map[string]string
-		args      []string
-		wantDir   string
-		wantError bool
-		wantToken bool
-	}{
-		{
-			name: "ok",
-			args: []string{"--test.open-error", workspace.Name, "--container", containerName},
-		},
-		{
-			name:      "no agent dir error relative path",
-			args:      []string{"--test.open-error", workspace.Name, "--container", containerName, "my/relative/path"},
-			wantDir:   filepath.FromSlash("my/relative/path"),
-			wantError: true,
-		},
-		{
-			name:    "ok with absolute path",
-			args:    []string{"--test.open-error", workspace.Name, "--container", containerName, "/home/coder"},
-			wantDir: "/home/coder",
-		},
-		{
-			name:      "ok with token",
-			args:      []string{"--test.open-error", workspace.Name, "--container", containerName, "--generate-token"},
-			wantToken: true,
-		},
-		// Inside workspace, does not require --test.open-error
 		{
 			name: "ok inside workspace",
 			env:  insideWorkspaceEnv,
-			args: []string{workspace.Name, "--container", containerName},
+			args: []string{workspace.Name + "." + devcontainerName},
 		},
 		{
 			name:    "ok inside workspace relative path",
 			env:     insideWorkspaceEnv,
-			args:    []string{workspace.Name, "--container", containerName, "foo"},
+			args:    []string{workspace.Name + "." + devcontainerName, "foo"},
 			wantDir: filepath.Join(wd, "foo"),
 		},
 		{
 			name:      "ok inside workspace token",
 			env:       insideWorkspaceEnv,
-			args:      []string{workspace.Name, "--container", containerName, "--generate-token"},
+			args:      []string{workspace.Name + "." + devcontainerName, "--generate-token"},
 			wantToken: true,
 		},
 	}
@@ -610,8 +527,10 @@ func TestOpenVSCodeDevContainer_NoAgentDirectory(t *testing.T) {
 			assert.Equal(t, client.URL.String(), qp.Get("url"))
 			assert.Equal(t, me.Username, qp.Get("owner"))
 			assert.Equal(t, workspace.Name, qp.Get("workspace"))
-			assert.Equal(t, agentName, qp.Get("agent"))
+			assert.Equal(t, parentAgentName, qp.Get("agent"))
 			assert.Equal(t, containerName, qp.Get("devContainerName"))
+			assert.Equal(t, workspaceFolder, qp.Get("localWorkspaceFolder"))
+			assert.Equal(t, configFile, qp.Get("localConfigFile"))
 
 			if tt.wantDir != "" {
 				assert.Equal(t, tt.wantDir, qp.Get("devContainerFolder"))

cli/organizationroles.go

@@ -435,7 +435,6 @@ func applyOrgResourceActions(role *codersdk.Role, resource string, actions []str
 	// Construct new site perms with only new perms for the resource
 	keep := make([]codersdk.Permission, 0)
 	for _, perm := range role.OrganizationPermissions {
-		perm := perm
 		if string(perm.ResourceType) != resource {
 			keep = append(keep, perm)
 		}

cli/organizationsettings.go

@@ -116,7 +116,6 @@ func (r *RootCmd) setOrganizationSettings(orgContext *OrganizationContext, setti
 	}
 
 	for _, set := range settings {
-		set := set
 		patch := set.Patch
 		cmd.Children = append(cmd.Children, &serpent.Command{
 			Use:     set.Name,
@@ -192,7 +191,6 @@ func (r *RootCmd) printOrganizationSetting(orgContext *OrganizationContext, sett
 	}
 
 	for _, set := range settings {
-		set := set
 		fetch := set.Fetch
 		cmd.Children = append(cmd.Children, &serpent.Command{
 			Use:     set.Name,