DevSpace

<p align="center"> <picture> <img src="https://raw.githubusercontent.com/CYZice/devs-codex/main/docs/assets/devspace-logo-light.png" alt="DevSpace logo" width="140"> </picture> </p>

<h1 align="center">DevSpace</h1>

<p align="center">Bring a Codex-style coding workflow to ChatGPT.</p>

<p align="center"> <a href="https://www.npmjs.com/package/@waishnav/devspace"><img alt="npm" src="https://img.shields.io/npm/v/%40waishnav%2Fdevspace?style=flat-square" /></a> <a href="https://github.com/CYZice/devs-codex/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/CYZice/devs-codex/ci.yml?style=flat-square&branch=main" /></a> <a href="https://github.com/CYZice/devs-codex/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/npm/l/%40waishnav%2Fdevspace?style=flat-square" /></a> </p>

Give ChatGPT a secure connection to your own machine and Turn ChatGPT into Codex

DevSpace is a self-hosted MCP server that lets ChatGPT read, edit, search, and run code in your real local projects — your files, your tools, your terminal — without uploading anything to a third party. You run it on your machine, expose it through a tunnel you control, and approve the connection with a password only you have.

Sponsors and Special Thanks

<!--

<table> <thead> <tr> <th>Sponsor</th> <th>About</th> </tr> </thead> <tbody> <tr> <td align="center" width="220"> <a href="https://rebates.ai/"> <img src="https://app.rebates.ai/brand/rebates-lockup.svg" alt="Rebates" width="170" > </a> </td> <td> <strong>The ads in your terminal pay you.</strong><br><br> <a href="https://rebates.ai/">Rebates</a> adds one optional sponsored footer to your coding agent and pays you cash back for every session in which it is shown. Turn it off at any time. </td> </tr> </tbody> </table> --> <p> DevSpace is open to new sponsors. <a href="https://x.com/wshxnv">Get in touch to become one.</a> </p>

Installation

DevSpace requires Node >=22.19 <27.

Install the DevSpace CLI:

npm install -g @waishnav/devspace

Then initialize and start the server:

devspace init
devspace serve

Or run it without a global install:

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

During setup, DevSpace asks for:

• the local project folders ChatGPT is allowed to open through DevSpace
• the local port, usually 7676
• your public HTTPS base URL from Cloudflare Tunnel, ngrok, Pinggy, Tailscale Funnel, or another reverse proxy

Use the public origin without /mcp during setup:

https://your-tunnel-host.example.com

You will configure your MCP client with the public /mcp URL after setup.

When the client connects, DevSpace opens an Owner password approval page. Enter the Owner password printed by devspace init. It is also stored in:

~/.devspace/auth.json

Keep that password private.

Connect Your MCP Client

The default local endpoint is:

http://127.0.0.1:7676/mcp

Most users should connect through a public HTTPS tunnel:

https://your-tunnel-host.example.com/mcp

[!NOTE] Using DevSpace as an MCP connector isn't against OpenAI's Usage Policies — it's a standard custom App/connector setup, and writing or running code isn't a restricted use case. But your account is governed by your usage, not by DevSpace. Don't point it at anything that would violate your provider's terms. Used normally, you're fine. (Based on OpenAI's Usage Policies and Service Terms as of June 2026.)

What ChatGPT Can Do

Once connected, ChatGPT can open one of your approved project folders as a workspace. From there, it can inspect the repo, make scoped edits, run commands, and show you what changed.

DevSpace gives ChatGPT tools to:

• read, write, and edit files inside the opened workspace
• search code and inspect directories
• run shell commands for tests, builds, git, and package scripts
• use isolated Git worktrees for parallel coding sessions
• follow project instructions from AGENTS.md and CLAUDE.md
• discover local agent skills from your skill folders
• show tool cards and optional change summaries in ChatGPT Apps-compatible hosts

Mental Model

DevSpace is remote access to selected local folders.

You decide which roots are allowed. The MCP client still has powerful local capabilities inside an opened workspace, including shell execution. Treat a connected client like a trusted coding partner with access to your machine.

For a normal ChatGPT coding session:

1. Start your tunnel.
2. Run devspace serve.
3. Connect the MCP client to your public /mcp URL.
4. Approve the connection with the Owner password.
5. Ask ChatGPT to open a project inside one of your allowed roots.

Architecture

DevSpace is a local execution layer for MCP hosts. The host remains the orchestrator: it chooses tools, asks for user confirmation, and presents results. DevSpace provides the workspace-scoped capabilities and enforces the local boundaries around them.

ChatGPT / Claude / another MCP host
                |
        Streamable HTTP MCP server
                |
  +-------------+------------------+
  |                                |
