diff --git a/sources/platform/integrations/ai/deepseek-harness.md b/sources/platform/integrations/ai/deepseek-harness.md new file mode 100644 index 0000000000..9b11365623 --- /dev/null +++ b/sources/platform/integrations/ai/deepseek-harness.md @@ -0,0 +1,206 @@ +--- +title: DeepSeek Harness integration +sidebar_label: DeepSeek Harness +description: Learn how to install the Apify plugin for DeepSeek Harness to discover, run, and build Actors with the Apify MCP server and bundled workflow skills. +slug: /integrations/deepseek-harness +--- + +import ThirdPartyDisclaimer from '@site/sources/_partials/_third-party-integration.mdx'; + +[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`) is DeepSeek's open-source agent harness. It boots a profile, an ordered stack of plugin layers. It then runs the agent in your terminal or in a local web GUI, backed by the model provider you configure. + +The [Apify plugin for DeepSeek Harness](https://www.npmjs.com/package/dsh-apify-plugin) connects `dsh` to Apify's library of [Actors](https://apify.com/store) and bundles: + +- The [Apify MCP server](/integrations/mcp) for searching Apify Store, running Actors, and retrieving datasets through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro). +- An `apify` router skill that turns a natural-language request into the right tool or skill, and diagnoses missing authentication. +- Five workflow skills for common tasks (see [Bundled skills](#bundled-skills)). + + + +## Prerequisites + +- [An Apify account](https://console.apify.com/sign-up) - sign up for free if you don't have one. +- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) - installed locally, running Node.js `^22.19.0 || >=24.0.0`. Older versions fail with a `node:sqlite` error. +- [pnpm](https://pnpm.io/installation) on your `PATH` - `dsh plugin` forwards its arguments to pnpm. +- A model provider configured in `dsh` - see [Connect a model provider](#connect-a-model-provider). +- [The Apify CLI](/cli/docs/installation) - required only for the Actor development, actorization, and ultimate scraper skills. + +:::note Most work needs no local CLI + +The Apify MCP server covers Apify Store search and platform runs, so nothing has to be installed locally for them. Install the CLI only for the three skills noted above. + +::: + +## Install the plugin + +Install the plugin into the profile you launch. The `web` profile backs the web GUI (`dsh web`), and `headless` answers a single task in the terminal and exits: + +```bash +dsh plugin --profile web add dsh-apify-plugin +``` + +If you run `dsh` through npx rather than a global install, prefix the command: + +```bash +npx @deepseek-ai/dsh plugin --profile web add dsh-apify-plugin +``` + +To uninstall: + +```bash +dsh plugin --profile web remove dsh-apify-plugin +``` + +:::note Install into every profile you use + +A profile gets the plugin only if you add it there. To use the terminal as well, repeat the command with `--profile headless`, then run a one-off task: + +```bash +dsh --profile headless "Find an Actor for scraping Google Maps places" +``` + +::: + +## Connect your Apify account + +The plugin enables the Apify MCP server on install. Searching Apify Store, inspecting Actors, and reading the Apify documentation work without a token. Running Actors, reading datasets and key-value stores, and retrieving run data need one. + +`dsh` sends static MCP headers and has no OAuth flow, so authenticate with an API token: + +1. Copy your token from [Apify Console > Settings > Integrations](https://console.apify.com/settings/integrations?utm_source=deepseek-harness&utm_medium=integrations). + +1. Create a `.env` file in the directory you launch `dsh` from: + + ```bash + # .env + APIFY_TOKEN= + ``` + +1. Restart the profile. + +:::tip Where the token is read from + +`dsh` reads `.env` from the launch directory only, without searching parent directories. A `.env` in the harness home (`~/.dsh` by default, or `$DSH_HOME` if you set it) acts as a machine-wide fallback, and a variable already exported in your shell takes precedence over both. Add `.env` to your `.gitignore` so the token stays out of version control. + +::: + +`dsh` reads the token once, at startup. Exporting it inside a running session has no effect, so restart the profile after you change it. + +## Start the profile + +```bash +dsh web +``` + +Open the URL `dsh` prints. It carries a one-time token, so the bare address doesn't authenticate. + +On first launch, no workspace exists. Select **Add workspace** in the workspace menu and choose the folder you want the agent to work in. + +## Connect a model provider + +`dsh` ships no model of its own. Open **Settings > Models**, select **Add provider**, choose your provider, and supply its API key. DeepSeek has a card there from the start; other providers you add yourself. Keys saved here live in `~/.dsh/.credentials.yaml` and take effect without a restart. + +For a model served on your own machine, such as LM Studio or Ollama, select **Add a custom provider** and enter the URL and port it listens on. + +To set a DeepSeek key before launch instead, put `DEEPSEEK_API_KEY` in the same `.env` file as `APIFY_TOKEN`. + +## Run your first prompt + +Describe what you want in natural language. The `apify` skill loads on Apify requests and routes them, so you don't need to name tools yourself. + +> Use Apify to find a good Actor for scraping Google Maps places. Show me the best option, its input requirements, pricing model, and what kind of dataset output it returns. Do not run the Actor yet. + +The router searches Apify Store, fetches the top Actor's details through the Apify MCP server, and summarizes its inputs, pricing, and output - all without running the Actor. + +## Bundled skills + +| Skill | Description | +| --- | --- | +| `apify` | Routes each request to the right tool or skill and diagnoses authentication problems. | +| `apify-ultimate-scraper` | Extracts data with existing Actors for multi-step scraping and lead-generation workflows. | +| `apify-actor-development` | Covers the full Actor lifecycle - template selection, development, local testing, and deployment with `apify push`. | +| `apify-actorization` | Converts existing JavaScript, TypeScript, Python, or CLI projects into Apify Actors. | +| `apify-generate-output-schema` | Generates dataset and key-value store schemas for existing Actors. | +| `apify-sdk-integration` | Integrates Actor execution into applications using the `apify-client` package. | + +Example prompts that route to specific skills: + +_Ultimate scraper:_ + +> Find 10 highly rated coffee shops in Seattle with name, address, rating, phone, and website. + +_Actor development:_ + +> Create an Apify Actor that accepts a `startUrl` and `maxPages` input, crawls the site, and stores each page title and URL. + +_SDK integration:_ + +> Add Apify to this project. The Node.js API route should run an Actor and return dataset items as JSON. + +## Install the Apify CLI + +The Actor development, actorization, and ultimate scraper skills call the local `apify` command, so install the [Apify CLI](/cli/docs/installation) before using them: + +```bash +npm install -g apify-cli +``` + +### Grant the Apify CLI file access + +The CLI keeps its credentials in `~/.apify/`, which sits outside the session workspace. Under the default `workspace-write` sandbox mode, `dsh` denies that path and every `apify` command fails with `EPERM`, even when the login itself is valid. + +You have two ways to work around this: + +- Approve the escalation prompt that the agent raises when a command is denied. It applies to that one command. +- Switch the session to **Full access** in the permission menu, which reads **Workspace Write** by default. You can switch at any point, and the change takes effect on the next command the agent runs. + +To change the default mode for new sessions, use **Settings > General > Permission**. + +If you'd rather keep the sandbox narrow, set `APIFY_TOKEN` instead and let the agent run Actors through the Apify MCP server, which needs no local file access. + +## Troubleshooting + +The failures below cover missing or invalid tokens, sandbox denials, and profile mismatches. + +### The agent says it can't run an Actor + +No `APIFY_TOKEN` was set when `dsh` started, so only the anonymous MCP tools loaded and the agent can search but not run. Add the token to your `.env` file and restart the profile. See [Connect your Apify account](#connect-your-apify-account). + +### The Apify MCP server fails to start with `invalid_token` + +The token is present but rejected. Check for stray quotes or trailing whitespace in the `.env` file, regenerate the token in [Apify Console > Settings > Integrations](https://console.apify.com/settings/integrations?utm_source=deepseek-harness&utm_medium=integrations) if needed, and restart the profile. + +### The `apify` command fails with `EPERM` + +The sandbox is blocking `~/.apify/`, not your login, so running `apify login` again won't fix it. See [Grant the Apify CLI file access](#grant-the-apify-cli-file-access). + +### The plugin doesn't show up after installing + +Print the composed profile tree and confirm the plugin's rows are in it: + +```bash +dsh --profile web --dump-config +``` + +Check that you installed into the profile you actually launch. Installing into `web` doesn't affect `headless`, and the reverse. + +## Limitations + +- `dsh` sends static MCP headers and has no OAuth flow, so the Apify MCP server authenticates with an API token only. +- `dsh` reads the token at startup, so a change to `.env` needs a restart of the profile. +- The plugin raises the MCP tool call timeout from the `dsh` default of 60 seconds to 5 minutes. Longer runs need a narrower scope, or the Apify CLI to start the run and poll for its result. +- Each Actor run consumes Apify platform usage from your plan in addition to any model provider costs. See [Billing](/account/billing) for details. +- Skills that edit files in your project (Actor development, actorization, and SDK integration) make local changes - review them before deploying or committing. + +## Related integrations + +- [MCP server integration](/integrations/mcp) - The same MCP server with other clients +- [Kimi Code CLI integration](/integrations/kimi-code-cli) - The equivalent plugin for Kimi Code CLI +- [OpenCode integration](/integrations/opencode) - The equivalent plugin for OpenCode + +## Resources + +- [Apify plugin for DeepSeek Harness](https://www.npmjs.com/package/dsh-apify-plugin) - Plugin package and setup notes +- [DeepSeek Harness repository](https://github.com/deepseek-ai/deepseek-harness) - Source, profiles, and plugin packaging docs +- [Apify MCP server documentation](/integrations/mcp) - Tools, authentication, and configuration +- [Apify Store](https://apify.com/store) - Actors you can run from DeepSeek Harness diff --git a/sources/platform/integrations/ai/index.mdx b/sources/platform/integrations/ai/index.mdx index eb7047c664..fce247bc24 100644 --- a/sources/platform/integrations/ai/index.mdx +++ b/sources/platform/integrations/ai/index.mdx @@ -211,6 +211,13 @@ Chat and coding assistants you connect to Apify through the Apify MCP server or imageUrl="/img/platform/integrations/qwen.svg" smallImage /> + ## By provider diff --git a/sources/platform/integrations/index.mdx b/sources/platform/integrations/index.mdx index ff4987a06b..eb7f3143f1 100644 --- a/sources/platform/integrations/index.mdx +++ b/sources/platform/integrations/index.mdx @@ -171,6 +171,13 @@ Plug Apify Actors into the AI stack - chat clients like Claude and ChatGPT via t imageUrlDarkTheme="/img/platform/integrations/vscode-white.svg" smallImage /> + [See all AI integrations →](/integrations/ai) diff --git a/static/img/platform/integrations/deepseek.svg b/static/img/platform/integrations/deepseek.svg new file mode 100644 index 0000000000..54f14c03d5 --- /dev/null +++ b/static/img/platform/integrations/deepseek.svg @@ -0,0 +1 @@ +DeepSeek