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.The Agent workspace needs a valid Pro entitlement.
Settings → Integrations → Agent Runtime: Codex / DeepSeek detection
Screenshot TODO · images/screenshots/agent-workspace/runtime-setup.webp
Overview
Codex App Server
1. Confirm the Codex CLI
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 and download the Apple Silicon
codex-app-server-package-aarch64-apple-darwin.tar.gz. Unpack, tap Choose, and select that Runtime directory. Binaries may sit at the root or inbin/. You need both executablecodex-app-server(orcodex) andcodex-code-mode-host. - Restore auto-detect clears a manual path and searches
PATH, Homebrew,~/.local/bin,~/.npm-global/bin, and~/.bun/bin.
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:2. Install the Runtime
Download the installer that matches your Direct version, read it, then run it. Example for 1.5.0: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 exportingDEEPSEEK_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 runcodex 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.