Codex and DeepSeek runtimes

Configure external Agent runtimes in Starcat Direct 1.5.0

Starcat 1.5.0 supports three interchangeable Agent runtimes: the built-in Loop, Codex App Server, and DeepSeek Harness. External runtimes run as local child processes and are not bundled in the Starcat DMG.

Codex App Server and DeepSeek Harness are available in Starcat Direct only. The Mac App Store build always uses the built-in runtime because its sandbox cannot launch user-installed executables.

Agent Workspace requires an active Pro entitlement.

At a glance

Runtime	What you need	Credential source
Codex App Server	Installed and authenticated Codex CLI	Existing Codex CLI login
DeepSeek Harness	Apple Silicon, Python 3.10+, runtime installer, verified Starcat AI Provider	Starcat Keychain

Codex App Server

1. Verify Codex CLI

This guide assumes Codex CLI is already installed and authenticated:

command -v codex
codex --version
codex login status

Starcat does not copy the Codex credential or pass a Starcat AI Provider key to Codex. It launches codex app-server with the same local CODEX_HOME login state.

2. Let Starcat find the Runtime directory

Open Settings → Integrations → Agent Runtime.

• If Codex shows Codex CLI, automatic detection found the installed CLI. That status only means the executable was found, not that you are logged in. codex login status remains the source of truth.
• To use the official standalone package, open Codex Releases and download the Apple Silicon archive codex-app-server-package-aarch64-apple-darwin.tar.gz. After extracting it, click Choose and select that Runtime directory. Starcat accepts binaries directly in the directory or in its bin/ subdirectory. The package must contain executable codex-app-server (or codex) and codex-code-mode-host.
• Use Automatic Detection clears a manually configured path and searches PATH, Homebrew, ~/.local/bin, ~/.npm-global/bin, and ~/.bun/bin again.

Download the archive whose name includes package. codex-app-server-aarch64-apple-darwin.tar.gz contains only the App Server binary and is missing codex-code-mode-host. Also skip the few-kilobyte asset named exactly codex-app-server.

3. Run it

Open Agent Workspace, choose Codex App Server, then select a provider, model, and reasoning effort offered by Codex. Send a small request first and confirm that the Runtime badge and execution events both say Codex App Server.

DeepSeek Harness

1. Verify prerequisites

The provided runtime wheel currently supports macOS arm64 only. Check Python:

uname -m
python3 --version

Use Python 3.10 or later. No Node installation or local binary compilation is required.

2. Install the runtime

Download the installer shipped with Starcat 1.5.0, inspect it, and then run it:

curl -fL \
  https://raw.githubusercontent.com/starcat-app/Starcat/v1.5.0/scripts/install-deepseek-harness-runtime.sh \
  -o /tmp/install-starcat-deepseek-runtime.sh
less /tmp/install-starcat-deepseek-runtime.sh
bash /tmp/install-starcat-deepseek-runtime.sh

The script installs deepseek-harness-runtime-bin==0.1.1rc1 under ~/Library/Application Support/Starcat/Runtimes/, creates Starcat’s restricted Cordis configuration, verifies the three carrier signatures, and writes the production Starcat Direct Runtime paths. Restart Starcat after the script finishes.

3. Configure a Provider in Starcat

Open Settings → AI and add a DeepSeek Provider with your API key. Run the connection test and enable at least one Chat model. The key remains in Starcat’s Keychain; you do not need to export DEEPSEEK_API_KEY before launching the app.

DeepSeek Harness is the Agent framework, not a provider lock. It can also use a verified OpenAI-compatible Provider configured in Starcat. The Provider and model selected in Agent Workspace are injected only for that run.

4. Verify and run

Open Settings → Integrations → Agent Runtime. DeepSeek is ready only when the carrier, restricted Cordis config, and a verified AI Provider all pass the same checks used by a real run.

Then open Agent Workspace and choose:

1. Runtime: DeepSeek Harness
2. Provider: a verified Starcat AI Provider
3. Model: an enabled Chat model from that Provider
4. Reasoning: Default unless the selected model exposes another supported level

Send a small request and expand the execution steps. The Runtime badge and event metadata should both say DeepSeek Harness.

Troubleshooting

Runtime unavailable

• Confirm you installed Starcat Direct, not the Mac App Store build.
• Restart Starcat after installing or changing Runtime paths.
• Open Settings → Integrations → Agent Runtime and use the displayed validation error instead of guessing which path failed.

Codex keeps retrying

Run codex login status, then codex app-server --help in Terminal. If Terminal works but Starcat cannot find Codex, choose the directory containing the complete Runtime package. For a CLI installation, this is normally dirname "$(command -v codex)".

DeepSeek reports a missing Provider

The Provider must pass Settings → AI → Test and have an enabled Chat model. Saving an API key without a successful test is not considered a verified Runtime configuration.

Gatekeeper mentions pty.node

The wrong Cordis configuration is being used. Re-run the Starcat installer and select the generated starcat.cordis.yml. Starcat’s configuration deliberately does not load the Harness bash/subprocess plugins, so a normal Agent run does not need pty.node.

Inspect saved paths

These commands show paths only; they do not print API keys:

defaults read com.starcat.app.direct AgentRuntimeCodexExecutablePath
defaults read com.starcat.app.direct AgentRuntimeDeepSeekHarnessExecutablePath
defaults read com.starcat.app.direct AgentRuntimeDeepSeekHarnessCordisConfigPath

A missing Codex preference is valid when automatic detection is in use. DeepSeek paths are normally written by the installer.