`codex agents` fails with an error

[michaelglass]

codex agents fails with an error...

Error: managed standalone Codex install not found at /Users/michaelglass/.codex/packages/standalone/current/codex

This command requires the standalone install managed by the Codex installer, because the daemon starts and updates app-server from that fixed path.

Install it with:
  curl -fsSL https://chatgpt.com/codex/install.sh | sh

Then rerun the command you just tried.

I wonder about the fix here. symlinking codex to the right spot? Templating in the right path where codex looks? Something else?

[michaelglass]

codex agents does work if you manually start the server

codex app-server --listen unix://

[sadjow]

Thank you for reporting this, Michael, and especially for noting that manually starting codex app-server --listen unix:// works. That observation points directly to the daemon startup path.

I reproduced the failure with this flake's Codex 0.150.1 package and with nixpkgs#codex. This is a real packaging compatibility issue rather than a missing runtime dependency.

What is happening

codex agents asks the app-server daemon to start. The daemon first probes its Unix socket. If a server is already listening, it uses that server, which explains the manual workaround. Otherwise it requires this fixed executable path:

$CODEX_HOME/packages/standalone/current/codex

The relevant upstream code is:

• codex agents invokes the daemon Start lifecycle
• the managed executable path is fixed under CODEX_HOME
• the daemon probes the socket before checking that path
• the standalone installer creates the expected releases and current layout

The same incompatibility has been reported upstream for Homebrew and OpenAI's downloadable package archive, so it is not specific to Nix.

Current Nixpkgs and llm-agents.nix do not create this layout. Some community configurations add a compatibility link. agent-box uses the closest match to the official installer's structure.

Home Manager workaround

The following example keeps the compatibility directory declarative and refreshes the executable whenever the Home Manager generation changes:

{ inputs, lib, pkgs, ... }:

let
  codexPackage =
    inputs.codex-cli-nix.packages.${pkgs.stdenv.hostPlatform.system}.default;
  managedCodex = pkgs.linkFarm "codex-managed-install" [
    {
      name = "codex";
      path = lib.getExe codexPackage;
    }
  ];
in
{
  home.packages = [ codexPackage ];

  home.file.".codex/packages/standalone/current".source = managedCodex;
}

This produces:

~/.codex/packages/standalone/
└── current -> /nix/store/...-codex-managed-install/
                  └── codex -> /nix/store/...-codex-0.150.1/bin/codex

If Codex is already installed through programs.codex, use that module's selected package as codexPackage and omit the duplicate home.packages entry. Do not enable this declaration if current is already owned by an official standalone Codex installation. Choose one owner for that path.

Guarded manual workaround

Users without Home Manager can create the same layout after installing Codex through a Nix profile:

codex_bin="$(command -v codex)"
standalone_root="${CODEX_HOME:-$HOME/.codex}/packages/standalone"
managed_dir="$standalone_root/codex-cli-nix-current"
current="$standalone_root/current"

if [ ! -x "$codex_bin" ]; then
  echo "Cannot find an executable Codex installation" >&2
  exit 1
fi

if [ -e "$current" ] || [ -L "$current" ]; then
  if [ ! -L "$current" ] || [ "$(readlink "$current")" != "codex-cli-nix-current" ]; then
    echo "Not replacing existing Codex standalone installation: $current" >&2
    exit 1
  fi
fi

mkdir -p "$managed_dir"
ln -sfn "$codex_bin" "$managed_dir/codex"

if [ ! -L "$current" ]; then
  ln -s codex-cli-nix-current "$current"
fi

If the current link was already created by this workaround, refresh the package-owned executable link after changing how Codex is installed. A Home Manager declaration handles that automatically.

Packaging boundary

I verified that this compatibility layout allows app-server daemon start, daemon version, daemon stop, and the full codex agents flow to work.

However, adding it implicitly to this flake's normal wrapper would make every Codex invocation mutate the user's home directory. It would also claim a path that the official installer considers its own. For that reason, an opt-in Home Manager declaration or explicit local setup is safer than an unconditional wrapper workaround.

There is one additional lifecycle distinction: codex agents uses daemon Start, which does not run the updater. The daemon's Bootstrap lifecycle can run OpenAI's standalone installer and replace the managed release. The behavior is documented in the app-server daemon README. Nix integrations should use Start, preserve Nix as the package owner, and avoid Bootstrap.

The durable upstream solution would be an explicit app-server executable override plus a package-manager mode that disables the standalone updater. This flake could then point the daemon directly at its packaged executable without managing files inside $CODEX_HOME.

[sadjow]

Upstream tracking update:

• openai/codex #41187 now tracks the exact codex agents failure for a Homebrew-managed installation. I added our support there rather than opening a duplicate bug.
• openai/codex #41188 requests the general package-manager contract identified above: an externally supplied app-server daemon executable plus an external ownership mode that prevents Bootstrap from running the standalone updater. It references this issue and the related Homebrew, npm, and archive reports.

I am leaving this issue open because the Nix package remains affected. The declarative Home Manager workaround above is currently the safest local option. Once upstream provides a supported executable and updater-policy hook, this flake can configure it without taking ownership of mutable files under $CODEX_HOME.

[sadjow]

Update for Codex 0.157 and later: codex agents now fails earlier, with the same error as #162:

Error: this CLI has no complete local package; install a packaged Codex CLI or use the standalone installer

The daemon now copies the package the CLI runs from into $CODEX_HOME/packages/app-server-daemon/, so the packages/standalone/current workarounds in my earlier comment no longer help. I tested that layout on 0.159.0 and codex agents still fails.

Starting the server manually still works on 0.159.0, as you originally found:

codex app-server --listen unix://

Then run codex agents in another terminal.

#165 switches this flake to OpenAI's complete package archive, which fixes #162. With that build, I confirmed on aarch64-darwin that codex agents starts the shared server by itself from a clean CODEX_HOME, so it should resolve this issue as well.

One part of my earlier comment still applies: the daemon's copy lives in CODEX_HOME, outside the Nix store, and Codex keeps its own update state for it there. openai/codex#41188 remains the place for a supported way to keep a package manager in charge of that copy.

[sadjow]

codex agents works again with #165, which is on main now. With the complete package, Codex can start its shared server, so codex agents no longer needs codex app-server started by hand. I tested it on aarch64-darwin from an empty CODEX_HOME. Closing, but reopen if it still fails after you update to the latest main.