WebCodex: run ChatGPT, Claude and Codex agents against your own repositories

What WebCodex solves for self-hosted agent work

The README states the problem plainly: WebCodex lets ChatGPT, Claude, and other AI agents work directly with code and developer tools on your own machines. The alternative it argues against is moving the project into a hosted workspace just to get an agent to touch it. That is the whole pitch, and it is a narrow one. If your repository already lives on a laptop or a build box with the compilers, test runners and Git checkout you actually use, WebCodex is a way to expose that environment instead of reconstructing it somewhere else.

The intended audience is developers who already run an AI coding assistant and want it pointed at real infrastructure. The README lists the capabilities as understanding and editing code, using the real toolchain (commands, tests, formatters, compilers), working with Git status and diffs, handling long-running work, and supporting human review through a Runtime Console. The topics list points at the same crowd: agent, claude-code, codex, mcp, self-hosted.

It is not a hosted service. There is no homepage in the repository metadata, and the README repeatedly sends readers to self-hosting documentation. The project is Apache-2.0 and the workspace lives in Rust, with a Cargo workspace split into crates such as webcodex-core, webcodex-runner, webcodex-server (built from src/bin/webcodex-server.rs), webcodex-lsp, webcodex-persistent-shell and webcodex-workspace. That crate layout is the clearest signal of the design: this is not a thin proxy, it is a tool runtime with a shell, a language server and a workspace abstraction inside it.

The Server, the Runner and the MCP boundary

The README's architecture diagram is three boxes: an AI client reaches WebCodex over MCP or HTTPS, WebCodex reaches your machine, and your machine holds the repository, Git, and compilers or tests. The internal split behind that diagram is Server plus Runner, documented in docs/ARCHITECTURE.md, docs/MCP.md and docs/AUTH_MODEL.md. The Server is what the AI client connects to; the Runner is what sits next to the code.

The default branch's Cargo workspace confirms the separation at the crate level: webcodex-runner, webcodex-runner-registry and webcodex-runner-config exist as distinct members, and the Dockerfile comment says webcodex-runner is intentionally not built into the server image. So the container you deploy for hosting is not the same artifact that touches your repository. The server image does bundle the webcodex CLI so that server-side pairing and administration can run through docker compose exec webcodex webcodex ....

There are several ways for the client to reach the Server, and the README is explicit that they are transport choices rather than different products: public HTTPS, Cloudflare Tunnel, and the OpenAI Secure MCP Tunnel are only ways for ChatGPT to reach the Server, and do not switch you into a different restricted experience. The restricted experience is the share mode described below. The environment variable WEBCODEX_MCP_MODEL_SURFACE is set in compose.yaml with a default of adaptive-runtime-v1, which suggests the model-facing surface is configurable, though the README does not explain what the alternatives are.

Installing WebCodex and running a first session

There are two entry paths in the README, and they are for different intentions. The recommended one for Windows and macOS is WebCodex Desktop plus the official OpenAI Secure Tunnel, following docs/desktop-install.md. The CLI, existing-Server and self-hosting paths go through docs/PERSONAL_SETUP.md.

If you only want to see whether the model fits your workflow, the README gives a one-command trial that runs inside a single repository. It starts a temporary, single-project, restricted environment and prints the ChatGPT connection values:

cd /path/to/your/repository
npx --yes @yyjeqhc/webcodex share

The README states that the endpoint and the temporary credential stop working when the command exits, and that share is intended for trials and short-lived sharing rather than as the default full daily setup. The exact steps are in docs/QUICK_START.md. On Windows there is also an explicit form, webcodex share --tunnel cloudflare|openai|none, so the tunnel choice is visible on the command line.

For a durable setup you run a Server and a Runner. The repository ships a compose.yaml that pulls ghcr.io/yyjeqhc/webcodex-server:latest and requires two variables to be set in a .env file. WEBCODEX_TOKEN is the credential, and WEBCODEX_PUBLIC_URL is the externally reachable address:

services:
  webcodex:
    image: ${WEBCODEX_SERVER_IMAGE:-ghcr.io/yyjeqhc/webcodex-server:latest}
    environment:
      WEBCODEX_TOKEN: ${WEBCODEX_TOKEN:?set WEBCODEX_TOKEN in .env}
      WEBCODEX_ADDR: 0.0.0.0:8080
      WEBCODEX_DATA: /var/lib/webcodex
      WEBCODEX_PUBLIC_URL: ${WEBCODEX_PUBLIC_URL:?set WEBCODEX_PUBLIC_URL in .env}

The compose file binds the published port to 127.0.0.1 by default, with a comment stating that only an existing reverse proxy on the host should reach WebCodex. It also runs the container read_only with a 64 MB tmpfs at /tmp, drops all capabilities and sets no-new-privileges. The healthcheck curls http://127.0.0.1:8080/openapi.json every 15 seconds. If you would rather build the binaries yourself, the README gives cargo build --release --workspace --bins and then adds target/release to PATH.

