Sprites for Cortex Code

Use Sprites from Snowflake Cortex Code as persistent, isolated Linux environments for builds, tests, sandboxes, previews, and Snowflake development workflows.

This Cortex Code plugin connects to the hosted Sprites MCP server with browser OAuth. It also contributes operating guidance, a long-work runner agent, a safety hook, and read-only status and end-to-end smoke commands. No Sprites CLI or pasted API token is required.

Install

Requirements

• Cortex Code CLI with plugin and remote HTTP MCP support.
• A Fly.io account with access to a Sprites organization.
• A browser available for the first-run OAuth flow.

Install from GitHub and enable the plugin:

cortex plugin install superfly/sprites-cortex-plugin
cortex plugin enable sprites

Run /plugin reload inside an existing session or restart Cortex Code. Both workflows are documented in the Cortex Code plugin guide.

For local development from a checkout instead:

cortex --plugin-dir /path/to/sprites-cortex-plugin

First use

1. Run /sprites-status or ask Cortex Code to list your Sprites.
2. Open /mcp if authorization is requested.
3. Authenticate with Fly.io, select the intended organization, and review the connector's name-prefix, creation-cap, and access settings.
4. Treat an empty list as success: the connector is authenticated and no Sprites are visible under its policy.

The explicit OAuth authorization-server URL in .mcp.json is intentional. The MCP endpoint's unauthenticated 401 response currently omits WWW-Authenticate, so Cortex cannot reliably discover the authorization server from that response alone.

What it provides

• Hosted MCP access at https://sprites.dev/mcp.
• Persistent, isolated Linux compute without treating the local Cortex shell as the Sprite.
• Guidance for commands, services, files, checkpoints, and network policy.
• sprites-runner, a bounded-output agent for long builds and tests.
• A PreToolUse hook that gates destructive, restore, policy, exposure, and broad persistent operations.
• Snowflake-aware boundaries for SQL, RBAC, stages, credentials, and governed data.
• /sprites-status for a read-only integration check.
• /sprites-smoke for list, create, and exec; the created Sprite is kept unless cleanup was explicitly requested and confirmed.

Example prompts

• "Create a Sprite for this dbt Core project and run compilation and unit tests."
• "Use the sprites-runner agent to build this Snowpark wheel for every supported Python version."
• "Run generated migration code in a checkpointed Sprite before we review it."
• "Start this Streamlit project as a Sprite preview, without copying production data."
• "List the services and recent logs on my integration-test Sprite."

How Cortex Code and Sprites divide the work

Cortex Code's local and Snowflake-native tools remain responsible for project editing, SQL, RBAC, catalog inspection, stages, and deployments. Sprites provide remote Linux execution for dependency-heavy, persistent, generated, or untrusted workloads.

The plugin does not copy Cortex's Snowflake session or credentials into a Sprite. If an integration test must connect from a Sprite, configure a separate least-privileged identity intentionally and keep governed data in Snowflake.

OAuth restrictions

Restricted connector tokens use a non-empty Sprite-name prefix and may cap how many Sprites the connector can create. The common default is mcp-, but the plugin learns the actual rule from the API instead of assuming it.

Full access removes the prefix by granting control over every Sprite in the organization. Prefer restricted access for day-to-day agent work. See the Sprites Remote MCP documentation for the live connector contract.

Safety

• Destroying a Sprite is irreversible.
• Restoring a checkpoint discards newer filesystem state.
• Network-policy updates replace the full policy.
• Services with an HTTP port can expose content through the Sprite URL.
• Checkpoint before risky package installs, migrations, bulk edits, and generated-code execution.
• Never expose secrets, environment dumps, arbitrary files, raw logs, or Snowflake data through a Sprite service.

Cortex Code's normal MCP permission flow still applies. The plugin hook adds a policy check; it does not weaken or auto-approve Cortex permissions. The hook intentionally evaluates every mcp__sprites__* call, including read-only calls, so a new or renamed destructive tool cannot bypass the guard. This adds one prompt-hook model evaluation per Sprites call, with a 30-second hook timeout. Organizations can further restrict the plugin and https://sprites.dev/mcp through connection profiles and managed settings.

Long-running work and output

The plugin sets a five-minute MCP call timeout. Work that might outlast it should use a Sprite service or detached process and bounded polling instead of one blocking exec. Cortex also caps MCP tool results at 50 KB, so verbose output should remain in a Sprite log file while Cortex receives a summary and small failure excerpt.

Enterprise deployment

Plugin-declared MCP servers can be disabled by administrators. Managed environments should allow https://sprites.dev/mcp and may distribute the plugin or an equivalent MCP definition through a Snowflake connection profile. Cortex Extensions can also store plugins with role-governed access.

Troubleshooting

If tools are missing:

1. Confirm sprites is active with cortex plugin list or /plugin.
2. Run /plugin reload in the active session or restart Cortex Code.
3. Inspect /mcp for the sprites server and its last error.
4. Ask whether administrator settings disable plugin MCP servers or block the endpoint URL.

If OAuth is stale, remove and reinstall the plugin-provided MCP configuration through the supported Cortex plugin/MCP flow, then authenticate again. Do not install the Sprites CLI, add a duplicate MCP server, or paste tokens into a shell.

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.

Development

python3 scripts/check_repository.py
python3 -m unittest discover -s tests -v
cortex plugin validate

The first two checks are dependency-free. The final check requires Cortex Code CLI. Before a release, also complete the live contract checklist.

Repository layout

.cortex-plugin/       Cortex manifest and inactive-plugin activation text
.mcp.json             Hosted Sprites MCP and OAuth configuration
agents/               Long-running Sprites runner
commands/             /sprites-status and /sprites-smoke
hooks/                PreToolUse safety policy
skills/sprites/       Core operating guidance and Snowflake references
assets/               Sprites logo
docs/                 Release and live-contract checklist
scripts/              Repository validation
tests/                Semantic and structural tests

Project policies

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

License

MIT © Fly.io, Inc.