GitVita
New repositoryImport repositoryNew issue
Your repositories Your dashboard Sign in

microsoft/TypeAgent

Public

mirrored from https://github.com/microsoft/TypeAgentAvailable

Watch0Fork0Star0
CodeCommitsIssuesPull requestsActionsInsightsSecurity
container

Branches

Tags

  • No tags available.
0Branches0Tags
Go to file
Add file
Code

Clone

HTTPS

Download ZIP

TypeAgent/.devcontainer

.devcontainer/README.md

325lines · modeblame

RawDownload
Latest commit unavailable.
ecec6489Hillary Mutisya1 months ago1# TypeAgent Development Container
2
3This devcontainer provides a fully configured development environment for TypeAgent with all required tools and dependencies.
4
5## Prerequisites
6
7### Windows
47fe4603Curtis Man1 months ago8
ecec6489Hillary Mutisya1 months ago9- **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
47fe4603Curtis Man1 months ago14
ecec6489Hillary Mutisya1 months ago15- **Docker Desktop** or Docker Engine
16- **VS Code** with the Dev Containers extension
17
18### GitHub Codespaces
47fe4603Curtis Man1 months ago19
ecec6489Hillary Mutisya1 months ago20No local prerequisites - works directly in browser or VS Code.
21
22## Quick Start
23
241. Open the TypeAgent folder in VS Code
252. When prompted "Reopen in Container", click **Reopen in Container**
26- Or use Command Palette: `Dev Containers: Reopen in Container`
273. Wait for the container to build (first time takes 5-10 minutes)
284. Once ready, open a terminal and run:
29```bash
30cd ts
31pnpm run build
32```
33
34## Container Configurations
35
36### Standard (`devcontainer.json`)
47fe4603Curtis Man1 months ago37
ecec6489Hillary Mutisya1 months ago38Default configuration for most development work. Includes:
47fe4603Curtis Man1 months ago39
ecec6489Hillary Mutisya1 months ago40- Node.js 22, Python 3.12, .NET 8.0
41- pnpm package manager
42- Azure CLI, GitHub CLI
43- Claude Code
44
8043ab38Curtis Man1 months ago45**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:
47fe4603Curtis Man1 months ago46
ecec6489Hillary Mutisya1 months ago47```bash
48# In container - start the backend
49pnpm run server
50
51# On host machine - run the Electron shell
52cd ts && pnpm run shell
53```
54
55## Working with the Container
56
8043ab38Curtis Man1 months ago57### SSH Access
58
59The universal devcontainer image includes an SSH server. To set up key-based
60access from your host machine, run:
61
62```bash
63.devcontainer/scripts/setup-ssh-access.sh
64```
65
66The 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
79By default, generated SSH config uses `StrictHostKeyChecking accept-new`.
80For local-only workflows where you intentionally want host key checks disabled,
81use:
82
83```bash
84.devcontainer/scripts/setup-ssh-access.sh --insecure-local
85```
86
87After it completes, connect with:
88
89```bash
90ssh typeagent-devcontainer
91```
92
93If 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
101Use this wrapper to start the devcontainer from the command line. If your
102VS Code agent window only supports tunnel/SSH connections, pass `--ssh` to
103also 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
110Useful options:
111
112```bash
113# Recreate container first
b2831ffdCurtis Man1 months ago114.devcontainer/scripts/start-devcontainer.sh --recreate --ssh
115
ff079d12Curtis Man1 months ago116# Rebuild the devcontainer image (implies --recreate)
b2831ffdCurtis Man1 months ago117.devcontainer/scripts/start-devcontainer.sh --rebuild
8043ab38Curtis Man1 months ago118
ff079d12Curtis Man1 months ago119# 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
8043ab38Curtis Man1 months ago125# 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
132After it completes with `--ssh`:
133
134```bash
135ssh typeagent-devcontainer
136```
137
ecec6489Hillary Mutisya1 months ago138### Common Commands
47fe4603Curtis Man1 months ago139
ecec6489Hillary Mutisya1 months ago140```bash
141cd ts # Navigate to TypeScript workspace
142pnpm run build # Build all packages
143pnpm run cli # Run the CLI
144pnpm run test:local # Run unit tests
16041f85Hillary Mutisya1 months ago145pnpm run start:agent-server # Start agent server
ecec6489Hillary Mutisya1 months ago146```
147
8043ab38Curtis Man1 months ago148### Git Configuration
149
150During container creation, the post-create script keeps any existing container
151Git identity, or sets `user.name` and `user.email` from the
152`LOCAL_GIT_USER_NAME` and `LOCAL_GIT_USER_EMAIL` environment variables when
153those values are provided. The devcontainer configs pass those host-side
154environment variables through with `${localEnv:...}`, and the
155`start-devcontainer.sh` wrapper fills them from your host `~/.gitconfig`
156using `git config --global` before calling `devcontainer up`.
157
158After rebuilding the container, you can verify with:
159
160```bash
161git config --global --list
162git config user.name
163git config user.email
164```
165
ecec6489Hillary Mutisya1 months ago166## Using with AI Agents
167
168### Claude Code
47fe4603Curtis Man1 months ago169
ecec6489Hillary Mutisya1 months ago170Claude Code is pre-installed in the container:
47fe4603Curtis Man1 months ago171
ecec6489Hillary Mutisya1 months ago172```bash
173claude # Start interactive session
174claude "your prompt" # Run with a prompt
175```
176
177### Parallel Agent Development with Worktrees
47fe4603Curtis Man1 months ago178
ecec6489Hillary Mutisya1 months ago179Run 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
193Each worktree shares the git history but has independent:
47fe4603Curtis Man1 months ago194
ecec6489Hillary Mutisya1 months ago195- Working directory and file changes
196- Node modules (via pnpm's content-addressable store)
197- Branch state
198
199## Forwarded Ports
200
8043ab38Curtis Man1 months ago201Standard 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
212VNC config (`vnc/devcontainer.json`) adds:
213
214| Port | Service |
215| ---- | ----------------- |
216| 6080 | noVNC Web Desktop |
217| 5901 | VNC Client |
218
219## Container User
220
221The container runs as `codespace` with UID/GID 1001 (matches the Codespaces
222convention and the previous universal base image). All workspace and cache
223paths are accessed via Docker named volumes, not host bind mounts of source
224files, so this UID does not need to match your host user. If you add a host
225bind mount later and your host user shares UID 1001, be aware of the implicit
226file-ownership overlap.
ecec6489Hillary Mutisya1 months ago227
228## Troubleshooting
229
230### Container fails to start
47fe4603Curtis Man1 months ago231
ecec6489Hillary Mutisya1 months ago2321. Ensure Docker Desktop is running
2332. Try rebuilding: `Dev Containers: Rebuild Container`
2343. Check Docker has sufficient resources (4 CPU, 8GB RAM minimum)
235
236### pnpm install fails
47fe4603Curtis Man1 months ago237
ecec6489Hillary Mutisya1 months ago238```bash
239# Clear pnpm cache and retry
240pnpm store prune
241pnpm install
242```
243
47fe4603Curtis Man1 months ago244### `EACCES` / permission denied on `ts/node_modules` during `pnpm install`
245
246The devcontainer mounts a Docker named volume at `ts/node_modules` (and at the pnpm
247global store). Docker creates these mount points owned by `root:root`, but the
248container runs as the non-root `codespace` user, which causes `pnpm install` to
249fail with permission errors on a fresh container.
250
251The `post-create.sh` script automatically `chown`s these paths to `codespace`
252on first launch. If you hit this manually, run:
253
254```bash
255sudo chown -R codespace:codespace \
256/workspaces/TypeAgent/ts/node_modules \
257/home/codespace/.local/share/pnpm \
258/home/codespace/.claude
259cd /workspaces/TypeAgent/ts && pnpm install
260```
261
ecec6489Hillary Mutisya1 months ago262### Permission errors
47fe4603Curtis Man1 months ago263
ecec6489Hillary Mutisya1 months ago264The container runs as the `codespace` user. If you encounter permission issues:
47fe4603Curtis Man1 months ago265
ecec6489Hillary Mutisya1 months ago266```bash
267sudo chown -R codespace:codespace /workspaces/TypeAgent
268```
269
8043ab38Curtis Man1 months ago270### Agent window cannot create `/workspaces/*.worktrees` (access denied)
271
272Agent windows may create sibling worktree folders such as
273`/workspaces/TypeAgent3.worktrees`.
274If this path is root-owned, worktree creation fails with access denied.
275
276Run:
277
278```bash
279sudo mkdir -p /workspaces/TypeAgent3.worktrees
280sudo chown codespace:codespace /workspaces/TypeAgent3.worktrees
281```
282
283Then retry creating the worktree.
284
285This is also handled automatically on fresh container creation by
286`.devcontainer/scripts/post-create.sh`.
287
288The standard and VNC devcontainer configs now mount a dedicated Docker
289named volume at `/workspaces/<repo>.worktrees` so agent-window worktrees
290have a stable writable location across container restarts and rebuilds.
291
ecec6489Hillary Mutisya1 months ago292### Line ending issues (Windows)
47fe4603Curtis Man1 months ago293
ecec6489Hillary Mutisya1 months ago294If scripts fail with `\r': command not found`, the repository may have CRLF line endings. Fix with:
47fe4603Curtis Man1 months ago295
ecec6489Hillary Mutisya1 months ago296```bash
297git config core.autocrlf input
298git rm --cached -r .
299git reset --hard
300```
301
302## Rebuilding the Container
303
304To rebuild with fresh state:
47fe4603Curtis Man1 months ago305
ecec6489Hillary Mutisya1 months ago3061. Command Palette: `Dev Containers: Rebuild Container`
ff079d12Curtis Man1 months ago3072. Or from the CLI: `.devcontainer/scripts/start-devcontainer.sh --rebuild`
ecec6489Hillary Mutisya1 months ago308
ff079d12Curtis Man1 months ago309To rebuild without cache and clean volumes:
47fe4603Curtis Man1 months ago310
ecec6489Hillary Mutisya1 months ago3111. Command Palette: `Dev Containers: Rebuild Container Without Cache`
ff079d12Curtis Man1 months ago3122. Or from the CLI: `.devcontainer/scripts/start-devcontainer.sh --reset`
313
314## Container Image
315
316The devcontainer uses a custom Dockerfile (`.devcontainer/Dockerfile`) that
317extends the base Ubuntu 24.04 image with pre-installed system libraries
318(libsecret). This avoids running `apt-get install` on every container
319creation and leverages Docker's layer cache for fast rebuilds.
ecec6489Hillary Mutisya1 months ago320
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)