DevSpace: ChatGPT MCP Setup for Local Development

01Tool overview

ChatGPT access to local machines

DevSpace is a TypeScript MCP (Model Context Protocol) server published as npm package @waishnav/devspace. It addresses ChatGPT's inability to access your local development environment by starting a local service on your machine (default http://127.0.0.1:7676); connect it to ChatGPT through an HTTPS channel you control. ChatGPT can operate local projects without uploading files to third parties.

After connecting, ChatGPT can read, write and edit files, search code, inspect directories and run shell commands for tests, builds, git and package scripts; it can also run parallel sessions in isolated Git worktrees. It reads the project root's AGENTS.md and CLAUDE.md as instructions and automatically discovers local skills in your skill folders. The project describes its role as turning ChatGPT into Codex while using ChatGPT usage separately.

You control the access scope and channel. You choose accessible folders (roots), host the channel and store the Owner password locally in ~/.devspace/auth.json. File tools have path boundaries, but shell commands run with your user permissions; confirm their scope during setup.

init
serve
Tunnel
ChatGPT connector
Owner password approval
open_workspace

Your files, tools and terminal are not uploaded to any third party. You run it on your own machine and expose it through a tunnel you control.

— DevSpace README, project scope · Translated from Chinese

02Installation and startup

npm installation and three management commands

Requirements: Node.js >=20.12 <27 (Node 22 LTS is officially recommended), npm, Git and a Bash-compatible shell. After global installation, use init for setup, serve to start and doctor to check the environment.

# Install globally
npm install -g @waishnav/devspace

# Interactive setup: choose accessible folders, the local port and the public HTTPS URL
devspace init

# Start the MCP server(default http://127.0.0.1:7676/mcp)
devspace serve

# Check local environment compatibility
devspace doctor

npx installation

If you prefer not to install globally, or devspace is missing from PATH, run any command with npx:

npx @waishnav/devspace init
npx @waishnav/devspace serve
npx @waishnav/devspace doctor

038 MCP tools

Local MCP tools for ChatGPT

DevSpace exposes local development through eight MCP tools called explicitly by ChatGPT; start with open_workspace, which returns a workspaceId; reuse that ID for every subsequent operation. File tools (read / edit / write) have path boundaries and may access only roots allowed during init; bash runs shell commands. Official guidance recommends edit / write for file changes instead of shell sed -i, heredocs or redirection with tee.

Session · 01

open_workspace

Open a workspace

Specify a local project or worktree path to receive workspaceId. Call once per project and reuse the ID in later tools. Loads root AGENTS.md / CLAUDE.md.

File · 02

read

Read files

Read workspace files. Nested instruction files appear in availableAgentsFiles, prompting the model to read them before changing that directory.

File · 03

edit

Targeted editing

Make precise, scoped file changes. Official guidance uses edit/write instead of shell sed -i, heredocs or redirection.

File · 04

write

Write files

Create or overwrite whole files. Like edit, it has path boundaries and writes only within roots allowed during init.

Search · 05

ls

Inspect directories

List directory contents and project structure. Maps to internal list_directory so ChatGPT can inspect the layout before editing.

Search · 06

find

Locate files

Locate files by name or pattern (internal find_files), quickly narrowing the reading scope in large repos.

Search · 07

grep

Search code

Search strings or patterns within the workspace (internal grep_files) to locate symbols, usage and cross-file relationships.

Exec · 08

bash

Run Shell

Run tests, builds, git and package scripts with your user permissions. Confirm its permission scope. Requires a Bash-compatible shell.

Four public HTTPS channels

DevSpace listens only on local 127.0.0.1:7676; external access requires your own reverse proxy. The official documentation lists four choices. Enter the origin without /mcp in settings, then append /mcp in the ChatGPT connector.

Channel	Characteristics	Suitable use
`Cloudflare Tunnel`	Can add Cloudflare Access for another access-control layer	Long-term use with a stable domain
`Tailscale Funnel`	Uses your tailnet with a stable domain	Individuals / teams already using Tailscale
`ngrok` / `Pinggy`	Fastest startup; temporary URLs often change between runs	Quick trials and temporary connections
Changing URLs	Override with `DEVSPACE_PUBLIC_BASE_URL` or `devspace config set publicBaseUrl https://...`

04Setup and usage · Official documentation

Eight setup points

These points come from the official DevSpace setup.md, security.md and gotchas.md. Most connection failures involve recurring issues with Node versions, native dependencies, public URL formats and host-header allowlists.

Node versions 20.12 to 26

DevSpace requires Node >=20.12 <27; Node 22 LTS is officially recommended. An incompatible version prevents startup. Use nvm, fnm or mise to switch to 22 LTS.

