Sprites for DeepSeek Harness

Use Sprites from DeepSeek Harness: isolated, persistent Linux environments for builds, tests, experiments, and long-running services.

This repository is a Harness bundle. Its cordis.patch.yml mounts:

• @deepseek-ai/dsh-mcp-client, connected to the hosted Sprites MCP server.
• This package's index.js entry, which mounts @deepseek-ai/dsh-skill-filesystem against the packaged Sprites workflow skill.

The result is a native Cordis composition: Sprites tools appear as mcp__sprites__*, and the Sprites skill is discoverable through Harness's normal skill system.

Requirements

• Node.js 20.19 or newer. The packaged filesystem provider currently depends on Chokidar 5, whose engine floor is Node 20.19.
• DeepSeek Harness developer preview.
• Browser access for the first Sprites OAuth authorization.
• Network access for npx to run the pinned mcp-remote@0.1.38 OAuth bridge.

Harness's current Streamable HTTP MCP transport accepts static headers but does not perform MCP OAuth. This bundle therefore uses Harness's supported stdio transport and mcp-remote to complete the standard browser OAuth flow without requiring a Sprites API token.

Install

Install the GitHub checkout into the profile you use. For the built-in Web profile:

npx @deepseek-ai/dsh plugin --profile web add github:superfly/sprites-deepseek-plugin

Then start that profile:

npx @deepseek-ai/dsh --profile web

On first connection, complete the browser OAuth flow, choose the Fly.io organization, and review the connector access policy. Restart Harness once if the initial tool synchronization timed out while you were authorizing.

For local development from this repository:

npx @deepseek-ai/dsh plugin --profile web add .
npx @deepseek-ai/dsh --profile web

To try the layer without installing it into a profile:

npx @deepseek-ai/dsh web --patch ./cordis.patch.yml

Verify the installed bundle and composed rows without booting the UI:

npx @deepseek-ai/dsh --profile web --dump-config

The output should include the dsh-sprites-plugin layer, sprites-mcp, and sprites-skill-filesystem.

First prompts

• "List my sprites."
• "Create a sprite for this experiment and run uname -a in it."
• "Create a checkpoint, then run the test suite in my sprite."
• "Start the web service in my sprite and give me its URL."

An empty sprite list is a successful authenticated response.

Authentication and access

The hosted endpoint is https://sprites.dev/mcp and uses OAuth 2.1. mcp-remote stores its OAuth state in its normal local credential directory; this repository contains no credentials.

The Sprites consent screen normally creates a restricted connector token. Its default name prefix is often mcp-, and it may cap how many sprites the connector can create. A custom non-empty prefix remains restricted. Choosing Full access removes the prefix restriction but grants access to every sprite in the organization.

Prefer restricted access for agent work. If a create call reports a required prefix, Harness should retry once with that exact prefix and report the actual name.

How it works

cordis.patch.yml contributes two rows:

1. sprites-mcp starts mcp-remote through the Harness MCP client. The bridge handles OAuth and exposes server tools through ctx.tools as mcp__sprites__<tool>.
2. sprites-skill-filesystem loads this package's index.js. The entry resolves skills/ from import.meta.url, then mounts @deepseek-ai/dsh-skill-filesystem as an isolated provider. This is intentionally done in JavaScript: a bundle patch is evaluated with the profile directory as its baseUrl, not the installed package directory.

The MCP subprocess also sends fixed, privacy-safe client attribution headers:

Header	Value
Fly-Client-Agent	deepseek-harness
Fly-Client-Interactive	false

No user-, machine-, repository-, or session-specific attribution is sent. The headers are advisory analytics only and are not used for authorization or rate limiting.

mcp-remote includes both the server URL and serialized headers in its OAuth cache key. Changing either attribution header therefore invalidates existing cached authorization and requires users to authenticate again.

Safety

• Treat services exposed through a sprite URL as potentially internet-accessible.
• Never publish secrets, environment dumps, arbitrary files, debug endpoints, or unfiltered logs.
• Use a checkpoint before risky filesystem changes, dependency upgrades, or migrations.
• Destroying a sprite is irreversible. Only destroy one when the user explicitly asks to delete, destroy, or remove it, or approves cleanup.
• Inspect outbound network policy before changing it.

Troubleshooting

Tools are missing

Confirm the bundle appears in --dump-config and that both Cordis rows are present. Harness's MCP client logs connection, discovery, and tool-registration failures. The native tool names begin with mcp__sprites__.

OAuth did not finish

Keep the Harness process running while completing the browser flow. If initial synchronization times out, finish authorization and restart Harness; mcp-remote reuses the stored OAuth session.

For persistent mcp-remote authentication state problems, follow its upstream troubleshooting guidance. Clearing its credential directory signs every mcp-remote connector out, so do not do that casually.

npx cannot start

Make sure Node.js 20.19+ and npx are available in the environment that launches Harness. The MCP client intentionally uses argument arrays without shell interpolation.

Network failures inside a sprite

Ask Harness to inspect the sprite's network policy before changing it. A reachable MCP server does not imply unrestricted egress inside a sprite.

Repository layout

package.json                 Harness bundle manifest (`dsh.bundle`)
cordis.patch.yml             Cordis rows for MCP and packaged skills
index.js                     Package-relative Sprites skill provider entry
skills/sprites/              DeepSeek Harness Sprites skill and references
scripts/check_repository.py  Static repository validation
tests/test_repository.py     Bundle contract tests

Development

python -m pip install -r requirements-dev.txt
npm install --ignore-scripts --package-lock=false
ruff check .
ruff format --check .
python scripts/check_repository.py
python -m unittest discover -s tests -v
node scripts/check_skill_entry.mjs

Related

• DeepSeek Harness plugin development
• DeepSeek Harness package and install guide
• Sprites remote MCP documentation
• Sprites MCP server repository
• mcp-remote

Support and feedback

• Report reproducible plugin bugs with the bug report form.
• Propose workflow or integration improvements with the feature request form.
• Ask general Sprites questions in the Fly.io community after checking the Sprites documentation.
• Report security issues privately as described in SECURITY.md. Never include credentials or production data in an issue.

Project policies

See CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, SUPPORT.md, and CHANGELOG.md.

License

MIT © Fly.io, Inc.