{"id":"dfad1f26-3dda-4cd2-858e-c524f00e17f4","shortId":"vXSWnS","kind":"skill","title":"sapiom-deploy","tagline":"Deploy and run code on Sapiom — scheduled jobs, batch execution,","description":"# Sapiom Deploy\n\nDeploy and run code via Sapiom. ZIP your code, POST it, done.\n\n## When to Use\n\n- User says \"deploy this\" / \"ship it\" / \"put this in the cloud\"\n- User wants to run a script on a schedule\n- User wants to process N items in parallel\n- User wants a persistent environment with ports/filesystem\n- User already has working code and wants it deployed\n\n> Building an agent from scratch? Use the **sapiom-agent-builder** skill instead — it handles the full workflow from intent to deploy.\n\n## Deploy Patterns (pick one)\n\n| Pattern | What It Does | When to Use | Reference |\n|---------|-------------|-------------|-----------|\n| Scheduled job | Runs on cron | Periodic tasks (monitoring, scraping, reports) | `references/jobs.md` |\n| Batch job | N parallel tasks on demand | Process a list of items in parallel | `references/jobs.md` |\n| Orchestrator + workers | Scheduled job fans out to batch | Periodic task that processes N items | `references/patterns.md` |\n| Sandbox | Persistent instance with ports + filesystem | Dev environments, servers, long-running processes | `references/sandboxes.md` |\n\n## Quick Decision\n\n- \"Run X every hour\" → Scheduled job\n- \"Process these 50 items\" → Batch job\n- \"Every hour, check for new items, process each\" → Orchestrator + workers\n- \"Spin up a server\" / \"I need a dev environment\" → Sandbox\n\n## Setup (same for all patterns)\n\n```js\nconst { createFetch } = require(\"@sapiom/fetch\");\nconst safeFetch = createFetch({\n  apiKey: process.env.SAPIOM_API_KEY,\n});\nconst GATEWAY = \"https://blaxel.services.sapiom.ai\";\n```\n\n## Example: Deploy a Script on a Schedule\n\nUser says: \"Deploy this script to run every 2 hours\"\n\n**Steps:**\n1. Read `references/jobs.md` for the full API\n2. ZIP `index.js` + `package.json` (files at ZIP root, not in a subdirectory)\n3. `POST /v1/jobs?name=my-job&schedule=0 */2 * * *` with ZIP body\n4. Response returns `{ status: \"deployed\" }` — deploy is synchronous, no polling\n\n**Result:** Deploy returns immediately with `status: \"building\"`. Poll `GET /v1/jobs/my-job` every 10–15s until `\"deployed\"` (~60–120s). Then the job runs every 2 hours.\n\n## Example: Fan Out to Parallel Workers\n\nUser says: \"Process these 100 URLs in parallel\"\n\n**Steps:**\n1. Deploy worker code as a batch job (no schedule): `POST /v1/jobs?name=my-worker` with ZIP body\n2. Trigger execution: `POST /v1/jobs/my-worker/executions` with `{ tasks: [{ url: \"...\" }, ...] }`\n3. Each task runs in parallel, receives its payload via `blStartJob(async (args) => { ... })`\n\n**Result:** 100 tasks run concurrently. Check progress with `GET /v1/jobs/my-worker/executions/{id}`.\n\n## Troubleshooting\n\n### Deploy returns 502\n**Cause:** Bad `package.json` — missing `main`, `scripts.start`, or invalid JSON.\n**Fix:** Ensure `package.json` has `\"main\": \"index.js\"` and `\"scripts\": { \"start\": \"node index.js\" }`.\n\n### Deploy returns 402\n**Cause:** Missing or invalid `SAPIOM_API_KEY`.\n**Fix:** Ensure the API key is valid and passed via the `@sapiom/fetch` SDK.\n\n### Job deploys but fails at runtime\n**Cause:** Code works locally but crashes in the cloud — usually missing env vars.\n**Fix:** Pass `SAPIOM_API_KEY` and any other env vars via the `envs` field in the JSON deploy body.\n\n### ZIP files not found by builder\n**Cause:** Files nested in a subdirectory inside the ZIP (e.g., `my-project/index.js` instead of `index.js`).\n**Fix:** ZIP from inside the directory: `cd my-project && zip -r ../deploy.zip .`\n\n### Job name conflict\n**Cause:** A job with that name already exists.\n**Fix:** Use `PUT /v1/jobs/{name}` to update, or `DELETE` then recreate.\n\n## References\n\n- `references/jobs.md` — Jobs API (create, deploy, execute, manage)\n- `references/sandboxes.md` — Sandboxes API (create, filesystem, processes, ports)\n- `references/patterns.md` — Orchestrator + workers pattern with concrete example","tags":["sapiom","deploy","skills","agent-skills","ai-agents"],"capabilities":["skill","source-sapiom","skill-sapiom-deploy","topic-agent-skills","topic-ai-agents","topic-sapiom"],"categories":["skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/sapiom/skills/sapiom-deploy","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add sapiom/skills","source_repo":"https://github.com/sapiom/skills","install_from":"skills.sh"}},"qualityScore":"0.454","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 9 github stars · SKILL.md body (3,826 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:08:44.597Z","embedding":null,"createdAt":"2026-05-18T13:14:12.639Z","updatedAt":"2026-05-18T19:08:44.597Z","lastSeenAt":"2026-05-18T19:08:44.597Z","tsv":"'/2':264 '/deploy.zip':488 '/index.js':472 '/v1/jobs':257,328,503 '/v1/jobs/my-job':287 '/v1/jobs/my-worker/executions':340,366 '0':263 '1':236,317 '10':289 '100':312,358 '120s':294 '15s':290 '2':233,243,300,336 '3':255,344 '4':268 '402':394 '50':174 '502':371 '60':293 'agent':77,84 'alreadi':67,498 'api':213,242,400,405,437,514,521 'apikey':211 'arg':356 'async':355 'bad':373 'batch':12,120,142,176,323 'blaxel.services.sapiom.ai':217 'blstartjob':354 'bodi':267,335,452 'build':75,284 'builder':85,458 'caus':372,395,421,459,492 'cd':482 'check':180,362 'cloud':41,429 'code':7,19,24,70,320,422 'concret':531 'concurr':361 'conflict':491 'const':204,208,215 'crash':426 'creat':515,522 'createfetch':205,210 'cron':113 'decis':165 'delet':508 'demand':126 'deploy':3,4,15,16,33,74,96,97,219,227,272,273,279,292,318,369,392,416,451,516 'dev':156,195 'directori':481 'done':27 'e.g':468 'ensur':382,403 'env':432,442,446 'environ':63,157,196 'everi':168,178,232,288,299 'exampl':218,302,532 'execut':13,338,517 'exist':499 'fail':418 'fan':139,303 'field':447 'file':247,454,460 'filesystem':155,523 'fix':381,402,434,476,500 'found':456 'full':91,241 'gateway':216 'get':286,365 'handl':89 'hour':169,179,234,301 'id':367 'immedi':281 'index.js':245,386,391,475 'insid':465,479 'instanc':152 'instead':87,473 'intent':94 'invalid':379,398 'item':56,131,148,175,183 'job':11,110,121,138,171,177,261,297,324,415,489,494,513 'js':203 'json':380,450 'key':214,401,406,438 'list':129 'local':424 'long':160 'long-run':159 'main':376,385 'manag':518 'miss':375,396,431 'monitor':116 'my-job':259 'my-project':469,483 'my-work':330 'n':55,122,147 'name':258,329,490,497,504 'need':193 'nest':461 'new':182 'node':390 'one':100 'orchestr':135,186,527 'package.json':246,374,383 'parallel':58,123,133,306,315,349 'pass':410,435 'pattern':98,101,202,529 'payload':352 'period':114,143 'persist':62,151 'pick':99 'poll':277,285 'port':154,525 'ports/filesystem':65 'post':25,256,327,339 'process':54,127,146,162,172,184,310,524 'process.env.sapiom':212 'progress':363 'project':471,485 'put':37,502 'quick':164 'r':487 'read':237 'receiv':350 'recreat':510 'refer':108,511 'references/jobs.md':119,134,238,512 'references/patterns.md':149,526 'references/sandboxes.md':163,519 'report':118 'requir':206 'respons':269 'result':278,357 'return':270,280,370,393 'root':250 'run':6,18,45,111,161,166,231,298,347,360 'runtim':420 'safefetch':209 'sandbox':150,197,520 'sapiom':2,9,14,21,83,399,436 'sapiom-agent-build':82 'sapiom-deploy':1 'sapiom/fetch':207,413 'say':32,226,309 'schedul':10,50,109,137,170,224,262,326 'scrape':117 'scratch':79 'script':47,221,229,388 'scripts.start':377 'sdk':414 'server':158,191 'setup':198 'ship':35 'skill':86 'skill-sapiom-deploy' 'source-sapiom' 'spin':188 'start':389 'status':271,283 'step':235,316 'subdirectori':254,464 'synchron':275 'task':115,124,144,342,346,359 'topic-agent-skills' 'topic-ai-agents' 'topic-sapiom' 'trigger':337 'troubleshoot':368 'updat':506 'url':313,343 'use':30,80,107,501 'user':31,42,51,59,66,225,308 'usual':430 'valid':408 'var':433,443 'via':20,353,411,444 'want':43,52,60,72 'work':69,423 'worker':136,187,307,319,332,528 'workflow':92 'x':167 'zip':22,244,249,266,334,453,467,477,486","prices":[{"id":"1df6eada-5370-4e24-a483-67c6a1b8636b","listingId":"dfad1f26-3dda-4cd2-858e-c524f00e17f4","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"sapiom","category":"skills","install_from":"skills.sh"},"createdAt":"2026-05-18T13:14:12.639Z"}],"sources":[{"listingId":"dfad1f26-3dda-4cd2-858e-c524f00e17f4","source":"github","sourceId":"sapiom/skills/sapiom-deploy","sourceUrl":"https://github.com/sapiom/skills/tree/main/skills/sapiom-deploy","isPrimary":false,"firstSeenAt":"2026-05-18T13:14:12.639Z","lastSeenAt":"2026-05-18T19:08:44.597Z"}],"details":{"listingId":"dfad1f26-3dda-4cd2-858e-c524f00e17f4","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"sapiom","slug":"sapiom-deploy","github":{"repo":"sapiom/skills","stars":9,"topics":["agent-skills","ai-agents","sapiom"],"license":"mit","html_url":"https://github.com/sapiom/skills","pushed_at":"2026-03-06T17:40:04Z","description":"Agent skills for Sapiom — instant access to paid services for AI agents","skill_md_sha":"8f8497f8978e81273000039cd33e47362f744c7c","skill_md_path":"skills/sapiom-deploy/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/sapiom/skills/tree/main/skills/sapiom-deploy"},"layout":"multi","source":"github","category":"skills","frontmatter":{"name":"sapiom-deploy","description":"Deploy and run code on Sapiom — scheduled jobs, batch execution,"},"skills_sh_url":"https://skills.sh/sapiom/skills/sapiom-deploy"},"updatedAt":"2026-05-18T19:08:44.597Z"}}