Symbioza README

Symbioza

Run fine-tuning, evaluation and batch-inference jobs on a cloud GPU from Claude Code, under a hard spending limit. Your agent prepares the job, shows you a free estimate, and submits it only when you say so. Symbioza picks the machine, runs the job and returns the files it writes. You are never billed more than the spending limit you set.

How it works: your agent describes the job, gets a free estimate, submits with a total spending limit, Symbioza runs it on a cloud GPU, and the files the run wrote come back. You are never billed more than your budget.

What the plugin adds

Symbioza runs a containerized GPU job on a rented cloud machine under a hard dollar ceiling and collects available artifacts. An agent submits an image, a command and a budget through one MCP connector. Symbioza selects compute, runs the job and reports output delivery and billing separately. Recovery depends on job policy, available compute, remaining budget and compatible checkpoint support.

A hosted MCP server at https://symbioza.dev/mcp (streamable HTTP, sign-in with OAuth, no API key). Its nine tools: estimateExecution, submitJob, getStatus, inspectRun, getArtifact, listJobs, listSecrets, describeDataset, cancelJob.
One skill, /symbioza:run-on-symbioza. It tells your agent when a job fits Symbioza, what to ask you, and the four calls from spec to files: estimate, submit, status, artifact.

For agents deciding whether a job fits: https://symbioza.dev/agent

VS Code, GitHub Copilot and other MCP clients

You do not need the plugin to use Symbioza: the server is the same remote MCP endpoint, https://symbioza.dev/mcp. Any client that supports remote Streamable HTTP MCP with an OAuth sign-in connects to it. If the client asks for headers or an API key, leave them empty: you sign in in your browser the first time the client connects.

In VS Code, run MCP: Add Server from the Command Palette, or add this to .vscode/mcp.json:

config.json

{
  "servers": {
    "symbioza": { "type": "http", "url": "https://symbioza.dev/mcp" }
  }
}

Then ask for a free estimate (step 4). Setup for ChatGPT, Claude.ai and other clients: https://symbioza.dev/plugins

Cursor

Choose one of the two, not both, or your agent sees every tool twice.

Connect directly. Add the server to ~/.cursor/mcp.json (every project) or to .cursor/mcp.json in one project, merging it into any mcpServers block already there:

config.json

{
  "mcpServers": {
    "symbioza": { "url": "https://symbioza.dev/mcp" }
  }
}

Open Customize in the sidebar, enable symbioza under MCPs, and finish the sign-in in the browser. This gives your agent the nine tools; it does not install the run-on-symbioza skill and needs no marketplace listing.

Install the plugin. Copy this repository to ~/.cursor/plugins/local/symbioza (a real copy: Cursor skips a symlink that points outside that directory), restart Cursor or run Developer: Reload Window, then confirm in Customize that the run-on-symbioza skill and the symbioza MCP server are listed. Enable the server and finish the sign-in in the browser; invoke the skill with /run-on-symbioza. A team policy may block local plugin imports. Sign-in, usage, costs and a test checklist: docs/cursor.md.

1. Install

Steps 1 to 3 and the update commands are for Claude Code. Cursor: see the section above.

Terminal

claude plugin marketplace add symbioza/claude-plugin
claude plugin install symbioza@symbioza

Or both at once from inside a Claude Code session (Claude Code v2.1.275 or later): /plugin install symbioza --marketplace symbioza/claude-plugin. Tested with Claude Code 2.1.283.

From the shell, the install ends with Successfully installed plugin: symbioza@symbioza: start a new Claude Code session to use it. Installed from inside a session, Claude Code says either Plugin is now active. or Run /reload-plugins to activate. (then run /reload-plugins).

2. Sign in

The connector needs signing in once before its tools appear. Run /mcp, select plugin:symbioza:symbioza and choose Authenticate: your browser opens to sign in with Google, GitHub or an email address. There is no key to generate and none to send.

3. Check it's connected

You are ready when all three hold:

/mcp lists plugin:symbioza:symbioza as connected, with nine tools.
Typing / shows /symbioza:run-on-symbioza.
claude plugin list shows symbioza@symbioza as enabled.

Already added the connector with claude mcp add? Remove that copy (claude mcp remove symbioza) so your agent does not see every tool twice.

4. Get a free estimate

Paste this, or run /symbioza:run-on-symbioza:

Help me prepare this GPU job for Symbioza. Ask for the container image, command, input data and expected output files. Check that the workload fits the current service limits. Show me a free estimate and anything missing, then ask for my total spending limit. Do not submit the job yet.

The estimate needs no spending limit. It leads with the likely cost, its range, the expected runtime and how confident it is — a best-effort estimate, not a quote — or, when nothing about the job predicts its runtime, the price of each hour of running and no total; then what it includes, what is still missing, and the credit on your account. Once you choose a spending limit, the estimate is run again with it: the limit is the hard maximum, and the card shows where it would stop the run and whether your credit covers it. Worked specs for fine-tuning, evaluation and batch inference: https://symbioza.dev/examples

5. Add credit and submit

