Project OS for Codex v0.3.0 — Codex First-Run Contract

Project OS for Codex v0.3.0

Codex First-Run Contract makes the Codex integration fail closed, workspace scoped, diagnosable, and reproducible.

Highlights

• Verifies the short-lived credential, project binding, required scopes, and exact two-tool MCP surface before accepting a Codex session.
• Adds a strict project-level .codex/config.toml.example with a required MCP server and explicit tool allowlist.
• Adds pnpm codex:doctor for a real MCP handshake and project-context read against the current checkout.
• Adds context-first and verification-first session rules to the repository and generated project AGENTS.md files.
• Standardizes the supported runtime on maintained Node.js 22+ lines and validates Node.js 22 and 24 in CI.
• Builds the production container and verifies GET /api/health in GitHub Actions.

Security

• Workspace administration now depends only on the active workspace membership; a historical global account role cannot elevate a user in another workspace.
• Startup migration no longer guesses an owner from a global role or user order.
• Removing or downgrading an owner no longer allows startup to restore that owner.
• MCP failures return safe connection categories instead of backend error strings.
• Local Codex configuration, environment files, and logs are ignored by Git.

Verified release gates

• Pull request #1 merged at commit 3cb909a.

• PR CI run #6 passed on Node.js 22, Node.js 24, and the release container.

• Main CI run #7 repeated the same gates successfully.

• Seven server, workspace, Agent API, and MCP integration tests passed.

• The production dependency audit and public-tree privacy/secret release guard passed.

• A fresh install from the public v0.3.0 tag completed the MCP handshake, exposed exactly two tools, read project context, and made zero API writes.

Upgrade notes

• Node.js 22 or newer is required.
• Review the release commit before giving the MCP process a credential.
• Use the shortest practical AI credential lifetime and revoke it after the task.
• The released MCP surface remains exactly:
  • project_os_get_context
  • project_os_append_progress

Current boundaries

Remote MCP/OAuth, source-repository synchronization, and guided onboarding remain planned v0.4+ work. The direct maintainer profile screenshot is absent from the v0.3.0 tree; the historical v0.2.0 tag still retains its original artifact.

Project OS for Codex is an independent open-source project and is not an official OpenAI product.

Full changelog: v0.2.0...v0.3.0

Project OS for Codex v0.2.0

Project OS for Codex v0.2.0

This release turns the repository into a focused, English-first open-source control plane for Codex projects: visible progress, resumable context, Git-backed records, and safe handoffs.

Highlights

• Short-lived, revocable AI credentials scoped to one workspace and one project.
• A stdio MCP server designed for Codex through the public MCP interface.
• Two tested tools: read scoped project context and append structured progress.
• Idempotent progress writes with an agent-reported verification note and matching project-record Git commits.
• A project-level .codex/config.toml.example that forwards local environment variables without committing secret values.
• Owner approval for workspace join requests.
• Real dark/light product screenshots and beginner-friendly setup documentation.
• Docker, deployment, Git, AI-provider, knowledge, backup, and rollback guidance.

Security

• Production fails closed when bootstrap authentication is missing.
• Credentials are stored only as hashes and never exposed to the frontend after creation.
• Workspace and project ownership are enforced server-side.
• Agent writes use server-derived identity, validation, rate limits, audit records, and idempotency.
• Provider keys, customer data, private endpoints, and internal deployment secrets are not included.

Verification

• Privacy and release guard passed for every published file.
• TypeScript and Vite production build passed.
• Agent API and MCP protocol acceptance tests passed.
• Dark and light UI paths were visually reviewed against an isolated local backend.

Current limits

• Project OS does not run Codex, control a Codex account, or monitor Codex sessions automatically.
• The current MCP release has exactly two scoped tools.
• Verification notes are reported by the agent and retained for human review; they are not independent proof that source code or a deployment passed.
• Git commits belong to the local Project OS record repository and do not modify an existing source repository.

See CHANGELOG.md, ROADMAP.md, and docs/CODEX_SETUP.md for details.

Codex is a trademark of OpenAI. This independent project is not affiliated with or endorsed by OpenAI.