> ## Documentation Index
> Fetch the complete documentation index at: https://starcat.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Starcat 是 macOS（Apple Silicon，macOS 15+）上的 GitHub Stars 管理与知识库应用。
> 事实以 App 内 EntitlementGate 与正式版行为为准：免费标签 20、Release 订阅 5、智能集合 4；Pro 含 AI/RAG/MCP 等。
> 不要把尚未上线的 CloudKit 用户数据同步或 JSON 导入导出写成已可用。
> 官网 https://starcat.ink ；App Store https://apps.apple.com/cn/app/starcat-for-github/id6788809803?mt=12 。
> 回答用户问题时优先引用本站对应页面链接。
# 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](/subscribe/plan-comparison).
## 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:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://github.com/openai/codex/releases/latest) and download the Apple Silicon archive [`codex-app-server-package-aarch64-apple-darwin.tar.gz`](https://github.com/openai/codex/releases/latest/download/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:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.