Jobs

A job runs a command on one or more authorized servers. Jobs can run manually, on a cron schedule, once at a specified time, or in response to configured events. Self-hosted jobs target connected servers; Cloud jobs target the organization's managed servers, using the same operations and scheduler.

Job methods take the job's key. Run methods take a run ID. Writing a command job also requires administration access to every target server. The same target permission protects configuration, run history and output. Cloud does not expose internal system jobs, even to customer administrators.

Cloud users can share a managed server with projects or create a dedicated server with its own subscription. Commands use that server's capacity and usage allowance. An active subscription, available balance and a running server are required; executing a job never provisions a server. Manual billing refusals return CLOUD_BILLING_BLOCKED with the target workspaceId and serverId. Scheduled attempts record failures in their run history.

Create a command job

const job = await ship.jobs.create({
  label: "Check Node version",
  serverId: "srv_123",
  command: "node --version",
  scheduleType: "manual",
  timeoutMs: 10_000,
});
console.log(job.key);

curl -X POST "$OPENSHIP_URL/api/jobs" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"Check Node version","serverId":"srv_123","command":"node --version","scheduleType":"manual","timeoutMs":10000}'

update(key, input) accepts partial configuration plus enabled. System jobs only accept cronExpression and enabled, and cannot be removed. Secret updates replace the supplied secret map.

Run and inspect

const submitted = await ship.jobs.run("job_key");
console.log(submitted.runId, submitted.summary);

curl -X POST "$OPENSHIP_URL/api/jobs/job_key/run" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN"

Submission can return a runId or an immediate summary. Use getRun(runId) to inspect execution status, attempt, output, errors, and timing. listRuns(key, { limit }) returns history; limit is 1–1,000.

for await (const event of ship.jobs.streamRun("run_123")) {
  console.log(event);
}

curl -N "$OPENSHIP_URL/api/jobs/runs/run_123/stream" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN"

Native scheduling

An owned native installation does not start scheduling by default. Set jobs: { enabled: true } in its startup configuration only when it should own that work. Running one job manually and enabling recurring scheduling are separate actions. See background work limits.

Operations