Source · Official gotchas.md

Enter the public origin without /mcp

Enter https://your-tunnel.example.com (origin) during init and append /mcp only in the ChatGPT connector. An incorrect path is the most common cause of connection failures.

Source · Official setup.md

Rebuild if better-sqlite3 fails to load

Native dependencies may fail to load when installed under a different Node runtime. Run npm rebuild better-sqlite3, then devspace doctor to verify.

Source · Official gotchas.md

Override temporary channel URLs with an environment variable

Temporary ngrok / Pinggy URLs often change after restart. Run DEVSPACE_PUBLIC_BASE_URL="https://new.example.com" devspace serve without editing the config file.

Source · Official setup.md / gotchas.md

Run doctor for 403 / host-header errors

DevSpace derives allowed hosts from the public URL. For 403 errors, check the hostname with devspace doctor. Use DEVSPACE_ALLOWED_HOSTS="*" only for local debugging, not long-term operation.

Source · Official gotchas.md / security.md

Narrow roots improve safety

Official guidance recommends narrow folders such as ~/work or ~/personal/open-source, avoiding ~, / and C:\. Narrower roots make the accessible scope easier to determine.

Source · Official security.md

Worktree mode for parallel tasks

Pass "mode": "worktree" to open_workspace for isolated parallel development under ~/.devspace/worktrees. Requires a Git repo with at least one commit; uncommitted changes are not copied.

Source · Official chatgpt-coding-workflow.md

Use file tools instead of shell redirection

Official instructions require edit / write for file changes, not sed -i, heredocs, tee or generated scripts. Reserve shell for terminal commands such as tests, builds and git.

Source · Official chatgpt-coding-workflow.md

05Worked example

Local code repair workflow

Start DevSpace locally, expose a public URL through Cloudflare Tunnel, paste the /mcp endpoint into the ChatGPT connector and approve with the Owner password. Ask ChatGPT to open a workspace, locate a bug, fix it with edit and verify through bash tests. Commands and tool names come from the official documentation.



# 1 · Start DevSpace locally
$ devspace serve
  ok: DevSpace MCP listening on http://127.0.0.1:7676/mcp
  # roots: ~/work  ·  owner password: ~/.devspace/auth.json


# 2 · Open another terminal and create a public HTTPS tunnel(pointing to the local port)
$ cloudflared tunnel --url http://127.0.0.1:7676
  hl: https://devspace-demo.trycloudflare.com


# 3 · Enter the endpoint (origin + /mcp) in the ChatGPT connector and approve with the Owner password
  # Connector URL → https://devspace-demo.trycloudflare.com/mcp
# [Owner password approval page] → Enter the password from auth.json ✓ Connected


# 4 · Ask ChatGPT to open the workspace
$ You ›
  Open ~/work/api-server; the tests keep failing in the user serializer. Help me find the cause.


claude: ChatGPT ›
  # → open_workspace { path: "~/work/api-server" }
    # workspaceId: ws_8fa2 · Read AGENTS.md
  # → bash { cmd: "npm test" }
    hl: FAIL  test/user.test.ts · serialize() drops the email field


  # → grep { pattern: "serialize", path: "src/" }
  # → read { path: "src/user.ts" }
  Found it:the object returned by serialize() is missing the email field,
  which the test expects to exist. I'll add it with edit.


  # → edit { path: "src/user.ts", ... }
    # + email: this.email,


# 5 · Rerun the tests to verify(all on your machine; no files uploaded)
  # → bash { cmd: "npm test" }
    ok: PASS  test/user.test.ts · All tests passed(12 passed)


claude: ChatGPT ›
  ok: The fix passes the tests. Should I run git commit with bash, or would you like to review the diff first?

ChatGPT ran open_workspace, bash, grep, read and edit, all on your machine. The source code never left your machine.

— DevSpace core promise: AI gets capabilities, files stay local · Translated from Chinese

MCP tool calls and permissions

ChatGPT makes explicit MCP calls to DevSpace, which executes them on your machine without uploading files. read / edit / write have path boundaries and can access only allowed roots; bash runs tests with your user permissions. ChatGPT operates local code through a controlled channel without sending the code into the cloud.

Security settings must account for shell access matching your account permissions. Keep roots narrow and add an access-control layer to the channel; assess the permissions granted to ChatGPT as a collaborator with local access.

06Boundaries and limitations

Connection and permission limits

Warning

