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. This surface requires a self-hosted installation.

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.

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