job_start
Destructive
Start a local or SSH command as a tracked job, with idempotent retries via a trace ID to prevent duplicate execution.
Instructions
Start one tracked local or SSH command. Pass remote shell commands verbatim without adding escapes. For a RunBeacon prompt trace, reuse requestTraceId on every retry so the server returns the original job instead of executing twice. When the user requests the default SSH server, set useDefaultCredential=true and call this tool directly without listing profiles first.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Local working directory. | |
| env | No | Local environment overrides. Values are never persisted. | |
| args | No | Local command arguments. For SSH, include arguments in command. | |
| label | No | ||
| shell | No | Use a local shell. | |
| target | No | ||
| adapter | No | generic | |
| command | Yes | Local command or complete remote shell command. | |
| metadata | No | In-memory caller metadata. It is not persisted unless RUNBEACON_PERSIST_METADATA=true, and sensitive-key values are redacted when persistence is enabled. | |
| timeoutMs | No | ||
| outputPolicy | No | ||
| executionMode | No | Prefer the durable runner, force direct SSH, or require the runner path. | auto |
| idempotencyKey | No | Stable caller-provided key that returns the existing job instead of launching a duplicate after a retry. | |
| requestTraceId | No | Opaque request UUID supplied by the RunBeacon prompt hook. Reuse it unchanged; a second start with the same trace returns the first job. | |
| requireDurable | No | Fail instead of falling back to direct SSH when the durable runner is unavailable. | |
| progressPattern | No | Optional RE2-compatible regex (no backreferences or lookbehind); capture group 1 must contain a finite percentage. | |
| credentialProfile | No | Saved SSH profile. If omitted, a unique profile matching target.host and target.username is selected automatically when no inline authentication is supplied. | |
| requestReceivedAt | No | ISO timestamp supplied by the RunBeacon prompt hook for end-to-end latency measurement. | |
| eventSubscriptions | No | ||
| useDefaultCredential | No | Fast path for an explicitly requested default SSH server. Set true directly without calling credential_profile_list first. Leave false for local commands. |