Sapiom Deploy
Deploy and run code via Sapiom. ZIP your code, POST it, done.
When to Use
- User says "deploy this" / "ship it" / "put this in the cloud"
- User wants to run a script on a schedule
- User wants to process N items in parallel
- User wants a persistent environment with ports/filesystem
- User already has working code and wants it deployed
Building an agent from scratch? Use the sapiom-agent-builder skill instead — it handles the full workflow from intent to deploy.
Deploy Patterns (pick one)
| Pattern | What It Does | When to Use | Reference |
|---|---|---|---|
| Scheduled job | Runs on cron | Periodic tasks (monitoring, scraping, reports) | references/jobs.md |
| Batch job | N parallel tasks on demand | Process a list of items in parallel | references/jobs.md |
| Orchestrator + workers | Scheduled job fans out to batch | Periodic task that processes N items | references/patterns.md |
| Sandbox | Persistent instance with ports + filesystem | Dev environments, servers, long-running processes | references/sandboxes.md |
Quick Decision
- "Run X every hour" → Scheduled job
- "Process these 50 items" → Batch job
- "Every hour, check for new items, process each" → Orchestrator + workers
- "Spin up a server" / "I need a dev environment" → Sandbox
Setup (same for all patterns)
const { createFetch } = require("@sapiom/fetch");
const safeFetch = createFetch({
apiKey: process.env.SAPIOM_API_KEY,
});
const GATEWAY = "https://blaxel.services.sapiom.ai";Example: Deploy a Script on a Schedule
User says: "Deploy this script to run every 2 hours"
Steps:
- Read
references/jobs.mdfor the full API - ZIP
index.js+package.json(files at ZIP root, not in a subdirectory) POST /v1/jobs?name=my-job&schedule=0 */2 * * *with ZIP body- Response returns
{status: "deployed"}— deploy is synchronous, no polling
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.
Example: Fan Out to Parallel Workers
User says: "Process these 100 URLs in parallel"
Steps:
- Deploy worker code as a batch job (no schedule):
POST /v1/jobs?name=my-workerwith ZIP body - Trigger execution:
POST /v1/jobs/my-worker/executionswith{tasks: [{url: "..."},...]} - Each task runs in parallel, receives its payload via
blStartJob(async (args) => {...})
Result: 100 tasks run concurrently. Check progress with GET /v1/jobs/my-worker/executions/{id}.
Troubleshooting
Deploy returns 502
Cause: Bad package.json — missing main, scripts.start, or invalid JSON. Fix: Ensure package.json has "main": "index.js" and "scripts": {"start": "node index.js"}.
Deploy returns 402
Cause: Missing or invalid SAPIOM_API_KEY. Fix: Ensure the API key is valid and passed via the @sapiom/fetch SDK.
Job deploys but fails at runtime
Cause: Code works locally but crashes in the cloud — usually missing env vars. Fix: Pass SAPIOM_API_KEY and any other env vars via the envs field in the JSON deploy body.
ZIP files not found by builder
Cause: Files nested in a subdirectory inside the ZIP (e.g., my-project/index.js instead of index.js). Fix: ZIP from inside the directory: cd my-project && zip -r../deploy.zip.
Job name conflict
Cause: A job with that name already exists. Fix: Use PUT /v1/jobs/{name} to update, or DELETE then recreate.
References
references/jobs.md— Jobs API (create, deploy, execute, manage)references/sandboxes.md— Sandboxes API (create, filesystem, processes, ports)references/patterns.md— Orchestrator + workers pattern with concrete example