Workspace and policy layer      Tool adapters
  |                                |
  |                         files, search, shell,
  |                         Git, artifacts, agents
  |
SQLite-backed local state
  |
approved roots, workspaces, worktrees,
process sessions, review checkpoints

Request flow

1. The host connects to the /mcp endpoint and completes Owner-password authentication.
2. open_workspace resolves a checkout or isolated Git worktree under an approved root. It loads AGENTS.md, CLAUDE.md, and applicable skills so the host receives project-specific instructions.
3. Read-only operations use workspace-aware file, search, and directory tools. Mutating operations go through explicit patch, write, shell, Git, process, or artifact tools and return inspectable results.
4. Long-running commands and bounded subagents are tracked as process or agent sessions. Their lifecycle, failures, and ownership remain visible to the host instead of being hidden inside an autonomous loop.
5. Change review uses persisted checkpoints so the host can show a coherent diff relative to the last review point.

Core boundaries

• Allowed roots: every workspace path is resolved and checked against a configured filesystem root; a workspace is not the same thing as an allowed root.
• Workspace lifecycle: checkout mode works in an existing directory; worktree mode creates an isolated Git worktree for parallel work.
• Local authority: shell commands run with the user's local authority, so authentication, credentials, tunnels, and destructive actions stay explicit.
• Provider adapters: Codex, Claude, OpenCode, Pi, ACP, and other runtimes are translated at the edges. Provider-specific behavior does not define the core workspace model.
• Artifacts and review: generated or incoming files and change summaries use dedicated paths rather than being smuggled through ordinary text or shell arguments.

Repository map

Area	Responsibility
src/server.ts	MCP server setup, tool registration, instructions, and responses
src/workspaces.ts and src/roots.ts	Workspace lifecycle, instruction loading, and path containment
src/process-sessions.ts	Long-running process lifecycle and I/O
src/git.ts and src/git-worktrees.ts	Git inspection and isolated worktrees
src/local-agent-*.ts	Bounded local-agent providers, runtimes, and lifecycle
src/artifact-*.ts and src/incoming-artifacts.ts	Artifact exchange and downloads
src/review-checkpoints.ts	Persisted change-review state
src/db/	SQLite schema and migrations for local state
src/ui/	MCP host widgets and change-review presentation
desktop/	Native desktop process adapters and packaging assets

The design goal is a small set of composable, inspectable primitives. A host can combine them into a coding workflow without giving DevSpace hidden control over provider permissions, tunnel ownership, or user approval decisions.

Platform Support

DevSpace supports Linux, macOS, and Windows environments with a Bash-compatible shell.

Platform	Status	Notes
Linux	Supported	Requires Node, npm, Git, and Bash.
macOS	Supported	Requires Node, npm, Git, and Bash.
Windows with Git Bash, WSL, MSYS2, or Cygwin Bash	Supported	Git Bash is the simplest native Windows setup.
Windows PowerShell or cmd.exe only	Not supported yet	Install Git Bash or use WSL.

Run this to inspect your local setup:

devspace doctor

Documentation

• Setup Guide
• ChatGPT Coding Workflow
• Configuration Reference
• Native File Download
• Security Model
• Troubleshooting Gotchas

Philosophy

Every piece of software is becoming conversational. Natural language is redefining how we interact with tools, workflows, and systems.

My bet is that ChatGPT becomes the operating system for everything. Once we reach AGI, we will simply talk to ChatGPT, and it will prompt, coordinate, and orchestrate sub-agents that set up the right loops for us.

We are not there yet.

DevSpace is one attempt to fast-forward that future: a way for MCP-capable hosts like ChatGPT and Claude to work directly with local project files through explicit, inspectable tools.

Built by Waishnav

I'm Waishnav. I like building opinionated products and tools, and Artifacts is one example.

This year, I began my journey to build a one-person, multi-agent company capable of generating millions in revenue. If you want to follow the failures, wins, lessons, and everything in between, come hang out with me on X.

More from me

<table> <thead> <tr> <th>Project</th> <th>About</th> </tr> </thead> <tbody> <tr> <td align="center" width="220"> <a href="https://gitcms.dev/"> <img src="https://gitcms.dev/brand/gitcms-logo.svg" alt="GitCMS" width="48" /><br /> <strong>GitCMS</strong> </a> </td> <td> <strong>Modern CMS and tooling for markdown based content sites — built for agents and humans.</strong><br><br> Visual editing, editorial workflow, and ChatGPT/Claude content agents, with every post and page stored as files in your repo. <a href="https://gitcms.dev/">Learn more</a>. </td> </tr> </tbody> </table>

Local Development

For working on DevSpace itself:

npm install --include=dev
npm run dev
npm run typecheck
npm test
npm run build
npm run start