Where WebCodex is the wrong tool

The security section is the honest part of the README, and it should be read before anything else: WebCodex can read and modify files and execute commands inside configured project boundaries. That is the feature and the hazard in one sentence. The README's own guidance is to use version control, keep credentials out of prompts, logs and Git, and register only project roots the assistant should access. There is no sandbox promise here beyond the boundary you configure. If you cannot articulate which directories the Runner should see, you are not ready to run it.

Platform coverage is uneven, and the README says so directly. Linux x64/arm64 covers local share, Server and Runner workflows. macOS covers Desktop local Server plus Runner, the OpenAI Secure Tunnel, local share and standalone Runner. Windows x64 gets Desktop local Server plus Runner with the official OpenAI Secure Tunnel, plus CLI and Runner, a local foreground Server, and the explicit share form. Windows arm64 is the thinnest: CLI and Runner, local foreground Server and share, with managed OpenAI tunnel-client supported, but the pinned Cloudflare release has no official Windows ARM64 artifact, so Cloudflare there requires a trusted explicit or PATH cloudflared. The Desktop installer is currently Windows x64 only, and WebCodex-managed Windows Server services remain unsupported outside Desktop's owned foreground runtime. If you wanted a Windows ARM64 machine running WebCodex as a background service, the answer is no.

Share mode is also easy to misread. It is single-project, restricted and temporary by design. Treating it as production because it worked in a demo is the obvious failure mode, and the README pre-empts it by calling share unsuitable as the default full daily setup.

WebCodex compared with running an agent inside a container

The closest alternative in practice is the hosted-workspace model: you push the repository into a cloud development environment and let the agent work there. The difference is where the toolchain lives and what it can see. In the hosted model the agent gets a fresh machine image; you reinstall dependencies, and anything that depends on local hardware, a private network or a licensed compiler is either unavailable or must be reproduced. WebCodex inverts that: the agent reaches the machine that already owns the repository, so the compilers, tests and Git checkout are the ones you use. The cost is that you now operate a Server and a Runner, and you own the exposure question that a hosted vendor would otherwise own.

Within the MCP ecosystem, the comparison is against single-purpose MCP servers that expose one capability, such as a filesystem server or a Git server. WebCodex bundles more: the crate list includes webcodex-lsp for code navigation and webcodex-persistent-shell for long-running execution, and the README claims long-running work stays observable instead of requiring one model turn to stay open indefinitely. That is a broader surface than a filesystem MCP server, and a broader surface to secure. If all you need is read access to one directory, a smaller MCP server is the better fit; WebCodex's value appears when the agent needs commands, tests and Git, not just file reads.

Maintenance, licence and what an upgrade costs you

The repository is not archived, and the last push was on 2026-09-10, which is recent enough to call the project current. The release history in the same period is dense: v0.3.9 on 2026-08-26, v0.4.0 on 2026-09-07, v0.4.1 on 2026-09-10. Three releases in roughly two weeks, with the workspace version pinned at 0.4.1 in Cargo.toml. Rapid minor releases on a 0.x line mean you should expect the surface to move; the Cargo workspace and the compose file both reference versioned artifacts, so pinning the image tag rather than following latest is the lower-surprise choice. The compose file as shipped uses ghcr.io/yyjeqhc/webcodex-server:latest with pull_policy: always, which will follow every release unless you override WEBCODEX_SERVER_IMAGE.

Licensing is Apache-2.0, declared both in the repository metadata and in Cargo.toml under workspace.package. That is a permissive licence with an explicit patent grant, and it imposes no copyleft on your own code. It does not tell you anything about the security posture of running an agent with command execution on your host, and nothing in the licence limits your liability if the agent deletes a branch. This is not legal advice; read LICENSE and SECURITY.md yourself.

The operational cost is the part the README is least specific about. It documents how to start things and where the deeper guides are, but the upgrade story is spread across docs/DEPLOYMENT.md and docs/TROUBLESHOOTING.md rather than summarised. The README does not document rollback. If you run the container, your state is in the webcodex_data volume and your configuration is in environment variables, so a rollback means pinning an older image tag and restoring that volume. Plan for that before you upgrade.

Editorial conclusion

Adopt WebCodex if you want an AI agent to work inside a repository that already lives on your own hardware, and you are willing to run a Server and a Runner rather than hand the code to a hosted workspace. Do not adopt it if you want the agent to run somewhere you do not administer, or if you need a managed Windows service outside Desktop. Before committing, verify two things: that the Runner can reach the toolchain your project needs, and that the credential path (WEBCODEX_TOKEN plus WEBCODEX_PUBLIC_URL for compose, or the Desktop tunnel) matches how you actually expose the host.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. yyjeqhc/webcodex on GitHub