Quickstart: the API and the SDK

Shotcup runs JavaScript in a fresh, sandboxed GocciaScript engine per run and answers with the output, a diff of the virtual filesystem and the files the code wrote under /out.

1. Get an API key

Sign in at shotcup.dev/dashboard and create a key. The key (sk_…) is shown once; Shotcup stores only its SHA-256 hash, so copy it then. Every account starts on Free: 5 s per run, 32 MiB of JS heap, 1 run at a time, no network, and each month 30,000 runs and 3 h of compute included. Run history is kept for Free 1 day, Pro 7 days, Scale 30 days, Platform 90 days.

2. Run code over HTTP

curl https://shotcup.dev/api/v1/runs \
  -H "Authorization: Bearer $SHOTCUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "console.log(\"hello from a sandbox\");"}'

The answer is { "run": { "status", "stdout", "stderr", "diff", "artifacts", "metrics", "hint", ... } }, and the Server-Timing header says where the request's time went. Files the code writes under /out come back as artifacts with a link:

curl https://shotcup.dev/api/v1/runs \
  -H "Authorization: Bearer $SHOTCUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "import fs from \"fs\";\nfs.mkdirSync(\"/out\", { recursive: true });\nfs.writeFileSync(\"/out/hello.txt\", \"hi\");"}'

3. Mind the language profile

The engine runs modern JavaScript as ES modules in GocciaScript's default profile: arrow functions, const/let and for...of; no function keyword, var, while or C-style for, and no semicolon insertion at line breaks. A run that trips over one of these fails with a hint that says what to write instead. There is no npm and no Node API besides fs.

4. Connect an agent over MCP

The MCP server is https://shotcup.dev/api/mcp/mcp with the header Authorization: Bearer sk_…. Claude Code:

claude mcp add --transport http shotcup https://shotcup.dev/api/mcp/mcp \
  --header "Authorization: Bearer sk_…"

The MCP guide covers Cursor, VS Code, Grok and Claude Desktop.

5. The TypeScript SDK

The SDK shotcup is a client of the hosted platform: every run happens on Shotcup, nothing runs on your machine. It is not published to npm yet. Once it is:

import { createClient } from "shotcup";

const shotcup = createClient({ apiKey: process.env.SHOTCUP_API_KEY, baseUrl: "https://shotcup.dev" });
const run = await shotcup.runs.create({ code: 'console.log("hello")' });
console.log(run.status, run.stdout);

Until then the REST API above and MCP are the ways in.

Limits and history

Plans and their limits are on the pricing page. Your runs, their output, source, timings and artifacts are in the dashboard for as long as your plan keeps them.