Shell has your account permissions: file tools have path boundaries, but bash runs as your user and can do anything your account can. Official guidance treats a connected client as a trusted collaborator with access to your machine. Confirm you trust it before connecting.
Keep roots narrow. Avoid ~, / and C:\ as roots. Use narrow scopes such as ~/work or ~/personal/open-source so accessible files are easier to determine.
Keep the Owner password and auth.json secret. The password in ~/.devspace/auth.json is the only connection-approval checkpoint. For deployments, use DEVSPACE_OAUTH_OWNER_TOKEN="$(openssl rand -base64 32)" to set a strong token.
Add another channel protection layer. The Owner password alone is insufficient; official guidance recommends Cloudflare Access or Tailscale access controls ahead of the channel to reduce public exposure.
Avoid shell command logging. Command previews are disabled by default; DEVSPACE_LOG_SHELL_COMMANDS=1 enables logging. If commands contain keys, enabling it writes secrets to logs; leave it disabled.
Windows requires Bash. Shell execution needs a Bash-compatible shell; PowerShell and cmd.exe are unsupported. Use Git Bash, WSL, MSYS2 or Cygwin and verify with devspace doctor.
Worktree mode has prerequisites: it requires a Git repo, a version-controlled path, at least one commit and a valid baseRef. Uncommitted changes are not copied to the worktree. Commit first or use checkout mode.
workspaceId identifies a session: restarting the server invalidates old workspaceIds. If you see unknown workspace, call open_workspace again. This remains an early project (created in 6/2026); connection details continue to change, so consult the official docs.

07Next steps

DevSpace advanced settings

DevSpace is an open-source TypeScript project under the MIT license, with publicly readable source. After establishing a basic connection, integrate it into a fuller development workflow through these settings.

Advanced settings

1. Project instructions in AGENTS.md / CLAUDE.md. Put coding rules, naming conventions and testing procedures in the root AGENTS.md or CLAUDE.md. open_workspace loads them; nested instruction files appear as availableAgentsFiles, prompting the model to read before editing.

2. Discover local skills. Skills are enabled by default; explicitly enable them with DEVSPACE_SKILLS=1 devspace serve. The model reads SKILL.md in your skill folder before using a skill.

3. Change cards on supported hosts. DevSpace can display tool cards and change summaries on ChatGPT Apps-compatible hosts. The default is DEVSPACE_WIDGETS=full; use changes for summaries only. Plain MCP clients ignore widget metadata.

4. Manage channels with environment variables. Override changing URLs with DEVSPACE_PUBLIC_BASE_URL. OAuth redirect hosts allow only chatgpt.com, localhost and 127.0.0.1 by default; adjust with DEVSPACE_OAUTH_ALLOWED_REDIRECT_HOSTS when needed.

5. Start troubleshooting with doctor. devspace doctor identifies nearly all connection, host, Node and native-dependency issues. Run it first, then consult gotchas.md.

Three official documents

① docs/setup.md: Complete installation, channel and connector setup. ② docs/security.md: Security model for permissions, roots, host allowlists and data flow. ③ docs/gotchas.md: 14 common errors and their fixes.

Turn ChatGPT into Codex while using your ChatGPT quota separately. Your files, tools and terminal stay on your own machine.

— DevSpace · Waishnav, project README · Translated from Chinese

Site search

ChatGPT access to local development environments

ChatGPT access to local machines

init

serve

Tunnel

ChatGPT connector

Owner password approval

open_workspace

npm installation and three management commands

npx installation

Local MCP tools for ChatGPT

Open a workspace

Read files

Targeted editing

Write files

Inspect directories

Locate files

Search code

Run Shell

Four public HTTPS channels

Eight setup points

Node versions 20.12 to 26

Enter the public origin without /mcp

Rebuild if better-sqlite3 fails to load

Override temporary channel URLs with an environment variable

Run doctor for 403 / host-header errors

Narrow roots improve safety

Worktree mode for parallel tasks

Use file tools instead of shell redirection

Local code repair workflow

MCP tool calls and permissions

Connection and permission limits

DevSpace advanced settings

Advanced settings

Three official documents

init

serve

Tunnel

ChatGPT connector

Owner password approval

open_workspace

npx installation

Open a workspace

Read files

Targeted editing

Write files

Inspect directories

Locate files

Search code

Run Shell

Four public HTTPS channels

Node versions 20.12 to 26

Enter the public origin without /mcp

Rebuild if better-sqlite3 fails to load

Override temporary channel URLs with an environment variable

Run doctor for 403 / host-header errors

Narrow roots improve safety

Worktree mode for parallel tasks

Use file tools instead of shell redirection

MCP tool calls and permissions

Advanced settings

Three official documents

Related documents

CVE-2026-98432: Linux TCP analysis and AI repair prompts

macOS × Ubuntu 24.04: Sunshine + Moonlight implementation guide

codebase-memory-mcp: Installation and Knowledge Graphs