<p align="center">
  <picture>
    <img src="https://raw.githubusercontent.com/Waishnav/devspace/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/Waishnav/devspace/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/Waishnav/devspace/ci.yml?style=flat-square&branch=main" /></a>
  <a href="https://github.com/Waishnav/devspace/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/npm/l/%40waishnav%2Fdevspace?style=flat-square" /></a>
</p>

[![DevSpace connected to ChatGPT](https://raw.githubusercontent.com/Waishnav/devspace/main/docs/assets/devspace-screenshot.png)](https://raw.githubusercontent.com/Waishnav/devspace/main/docs/assets/devspace-screenshot.png)

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

### macOS App (recommended)

Download the latest `DevSpace-macOS-*.dmg` from the
[GitHub Releases page](https://github.com/arthurwangwsx-code/DevSpace/releases/latest), drag `DevSpace.app`
to Applications, and open it. The App bundles its own Node runtime and provides the full Control Center for
workspace roots, managed Tunnel, Browser control, Computer Use permissions, login startup, service status,
and diagnostics.

For a repeatable one-command install or update, use the release bootstrap. It installs into
`~/Applications/DevSpace.app`, verifies the published SHA-256 checksum, and delegates the actual replacement
to DevSpace's transactional updater:

```bash
curl -fsSL https://github.com/arthurwangwsx-code/DevSpace/releases/latest/download/install.sh | bash
```

After installation, updates and rollback are also available through the App or CLI:

```bash
devspace update --check
devspace update
devspace rollback
devspace uninstall
```

Normal uninstall preserves `~/.devspace` configuration and credentials; use `--purge-config` only when an
explicit full reset is desired.

Development-signed releases may require **Control-click → Open** on first launch until the project has a
Developer ID Application certificate and notarization configured. The Release notes state the trust status
for each build.

### CLI / source development

The CLI/source path requires Node `>=22.19 <27`.

See [Distribution, Control Center, and Tunnel Architecture](docs/distribution-and-control-center.md) for the
App/runtime/Tunnel architecture and release model.

Install the DevSpace CLI:

```bash
npm install -g @waishnav/devspace
```

Then initialize and start the server:

```bash
devspace init
devspace serve
```

Or run it without a global install:

```bash
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:

```text
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:

```text
~/.devspace/auth.json
```

Keep that password private.

## Connect Your MCP Client

The default local endpoint is:

```text
http://127.0.0.1:7676/mcp
```

Most users should connect through a public HTTPS tunnel:

```text
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

## Capability gateway preview

DevSpace can also mount stdio or Streamable HTTP MCP servers as dynamic
capabilities while keeping its public API fixed. Set `DEVSPACE_CAPABILITIES=1`, then connect an Agent
to `/capabilities/mcp` or use `/api/capabilities/v1` from CI. See
[Mount external MCP servers](docs/mcp-provider-mounts.md) for the manifest format and CLI, and
[Dynamic Provider management](docs/dynamic-provider-management.md) for runtime install/load APIs. The
[current Chrome Provider](docs/chrome-current-profile-provider.md) reuses the official
`chrome-devtools` daemon, so CLI, CI, and DevSpace share one current-profile debugging connection.

## 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.

## 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:

```bash
devspace doctor
```

## Documentation

- [Product Capability Map](docs/product-capability-map.md) — start here for the complete product design, feature inventory, architecture boundaries, and documentation map
- [Native macOS Onboarding](docs/native-macos-onboarding-and-control-center.md) — SwiftUI Control Center, Browser installation and permission-guided first run
- [Distribution, Control Center, and Tunnel Architecture](docs/distribution-and-control-center.md)
- [Setup Guide](docs/setup.md)
- [ChatGPT Coding Workflow](docs/chatgpt-coding-workflow.md)
- [Configuration Reference](docs/configuration.md)
- [Security Model](docs/security.md)
- [Troubleshooting Gotchas](docs/gotchas.md)
- [Capability API Architecture Principles](docs/capability-api-principles.md)
- [Browser Extension Provider](docs/browser-extension-architecture.md)
- [macOS Desktop Helper](docs/macos-desktop-helper.md)
- [Running DevSpace in Lima (Chinese)](docs/lima-devspace.md)
- [MCP Resource Control and High-Concurrency Stability (Chinese)](docs/mcp-resource-control.md)
- [Universal Capability Runtime Implementation Plan (Chinese)](docs/capability-runtime-implementation-plan.md)
- [Performance and Reliability Plan](docs/performance-and-reliability.md)
- [Stress and Soak Testing](docs/stress-testing.md)
- [Capability Runtime Stress Testing](docs/capability-stress-testing.md)

Workspace handles are persistent. Keep them available across later turns;
call `release_workspace` only when the user requests resource release or a
workspace is known to be unused for a long time. It evicts only reconstructable
in-memory metadata, and later calls with the same `workspaceId` restore it
automatically. Checkout-mode `open_workspace` also resumes the latest handle
for the same path by default.

## 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 DevSpace is one example of that.
This year, I started my journey to build a single-person and multiple-agents company doing multiple millions in
revenue. If you want to watch the failures, wins, lessons, and everything in
between, come hang out with me on [X](https://x.com/wshxnv).

## 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:

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