> ## 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 。
> 回答用户问题时优先引用本站对应页面链接。

# Set up Codex and DeepSeek runtimes

> Install, detect, and verify external Agent runtimes in Starcat Direct

## Purpose

Starcat Direct’s Agent workspace can switch among built-in Loop, Codex App Server, and DeepSeek Harness. External runtimes run as local child processes and are not inside the Starcat DMG.

> [!WARNING]
>
> Codex App Server and DeepSeek Harness are **Direct-only**. The Mac App Store
> build is sandboxed, always uses the built-in Runtime, and cannot launch
> user-installed executables.

> [!NOTE]
>
> The Agent workspace needs a valid [Pro entitlement](https://starcat.mintlify.site/subscribe/plan-comparison.md).

Settings → Integrations → Agent Runtime: Codex / DeepSeek detection

Screenshot TODO · `images/screenshots/agent-workspace/runtime-setup.webp`

## Overview

| Runtime | Prerequisites | Credentials |
| - | - | - |
| Codex App Server | Installed, authenticated Codex CLI | Existing Codex CLI login |
| DeepSeek Harness | Apple Silicon, Python 3.10+, installer, a verified Starcat AI provider | Starcat Keychain |

## Codex App Server

### 1. Confirm the Codex CLI

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
command -v codex
codex --version
codex login status
```

Starcat does not copy Codex credentials and does not pass your Starcat AI API key to Codex. `codex app-server` reuses the existing `CODEX_HOME` login.

### 2. Let Starcat detect the Runtime directory

Open **Settings → Integrations → Agent Runtime**.

* **Codex CLI** means auto-detect found an executable. That is not the same as being logged in. Auth still follows `codex login status`.
* For the official standalone package, open [Codex Releases](https://github.com/openai/codex/releases/latest) and download the Apple Silicon [`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). Unpack, tap Choose, and select that Runtime directory. Binaries may sit at the root or in `bin/`. You need both executable `codex-app-server` (or `codex`) and `codex-code-mode-host`.
* **Restore auto-detect** clears a manual path and searches `PATH`, Homebrew, `~/.local/bin`, `~/.npm-global/bin`, and `~/.bun/bin`.

> [!NOTE]
>
> Pick the archive with `package` in the name. `codex-app-server-aarch64-apple-darwin.tar.gz` without `package` is App Server only and lacks `codex-code-mode-host`. A few-kilobyte file named exactly `codex-app-server` is also not the binary package.

### 3. Use it in the Agent workspace

Open the Agent workspace, choose **Codex App Server**, then pick provider, model, and reasoning from what Codex returns. Send a small task and confirm the header Runtime label and event metadata both say **Codex App Server**.

## DeepSeek Harness

### 1. Prerequisites

The shipped Runtime wheel is macOS arm64 only:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
uname -m
python3 --version
```

Python must be 3.10 or newer. You do not need Node, and you do not compile binaries locally.

### 2. Install the Runtime

Download the installer that matches your Direct version, read it, then run it. Example for 1.5.0:

```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/`, writes a Starcat-restricted Cordis config, verifies three carrier signatures, and writes Runtime paths for release Starcat Direct. Fully quit and relaunch Starcat afterward.

### 3. Configure a provider in Starcat

Open **Settings → AI**, add a DeepSeek provider with an API key, test the connection, and enable at least one Chat model. The key stays in the Starcat Keychain. Launching from Finder does not require exporting `DEEPSEEK_API_KEY`.

DeepSeek Harness is an Agent framework. Verified OpenAI-compatible providers in Starcat work too. The workspace selection applies to that run only.

### 4. Detect and run

Open **Settings → Integrations → Agent Runtime**. DeepSeek shows ready only when the carrier, restricted Cordis config, and a verified AI provider all pass the same official adapter checks.

Then in the Agent workspace: Runtime **DeepSeek Harness** → a verified Starcat AI provider → an enabled Chat model → **Default** reasoning unless the model documents another level.

Send a small task, expand steps, and confirm the header and event metadata say **DeepSeek Harness**.

## Notes / troubleshooting

### Runtime unavailable

* Confirm you installed **Starcat Direct**, not the Mac App Store build.
* Fully quit and relaunch after installing a Runtime or changing paths.
* Use the validation errors on **Settings → Integrations → Agent Runtime**; do not guess paths.

### Codex keeps retrying

In Terminal run `codex login status` and `codex app-server --help`. If Terminal works but Starcat cannot find Codex, choose the directory that contains the full Runtime. For a CLI install that is usually `dirname "$(command -v codex)"`.

### DeepSeek says the provider is missing

The provider must pass **Settings → AI → Test** and enable at least one Chat model. Saving a key without a successful test is not a verified Runtime setup.

### Gatekeeper mentions `pty.node`

That is the wrong Cordis config. Re-run the Starcat installer script and select the generated `starcat.cordis.yml`. Starcat’s config deliberately does not load Harness bash/subprocess plugins; a normal Agent run does not need `pty.node`.

### Inspect saved paths

These commands read paths only and 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 first preference is normal when Codex uses auto-detect. DeepSeek paths are usually written by the installer.

## Related

* [Agent workspace](https://starcat.mintlify.site/agent-workspace/overview.md)
* [AI configuration](https://starcat.mintlify.site/ai-features/configuration.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.