Agent GPU Sandbox
The Agent GPU Sandbox is your AI agent's GPU workstation. Your agent (Claude, Cursor, Codex CLI, or any MCP client connected through AI connections) deploys a real GPU VM on Spheron and keeps it for hours to train, fine-tune, benchmark and run long jobs, while the results come back in your chat. This page covers what the agent can do, how to turn the sandbox on, how it works, and its limits.
It is your VM, not a shared container. Files, packages and models stay on it between jobs, and your own SSH key keeps working the whole time, so you can log in and look at anything the agent is doing. A VM takes a few minutes to boot, so the sandbox suits real GPU work that runs for a while rather than quick one-off snippets. The Agent GPU Sandbox is open to every account, and the instance is billed at its normal price.
Prerequisites
- An AI assistant connected to Spheron. See AI connections.
- At least one SSH key saved in Settings > SSH Keys. The sandbox never replaces your own access. See User settings.
- Credit on your account for the GPU time. See Billing.
What you can ask for
Ask in plain words. The agent picks an offer, shows you the price, deploys after you say yes, and then gets to work on the machine:
Fine-tune Llama 3.1 8B on my dataset on an H100 and report the eval loss.
Benchmark vLLM serving Qwen3 32B on 2x H100 and tell me the tokens per second.
Clone github.com/<you>/<repo>, install the requirements and run the test suite on a GPU.
Start a training run in the background and check how the loss looks every few minutes.
Compare PyTorch 2.5 and 2.6 throughput for this script on an A100.What the agent can do on the sandbox
| Action | What it does |
|---|---|
| Run a command | Runs a shell command as the machine's login user, with sudo available, and returns the exit code and output. |
| Run a long job | Starts a command in the background (up to 24 hours) and streams its output while it runs. |
| Stop a command | Kills a running command and every process it started. |
| Read, write, and list files | Moves files of up to 5 MB each between the chat and the machine. |
| Check status | Reports whether the sandbox is setting up, ready, or not reachable. |
| Remove the sandbox | Uninstalls the sandbox program. The instance keeps running. |
The agent acts only on the machine it deployed, and only while the instance is running.
Turn on the sandbox
The sandbox cannot be turned on from the Spheron dashboard. Your agent requests it when it deploys for you:
- Connect Spheron to your AI assistant. See AI connections.
- Ask the agent for work that needs a GPU, or ask it to deploy a GPU sandbox.
- Approve the deploy preview. It shows the price and says the GPU sandbox is on.
The deploy wizard shows an Agent GPU Sandbox row above Deploy Instance. It explains the feature and is read-only.
When the instance is up, its deployment page shows the sandbox status:
| Status | Meaning |
|---|---|
| Setting up | The instance is booting and the sandbox program is installing. This takes about 1 to 3 minutes after the instance is running. |
| Ready | The agent can run commands and use files. |
| Not reachable | Spheron cannot reach the sandbox program. See Restore the sandbox. |
| Setup failed | The program could not be installed. The page shows the reason. The instance itself is unaffected. |
| Instance stopped | The instance is stopped. Start it to use the sandbox again. |
How it works
When the agent deploys with the sandbox on, Spheron installs a small program on the VM. Depending on the provider, it is installed by the startup script at boot, or over SSH right after boot with a one-time key that is removed afterwards.
The program connects outwards to Spheron over HTTPS and carries out the commands and file operations your agent sends through the connector. It opens no port on the machine. It runs as a system service, so it survives reboots, and it keeps working through instance restarts.
Your SSH key is added to the machine as usual. Connect with the same SSH command as any other instance, before, during, and after the agent works on it. See SSH connection.
Limits
| Limit | Value |
|---|---|
| Command run time | 10 minutes by default. Up to 24 hours when the agent sets a longer timeout or runs it in the background. |
| Output returned to the chat | The first 1 MB of each command. The full output is saved on the machine in /var/log/spheron-agent/. |
| File read or write | 5 MB per file. The agent downloads datasets and models on the machine itself with curl, git, or huggingface-cli. |
| Who can use it | Only the person who deployed the instance. Team members cannot. |
| Offers | Every offer that accepts a startup script or SSH setup. Some Spheron AI offers accept neither, so a sandbox request on them is refused before anything is created. Choose another offer, or deploy without the sandbox. |
Restore the sandbox
If Spheron cannot reach the sandbox program, for example after the program was stopped or the machine was rebuilt, the deployment page shows Not reachable and a one-line command:
- Copy the command from the deployment page.
- SSH into the instance.
- Paste and run the command.
The status returns to Ready within a minute. The command downloads the installer first and then runs it, so a failed download stops with an error and changes nothing. Each command expires within 30 minutes. Reload the page for a fresh one.
A problem with the sandbox never stops or deletes your instance. Commands the agent queued while the machine was unreachable run once it is back.
Remove the sandbox
Ask your agent to remove the sandbox from the instance. Spheron uninstalls the program and revokes its access. The instance keeps running, background jobs you started keep running, and your SSH access is not affected.
To remove it yourself, SSH into the instance and run:
sudo sh -c 'systemctl disable spheron-agent; systemctl stop spheron-agent; rm -rf /etc/spheron-agent /usr/local/bin/spheron-agent /usr/local/bin/spheron-agent.prev /etc/systemd/system/spheron-agent.service /etc/systemd/system/spheron-agent.service.d; systemctl daemon-reload'Terminating the instance removes everything with it.
Billing
You pay for the GPU instance at its normal price, exactly as without the sandbox, until you stop or terminate it. A stopped instance bills only storage. The minimum runtime applies as usual. If you ask to terminate before it is met, the agent tells you when the instance can be terminated and, within 30 minutes of that time, can hold your yes and terminate it then. Ask your agent to stop or terminate the instance when the work is done, and set a spend limit on the connection to cap what it can launch.
Security
- The program only connects outwards to Spheron. It opens no inbound port.
- Each machine has its own credentials. They are never shared between machines and stop working when the sandbox is removed.
- Every command the agent runs is recorded with its text and exit code. Command output and file contents are not stored in that record.
- Only the person who deployed the instance can use its sandbox.
- Every deploy, stop, and terminate still goes through the connection's preview and spend limit.
What's next
- AI connections: connect Claude, ChatGPT, Codex CLI, Cursor, or VS Code
- SSH connection: log in to the same machine yourself
- Startup script: what runs at boot on each provider
- Distributed training: multi-GPU training your agent can run
- Billing: how instance time and storage are charged
Troubleshooting
Issue: The sandbox is not available on this offer
Symptoms: The deploy is refused with a message that the GPU sandbox is not available on this offer.
Diagnosis: The offer accepts neither a startup script nor SSH setup, so the sandbox program cannot be installed.
Resolution: Ask the agent to pick an offer from another provider, or to deploy without the sandbox.
Issue: The status stays on Setting up
Symptoms: The deployment page shows Setting up for more than 10 minutes after the instance is running.
Diagnosis: The instance could not download the installer, or its startup script failed before the installer ran.
Resolution: Wait for the status to change to Setup failed or Not reachable. If the page shows a command, SSH in and run it. Otherwise ask the agent to deploy a new instance and terminate this one.
Issue: The agent reports the instance is not reachable
Symptoms: Commands stay queued, and the deployment page shows Not reachable.
Diagnosis: The sandbox program stopped, or the machine lost its network connection.
Resolution: Follow Restore the sandbox. The queued commands run once the status is Ready.
Issue: A command's output is cut off
Symptoms: The agent says the output was truncated.
Diagnosis: The command printed more than 1 MB.
Resolution: Ask the agent to read the full log from /var/log/spheron-agent/ on the machine, or to write results to a file and read that file.