​
Use Codex Remote Projects Across Hosts

guide2026-06-034 min read

Remote project turns any reachable folder on a connected machine into a Codex project, which makes local, Mac mini, and VPS workspaces feel much closer to the same operating surface.

codexremote-projectsworkflow

​
Summary

Codex can add a remote folder as its own project through the Add remote project dialog. The important idea is that the project boundary is no longer limited to the machine where the Codex app is running: a connected host such as macmini or VPS-hk can expose a real folder path, and that folder then appears in the Codex sidebar like any other project. This is useful when the working files already live on another machine, when a GPU or server environment matters, or when a repo should stay close to its deployment/runtime host.

​
What This Solves

Remote project solves the awkward gap between “Codex is on my desktop” and “the files I actually need are on another machine.” Instead of copying a repo back and forth or treating SSH as a separate manual workflow, Codex can connect to a configured host, browse a folder, and add that folder as a persistent project entry. In the captured UI, the same dialog can target different hosts:
  • macmini, using a folder path under /Users/yueyh
  • VPS-hk, using a folder path under /home/yueyh
Once added, the remote folder appears as its own project in the sidebar. That makes it natural to switch between local notes, a Mac mini workspace, and a VPS workspace without changing the mental model of “open a project, ask Codex to work inside it.”

​
Who This Is For

This is for anyone who uses Codex across more than one machine:
  • A local laptop or desktop for writing, reviewing, and orchestration
  • A Mac mini for always-on local compute or shared workspace storage
  • A VPS for server-side repos, deployments, LangFlow instances, or long-running services
  • A remote machine where the repo, credentials, or runtime environment already exist
The feature is especially helpful if you want Codex to work where the project already lives instead of treating the remote machine as an afterthought.

​
Prerequisites

  • A connected remote host in Codex, such as macmini or VPS-hk
  • A folder on that host that should become the project root
  • Permission for Codex to read and work inside that folder
  • A clear boundary for what should count as the project, such as /Users/yueyh/frontend-slides or /home/yueyh/langflow-yitwah
Remote project is a project-opening feature, not a replacement for environment setup. If the remote repo needs dependencies, credentials, GPUs, services, or ports, those still need to exist on the selected host.

​
The Workflow

1

Open the remote project dialog

Use Codex’s project controls to choose Add remote project. The dialog asks for a remote host and a folder path.
2

Choose the host

Select the connected host that owns the files. For a local network machine this might be macmini; for a server this might be VPS-hk.
3

Browse or type the folder path

Set the folder path to the parent directory you want to browse. The examples show /Users/yueyh on macOS-style hosts and /home/yueyh on Linux-style hosts.
4

Pick the actual project directory

Choose a concrete folder such as langflow-docker, onyx_data, searxng, vibe-proving-math, or another repo/workspace listed under that host.
5

Add the project

Click Add project. Codex then treats that remote folder as its own sidebar project, so future chats can be anchored directly in that remote workspace.
Use the smallest folder that still contains the real project. Adding /home/yueyh as a project is usually too broad; adding /home/yueyh/langflow-docker or /home/yueyh/vibe-proving-math gives Codex a cleaner working boundary.

​
Common Failure Modes

If the remote host is connected but the folder list looks wrong, first check the path style. macOS hosts usually start from /Users/..., while Linux VPS hosts usually start from /home/....
If Codex can see the folder but cannot complete work inside it, the issue is often permissions, missing dependencies, or missing credentials on the remote machine. Treat the remote project as a real machine context: commands, files, ports, and secrets are host-specific.
Adding a broad home directory can make future work noisy because unrelated folders become part of the project surface. Prefer repo-level folders when possible.

​
Final Checklist

  • The intended remote host is selected, such as macmini or VPS-hk
  • The folder path matches the host operating system, such as /Users/yueyh or /home/yueyh
  • The selected folder is the actual project root, not only a broad parent directory
  • The project appears in the Codex sidebar after adding it
  • A new chat inside that project can read the expected files and run in the expected environment

​
What To Remember

Remote project is best understood as “bring the workspace to Codex without moving the workspace.” It is a clean way to keep server-side or machine-specific repos on the host where they belong while still giving Codex a normal project interface. For daily use, the rule of thumb is simple: connect the host, select the narrow project folder, add it once, and then treat it like any other Codex project.

​
Metadata

Quick Reference

Typeguide
Statuspublished
Date2026-06-03

Retrieval Tags

codexremote-projectsworkflow
Related
Codex project setupremote development