Jinn docs Console

Runs

Updated 2026-11-06

A run is one call of a function. Each start makes a new run with a new id (run_…). A run ends one time, as succeeded or failed. To continue the work of a run that ended, save its disk as an image. Then start a new run from that image.

Start a run

With the CLI:

$ jinn run support-triage --prompt "Ticket #4812: charged twice" --in ./in --out ./result

With the API:

  1. Make the input folder into one tar file with gzip compression: tar -czf in.tar.gz -C in .
  2. Start an upload with the size and the SHA-256 of the file.
  3. Upload the file to the URL in the response, with the headers in the response.
  4. Start the run with the id of the upload.
POST /v1/files
{"bytes": 691, "sha256": "ac314bcd4091f5729b608f5570ee5ac87dd0eb60a9313158163a74d8732da3f0"}
← 201 {"id": "file_dfa9f553357ebb946a5045a8", "url": "https://…", "method": "PUT", "headers": {"X-Amz-Checksum-Sha256": "rDFLzUCR9XKbYI9VcO5ayH3Q62CpMTFYFjp02HMto/A="}}

PUT <url> with the returned headers and the .tar.gz as the body

POST /v1/functions/fnc_a3b59df3be29992f250c2e1e/runs
{"prompt": "Ticket #4812: charged twice", "input": "file_dfa9f553357ebb946a5045a8"}
← 201 {"id": "run_90bdd4f8175861bad26e0e1b", "state": "queued", …}
FieldValue
promptThe first message to the agent, without changes. Necessary if the function has an agent (prompt_required). Not permitted if the function has no agent (prompt_not_allowed).
inputAn uploaded .tar.gz file (file_…). Jinn unpacks it into /workspace/in. Necessary if the function has an input manifest. Not permitted if it has no input manifest.
imageA disk to boot for this run, not the image of the function: an image of the account (img_…) or a base.
environmentVariables for this run, as in a definition. If the function has a variable with the same name, the value from the run replaces it.
versionA version number. If you do not set it, the run uses the latest version.
webhookAn HTTPS address for the events of the run. See Webhooks.
external_referenceYour own id for the run, a maximum of 256 bytes. Jinn returns it as you sent it. An image that the run saves also keeps it.

A run can change only its image and its variables. Setup, size, timeout, the agent and the manifests are part of the version. To change them, publish a new version.

The input can contain only regular files and folders. Jinn refuses links. The unpacked input must not be larger than half of the disk of the run (see sizes). Jinn refuses a .tar file without compression.

Start a run one time

A request can fail before you receive the response. To send it again safely, send an Idempotency-Key header with the start:

POST /v1/functions/fnc_a3b59df3be29992f250c2e1e/runs
Idempotency-Key: ticket-4812
{"prompt": "Ticket #4812: charged twice", "input": "file_dfa9f553357ebb946a5045a8"}

States

queued → running → succeeded or failed.

A run starts in some seconds if a machine has space for it. If Jinn must start a new machine, the run waits approximately 30 seconds more. If a run does not start in 15 minutes, it fails with infrastructure.

At the start of a running run, Jinn does these steps. The log of the run shows each step.

  1. Jinn restores the disk from the image.
  2. The VM boots. This takes approximately 2 seconds.
  3. Jinn unpacks the input.
  4. Setup runs.

Then the run is ready. Jinn sets ready_at and sends the run.running event. The agent then starts its work, or your commands run. A command that you send before this time waits until the run is ready.

Finish a run

A run ends when a finish command ends it, or when Jinn stops it.

$ jinn finish run_5ab647d533bda87c1063b403
run_5ab647d533bda87c1063b403 succeeded
image img_1246e6c170ea4b93cf3ab52d
$ jinn finish run_3afd65eeb5fc5b3202c44d77 --failed "The tests do not build."
run_3afd65eeb5fc5b3202c44d77 failed incomplete

When a run ends, Jinn cancels the commands that did not end.

Results

A succeeded run has output. If the function has an output manifest and /workspace/out contains files, output lists them with their sizes. output.url is a link to the folder as one .tar.gz file. output.bytes and output.sha256 give its size and its SHA-256. Each read of the run makes a new link. You can use the link for 15 minutes.

Jinn uses the fastest level of gzip. Text files become much smaller. Media files stay almost the same size. If the function has output_image, output.image is the id of the saved image.

$ jinn output run_90bdd4f8175861bad26e0e1b --out ./result
result/actions.json 128 B
result/reply.md 557 B

A failed run has failure and detail:

FailureCauseImage saved
inputThe input is not a readable .tar.gz file, or it contains a link. Or the unpacked input is larger than half of the disk, or it does not agree with the input manifest. Or the image is larger than the disk of the size, or it does not boot. Or someone deleted the image before the run started.No
setupA setup command exited with a status other than 0. The detail shows its output.No
incompleteA finish as failed. The agent used give_up, or the agent stopped its tool calls, or the agent did 200 steps without a command in the VM. Or your code finished the run as failed.No
timeoutThe run continued after timeout_minutes.With output_image
providerThe model vendor refused a call, for example because the key is incorrect or the quota is empty. The detail quotes the vendor.With output_image
maintenanceJinn had to replace the machine of the run. The run.maintenance event comes first, with maintenance_at.With output_image
suspendedJinn suspended the account before the run started or while it worked.With output_image
creditThe balance of the account went more than $10 below its minimum before the run started or while it worked. Add credit to start runs again.With output_image
infrastructureJinn could not start or finish the run, or the machine of the run stopped. Or a step of the agent failed 6 times. Or someone deleted the function before the run started. Start the run again.No

The image of a failed run is the disk at the time when the run stopped. A run that fails before it is ready saves no image.

usage records the size of the VM and its seconds, its network bytes, and the model calls and tokens of the agent.

Logs

The log records each step of the run:

While a run is running, Jinn adds new events to the log at intervals of 30 seconds.

$ jinn logs run_90bdd4f8175861bad26e0e1b --follow

GET /v1/runs/{id}/log returns links to the parts of the log, in sequence. Each part is JSON lines, for example {"at": "2026-10-14T11:43:46.089855126Z", "kind": "tool_call", "name": "bash", "id": "call_xnmZFjRli7jJyQikzQlewJtS", "arguments": "…"}. The response also contains media: a link to each image that a read command or the screenshot tool returned, by command id. A tool_output event with image_bytes gives the id of its command. You can use the links for 15 minutes.

A step_retry event shows that Jinn did an agent step again, because the first attempt of the step did not finish. first_attempt_at gives the time of the first attempt. waited_seconds gives the time that the step lost.

Credit