microsoft/TypeAgent
Publicmirrored fromhttps://github.com/microsoft/TypeAgentAvailable
.devcontainer/README.md
325lines · modecode
| 1 | # TypeAgent Development Container |
| 2 | |
| 3 | This devcontainer provides a fully configured development environment for TypeAgent with all required tools and dependencies. |
| 4 | |
| 5 | ## Prerequisites |
| 6 | |
| 7 | ### Windows |
| 8 | |
| 9 | - **Docker Desktop** with WSL 2 backend enabled |
| 10 | - **VS Code** with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) |
| 11 | - Recommended: Run `ts/tools/scripts/setup-devcontainer.ps1` to verify prerequisites |
| 12 | |
| 13 | ### macOS / Linux |
| 14 | |
| 15 | - **Docker Desktop** or Docker Engine |
| 16 | - **VS Code** with the Dev Containers extension |
| 17 | |
| 18 | ### GitHub Codespaces |
| 19 | |
| 20 | No local prerequisites - works directly in browser or VS Code. |
| 21 | |
| 22 | ## Quick Start |
| 23 | |
| 24 | 1. Open the TypeAgent folder in VS Code |
| 25 | 2. When prompted "Reopen in Container", click **Reopen in Container** |
| 26 | - Or use Command Palette: `Dev Containers: Reopen in Container` |
| 27 | 3. Wait for the container to build (first time takes 5-10 minutes) |
| 28 | 4. Once ready, open a terminal and run: |
| 29 | ```bash |
| 30 | cd ts |
| 31 | pnpm run build |
| 32 | ``` |
| 33 | |
| 34 | ## Container Configurations |
| 35 | |
| 36 | ### Standard (`devcontainer.json`) |
| 37 | |
| 38 | Default configuration for most development work. Includes: |
| 39 | |
| 40 | - Node.js 22, Python 3.12, .NET 8.0 |
| 41 | - pnpm package manager |
| 42 | - Azure CLI, GitHub CLI |
| 43 | - Claude Code |
| 44 | |
| 45 | **Note:** The Electron shell requires GUI support. To use the shell with devcontainer, you need to start the agent-server in the container and run the shell on your host machine. The agent server port is forwarded to the host, so the shell will connect correctly: |
| 46 | |
| 47 | ```bash |
| 48 | # In container - start the backend |
| 49 | pnpm run server |
| 50 | |
| 51 | # On host machine - run the Electron shell |
| 52 | cd ts && pnpm run shell |
| 53 | ``` |
| 54 | |
| 55 | ## Working with the Container |
| 56 | |
| 57 | ### SSH Access |
| 58 | |
| 59 | The universal devcontainer image includes an SSH server. To set up key-based |
| 60 | access from your host machine, run: |
| 61 | |
| 62 | ```bash |
| 63 | .devcontainer/scripts/setup-ssh-access.sh |
| 64 | ``` |
| 65 | |
| 66 | The script will: |
| 67 | |
| 68 | - create `~/.ssh/typeagent-devcontainer` if it does not already exist |
| 69 | - find the running TypeAgent devcontainer from Docker labels |
| 70 | - add the public key to `~/.ssh/authorized_keys` for the `codespace` user in the container |
| 71 | - add or update an SSH config entry named `typeagent-devcontainer` |
| 72 | - enforce key-only SSH auth in both client config and container sshd settings |
| 73 | - use `StrictHostKeyChecking accept-new` by default |
| 74 | - when run in WSL, also detect your Windows `%USERPROFILE%/.ssh` directory |
| 75 | - copy the same keypair into Windows `~/.ssh` so Windows OpenSSH can use it directly |
| 76 | - add or update the same `typeagent-devcontainer` host entry in Windows SSH config |
| 77 | - use Windows-native paths for the copied key and `known_hosts` entry in that Windows config |
| 78 | |
| 79 | By default, generated SSH config uses `StrictHostKeyChecking accept-new`. |
| 80 | For local-only workflows where you intentionally want host key checks disabled, |
| 81 | use: |
| 82 | |
| 83 | ```bash |
| 84 | .devcontainer/scripts/setup-ssh-access.sh --insecure-local |
| 85 | ``` |
| 86 | |
| 87 | After it completes, connect with: |
| 88 | |
| 89 | ```bash |
| 90 | ssh typeagent-devcontainer |
| 91 | ``` |
| 92 | |
| 93 | If you use a non-default devcontainer config, pass it explicitly: |
| 94 | |
| 95 | ```bash |
| 96 | .devcontainer/scripts/setup-ssh-access.sh --config .devcontainer/vnc/devcontainer.json |
| 97 | ``` |
| 98 | |
| 99 | ### One-Command Start (and Optional SSH Setup) |
| 100 | |
| 101 | Use this wrapper to start the devcontainer from the command line. If your |
| 102 | VS Code agent window only supports tunnel/SSH connections, pass `--ssh` to |
| 103 | also configure host SSH access in the same step: |
| 104 | |
| 105 | ```bash |
| 106 | .devcontainer/scripts/start-devcontainer.sh # start only |
| 107 | .devcontainer/scripts/start-devcontainer.sh --ssh # start + configure SSH |
| 108 | ``` |
| 109 | |
| 110 | Useful options: |
| 111 | |
| 112 | ```bash |
| 113 | # Recreate container first |
| 114 | .devcontainer/scripts/start-devcontainer.sh --recreate --ssh |
| 115 | |
| 116 | # Rebuild the devcontainer image (implies --recreate) |
| 117 | .devcontainer/scripts/start-devcontainer.sh --rebuild |
| 118 | |
| 119 | # Remove container and associated Docker volumes |
| 120 | .devcontainer/scripts/start-devcontainer.sh --clean |
| 121 | |
| 122 | # Full reset: rebuild image + clean volumes |
| 123 | .devcontainer/scripts/start-devcontainer.sh --reset |
| 124 | |
| 125 | # Use alternate devcontainer config |
| 126 | .devcontainer/scripts/start-devcontainer.sh --config .devcontainer/vnc/devcontainer.json |
| 127 | |
| 128 | # Local-only mode with host key checks disabled (implies --ssh) |
| 129 | .devcontainer/scripts/start-devcontainer.sh --insecure-local |
| 130 | ``` |
| 131 | |
| 132 | After it completes with `--ssh`: |
| 133 | |
| 134 | ```bash |
| 135 | ssh typeagent-devcontainer |
| 136 | ``` |
| 137 | |
| 138 | ### Common Commands |
| 139 | |
| 140 | ```bash |
| 141 | cd ts # Navigate to TypeScript workspace |
| 142 | pnpm run build # Build all packages |
| 143 | pnpm run cli # Run the CLI |
| 144 | pnpm run test:local # Run unit tests |
| 145 | pnpm run start:agent-server # Start agent server |
| 146 | ``` |
| 147 | |
| 148 | ### Git Configuration |
| 149 | |
| 150 | During container creation, the post-create script keeps any existing container |
| 151 | Git identity, or sets `user.name` and `user.email` from the |
| 152 | `LOCAL_GIT_USER_NAME` and `LOCAL_GIT_USER_EMAIL` environment variables when |
| 153 | those values are provided. The devcontainer configs pass those host-side |
| 154 | environment variables through with `${localEnv:...}`, and the |
| 155 | `start-devcontainer.sh` wrapper fills them from your host `~/.gitconfig` |
| 156 | using `git config --global` before calling `devcontainer up`. |
| 157 | |
| 158 | After rebuilding the container, you can verify with: |
| 159 | |
| 160 | ```bash |
| 161 | git config --global --list |
| 162 | git config user.name |
| 163 | git config user.email |
| 164 | ``` |
| 165 | |
| 166 | ## Using with AI Agents |
| 167 | |
| 168 | ### Claude Code |
| 169 | |
| 170 | Claude Code is pre-installed in the container: |
| 171 | |
| 172 | ```bash |
| 173 | claude # Start interactive session |
| 174 | claude "your prompt" # Run with a prompt |
| 175 | ``` |
| 176 | |
| 177 | ### Parallel Agent Development with Worktrees |
| 178 | |
| 179 | Run multiple AI agents in parallel using git worktrees: |
| 180 | |
| 181 | ```bash |
| 182 | # Create a worktree for an agent |
| 183 | ../scripts/agent-worktree.sh feature-name |
| 184 | |
| 185 | # This creates: |
| 186 | # ../agent-feature-name/ - isolated working directory |
| 187 | # ../agent-feature-name/ts/ - TypeScript workspace |
| 188 | |
| 189 | # Clean up when done |
| 190 | ../scripts/agent-worktree.sh --cleanup feature-name |
| 191 | ``` |
| 192 | |
| 193 | Each worktree shares the git history but has independent: |
| 194 | |
| 195 | - Working directory and file changes |
| 196 | - Node modules (via pnpm's content-addressable store) |
| 197 | - Branch state |
| 198 | |
| 199 | ## Forwarded Ports |
| 200 | |
| 201 | Standard config (`devcontainer.json`): |
| 202 | |
| 203 | | Port | Service | |
| 204 | | ---- | ----------------------------------------------- | |
| 205 | | 2222 | Dev Container SSH (host-published on 127.0.0.1) | |
| 206 | | 3000 | API Server (HTTP) | |
| 207 | | 3443 | API Server (HTTPS) | |
| 208 | | 8999 | Agent Server (WebSocket) | |
| 209 | | 8081 | Browser Agent (WebSocket) | |
| 210 | | 8082 | Code Agent (WebSocket) | |
| 211 | |
| 212 | VNC config (`vnc/devcontainer.json`) adds: |
| 213 | |
| 214 | | Port | Service | |
| 215 | | ---- | ----------------- | |
| 216 | | 6080 | noVNC Web Desktop | |
| 217 | | 5901 | VNC Client | |
| 218 | |
| 219 | ## Container User |
| 220 | |
| 221 | The container runs as `codespace` with UID/GID 1001 (matches the Codespaces |
| 222 | convention and the previous universal base image). All workspace and cache |
| 223 | paths are accessed via Docker named volumes, not host bind mounts of source |
| 224 | files, so this UID does not need to match your host user. If you add a host |
| 225 | bind mount later and your host user shares UID 1001, be aware of the implicit |
| 226 | file-ownership overlap. |
| 227 | |
| 228 | ## Troubleshooting |
| 229 | |
| 230 | ### Container fails to start |
| 231 | |
| 232 | 1. Ensure Docker Desktop is running |
| 233 | 2. Try rebuilding: `Dev Containers: Rebuild Container` |
| 234 | 3. Check Docker has sufficient resources (4 CPU, 8GB RAM minimum) |
| 235 | |
| 236 | ### pnpm install fails |
| 237 | |
| 238 | ```bash |
| 239 | # Clear pnpm cache and retry |
| 240 | pnpm store prune |
| 241 | pnpm install |
| 242 | ``` |
| 243 | |
| 244 | ### `EACCES` / permission denied on `ts/node_modules` during `pnpm install` |
| 245 | |
| 246 | The devcontainer mounts a Docker named volume at `ts/node_modules` (and at the pnpm |
| 247 | global store). Docker creates these mount points owned by `root:root`, but the |
| 248 | container runs as the non-root `codespace` user, which causes `pnpm install` to |
| 249 | fail with permission errors on a fresh container. |
| 250 | |
| 251 | The `post-create.sh` script automatically `chown`s these paths to `codespace` |
| 252 | on first launch. If you hit this manually, run: |
| 253 | |
| 254 | ```bash |
| 255 | sudo chown -R codespace:codespace \ |
| 256 | /workspaces/TypeAgent/ts/node_modules \ |
| 257 | /home/codespace/.local/share/pnpm \ |
| 258 | /home/codespace/.claude |
| 259 | cd /workspaces/TypeAgent/ts && pnpm install |
| 260 | ``` |
| 261 | |
| 262 | ### Permission errors |
| 263 | |
| 264 | The container runs as the `codespace` user. If you encounter permission issues: |
| 265 | |
| 266 | ```bash |
| 267 | sudo chown -R codespace:codespace /workspaces/TypeAgent |
| 268 | ``` |
| 269 | |
| 270 | ### Agent window cannot create `/workspaces/*.worktrees` (access denied) |
| 271 | |
| 272 | Agent windows may create sibling worktree folders such as |
| 273 | `/workspaces/TypeAgent3.worktrees`. |
| 274 | If this path is root-owned, worktree creation fails with access denied. |
| 275 | |
| 276 | Run: |
| 277 | |
| 278 | ```bash |
| 279 | sudo mkdir -p /workspaces/TypeAgent3.worktrees |
| 280 | sudo chown codespace:codespace /workspaces/TypeAgent3.worktrees |
| 281 | ``` |
| 282 | |
| 283 | Then retry creating the worktree. |
| 284 | |
| 285 | This is also handled automatically on fresh container creation by |
| 286 | `.devcontainer/scripts/post-create.sh`. |
| 287 | |
| 288 | The standard and VNC devcontainer configs now mount a dedicated Docker |
| 289 | named volume at `/workspaces/<repo>.worktrees` so agent-window worktrees |
| 290 | have a stable writable location across container restarts and rebuilds. |
| 291 | |
| 292 | ### Line ending issues (Windows) |
| 293 | |
| 294 | If scripts fail with `\r': command not found`, the repository may have CRLF line endings. Fix with: |
| 295 | |
| 296 | ```bash |
| 297 | git config core.autocrlf input |
| 298 | git rm --cached -r . |
| 299 | git reset --hard |
| 300 | ``` |
| 301 | |
| 302 | ## Rebuilding the Container |
| 303 | |
| 304 | To rebuild with fresh state: |
| 305 | |
| 306 | 1. Command Palette: `Dev Containers: Rebuild Container` |
| 307 | 2. Or from the CLI: `.devcontainer/scripts/start-devcontainer.sh --rebuild` |
| 308 | |
| 309 | To rebuild without cache and clean volumes: |
| 310 | |
| 311 | 1. Command Palette: `Dev Containers: Rebuild Container Without Cache` |
| 312 | 2. Or from the CLI: `.devcontainer/scripts/start-devcontainer.sh --reset` |
| 313 | |
| 314 | ## Container Image |
| 315 | |
| 316 | The devcontainer uses a custom Dockerfile (`.devcontainer/Dockerfile`) that |
| 317 | extends the base Ubuntu 24.04 image with pre-installed system libraries |
| 318 | (libsecret). This avoids running `apt-get install` on every container |
| 319 | creation and leverages Docker's layer cache for fast rebuilds. |
| 320 | |
| 321 | ## Resources |
| 322 | |
| 323 | - [VS Code Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers) |
| 324 | - [GitHub Codespaces](https://docs.github.com/en/codespaces) |
| 325 | - [TypeAgent Documentation](../ts/README.md) |
| 326 | |