Two gates: an account, and money in it. A new account can connect, estimate and read its own job list; submitting refuses — “prepaid balance: $0.00 available … Top up, or lower the budget.” — until the account holds credit. Add credit at https://symbioza.dev/app/topup: sign in and add credit by card. Credit can be added in any whole-dollar amount within Symbioza's limits — the packs are shortcuts. When the estimate shows the job is not covered, it names the shortfall and your agent gives you a top-up link prefilled with it. Opening the checkout is not credit: ask for a fresh estimate once you have paid. Credit packs and billing details: https://symbioza.dev/pricing

When you are happy with the estimate, tell your agent to submit. Nothing is booked or charged before you do.

6. Get your files

Ask your agent for the job's status (getStatus). Once the run has finished, ask for its files (getArtifact): each delivered file comes with a download link and a hash you can verify. Links expire after 24 hours; ask again for fresh ones.

What your agent will ask you for

A supported container image. Symbioza runs images it has verified on its machines (today, PyTorch and TensorFlow images). Any other image is refused with the current list of supported images, before anything is booked or charged. A stock image does not contain your code, so the command must fetch your script and anything else it needs, for example from a URL.
A command that runs the job, as you would type it in the container.
Inputs the machine can reach: URLs it downloads itself, never files on your laptop. Use a signed link with the shortest expiry that covers staging.
Output files written to /workspace/artifacts/. That directory is what comes back; anything written elsewhere is not collected.
A total spending limit for the job, in US dollars.

Credentials: saved Secrets, never chat

A job that needs a Hugging Face token, storage keys or another credential gets it from a saved Secret, never from the chat. Your agent follows this rule:

Never ask the user to paste API keys, access tokens, passwords or cloud credentials into chat, and never put them in env — env is for non-sensitive configuration.

Save a credential once at https://symbioza.dev/app/secrets and your agent attaches it to a job by name (secrets). Your agent can list your saved sets with listSecrets, which returns names and types only — no page, API or tool shows a value after it is saved. If a job needs access you have not saved yet, your agent gives you a Symbioza setup link; open it, save the credential there, and tell your agent when it is done.

How a saved secret is handled: Symbioza stores it encrypted and no page, API or tool returns its value; a job that attaches the set receives the plaintext values in its environment, and the machine running that job can technically read them; an exact copy of a value of four or more characters in the job's printed output, or the base64 or URL-encoded form of a value of eight or more, is replaced with [redacted] before that output is stored — exact matching, not a guarantee against a value printed in any other form; files the job writes are delivered as written and are not scanned or redacted; and a credential an earlier job carried in env stays in that job's stored spec — saving a secret does not remove it.

How runs, files and cancelling work

Time. Every run has a time limit: what your spending limit buys on the machine it books and any cap you set, never more than the 48-hour platform maximum. The estimate shows that limit before you spend anything; the machine the job books can end a run sooner. A cap above 48 hours is refused at estimate and at submit.
Files. Check the file delivery status separately from the run status. Available output files have download links and hashes you can verify. A completed run does not by itself confirm file delivery or final billing. Download links expire after 24 hours; the files do not.
Recovery. A retry or move to another machine depends on the job policy, available compute and what is left of your spending limit. Checkpoint recovery needs compatible save-and-resume logic in your code. A run may stop without completing.
Cancel. Cancelling stops your job and releases its machine. If the stop is confirmed, you are charged for measured time up to then; if the machine cannot be reached, only up to the moment you asked — never more than your spending limit.

What you pay

Estimates, status checks and your own job list are free.
Submitted jobs use prepaid credit.
A job that fails, or that you cancel, is billed for the machine time it used — never more than the spending limit you set.
Your spending limit is a hard ceiling: you are never billed more than that. It is checked before a machine is booked and again before every retry. The charge shown after completion may change while billing is reconciled.

Privacy

Jobs run on third-party compute. Your job's image, command, dataset links, environment variables and log tails are processed on Symbioza's servers and can be stored, so keep secrets out of them: never put credentials in a job specification or its environment variables, and never send SSH private keys. Credentials belong in your saved Secrets, which are stored encrypted and injected into the job only when it runs. Only submit code and data you have permission to use.

Privacy: https://symbioza.dev/privacy · Terms: https://symbioza.dev/terms

Update and uninstall

These commands update an existing install; installing for the first time, see step 1. Auto-update is off by default for this marketplace. To update:

Terminal

claude plugin marketplace update symbioza
claude plugin update symbioza@symbioza

The update ends with Restart to apply changes.: restart Claude Code to load the new version.

To uninstall:

Terminal

claude plugin uninstall symbioza@symbioza
claude plugin marketplace remove symbioza

Uninstalling the plugin does not cancel jobs you already submitted and does not close your Symbioza account. Cancel running jobs first (ask your agent, which calls cancelJob), and manage your account at https://symbioza.dev/app.

Get help

A problem installing or using the plugin: open an issue at https://github.com/symbioza/claude-plugin/issues. Redact before you post: never paste tokens, keys, account details or private job data.
Your account, a payment, privacy or security: use the contact form at https://symbioza.dev/contact.
Other clients (ChatGPT, Claude, any remote MCP client): https://symbioza.dev/plugins

Changes and license

Release notes: CHANGELOG.md. MIT — see LICENSE. The license covers this plugin's files only.