Functions
Updated 2026-10-22
A function is a named definition of a run. Each time that you publish a function, Jinn makes a new version of it. A version does not change. A run uses the version that you specify, or the latest version.
The id of a function (fnc_…) identifies it. Two functions in an account can have the same name. The CLI accepts a function name only if one function has that name.
A function with an agent receives a prompt. Jinn's agent works in the VM until the output files exist. A function without an agent starts a VM. The VM then waits for your commands.
Definition
This is the function of the support ticket example:
{
"name": "support-triage",
"agent": {
"system_prompt": "You answer billing tickets for Acme. /workspace/in contains the ticket (ticket.json) and the billing policy (policy.md). Find the customer with lookup_customer and the email address of the ticket. Obey all rules of the policy. Write the reply to the customer in /workspace/out/reply.md. Write the refunds to make in /workspace/out/actions.json, as a JSON array of {\"charge\": id, \"amount\": number, \"reason\": text}. If there are no refunds, write []. Write in ASD-STE100 Simplified Technical English. Then call complete.",
"custom_tools": [{
"name": "lookup_customer",
"description": "Finds a customer by email address. Returns the plan, seats, prices and recent charges of the customer.",
"parameters": { "type": "object", "properties": { "email": { "type": "string" } }, "required": ["email"], "additionalProperties": false },
"url": "https://docs.usejinn.com/tools/lookup-customer",
"secret": "sk_example_support"
}]
},
"input_manifest": [
{ "path": "ticket.json", "description": "The ticket" },
{ "path": "policy.md", "description": "The billing policy" }
],
"output_manifest": [
{ "path": "reply.md", "description": "The reply to send" },
{ "path": "actions.json", "description": "The refunds to make" }
]
}
This function has no agent. It is a Go machine of the default size, m. Jinn keeps its disk from one run to the next:
{
"name": "go-sandbox",
"setup": ["apt-get update", "apt-get install -y --no-install-recommends golang-go"],
"environment": [{"name": "CGO_ENABLED", "value": "0"}],
"output_image": true
}
Only name is necessary. When you publish, Jinn sets a default value for each field that you do not set. The version records these values. To change a value, set the field.
| Field | Value | Default |
|---|---|---|
name | The name of the function. jinn publish reads it from the file. The API receives it next to the definition, in POST /v1/functions. | Necessary |
image | The disk that the VM boots: a Jinn base or an image of the account (img_…). jinn images lists the two. See Images. | The newest base |
setup | Commands that run at the start of each run. See Setup. | None |
environment | Variables for setup and for all commands. See Secrets. | None |
size | s, m, l or xl. See Environment. | m |
timeout_minutes | 1 to 1440. The time of setup is part of the timeout. | None: the run continues until a command finishes it |
input_manifest | The files and folders that the input must contain. Jinn examines the input before setup. Without an input manifest, the runs take no input. | None: the runs take no input |
output_manifest | The files and folders that /workspace/out must contain when the run finishes as succeeded. Without an output manifest, the run returns no files. | None: the run returns no files |
output_image | If true, Jinn saves the disk of the run as a new image when the run ends. See Images. | false |
agent | Jinn's agent. See The agent. | No agent: the run waits for commands |
A version keeps the image that it had when you published it. To use a newer base, publish the function again.
A run without a timeout continues until a command finishes it. Jinn bills the run for all of this time. Set timeout_minutes if your code does not always finish its runs.
The agent
| Field | Value | Default |
|---|---|---|
agent.system_prompt | The instructions for the agent. The prompt of the run is the first message to the agent. | Necessary |
agent.provider | The provider, by name or id, and its version. openai or openai@latest uses the newest version at the start of the run. openai@3 uses version 3. prv_…@3 and prv_…@latest also work. Jinn records a name as the id of its provider. The publish fails if no provider has the name, or if two providers have it. | The only provider of the account, at @latest. If the account has no provider or more than one, the publish fails. Then you must set the provider. |
agent.tools | Some or all of bash, read, write, edit, screenshot and web_search. [] gives no tools. | All of them |
agent.custom_tools | Tools that you serve with HTTPS. See Custom tools. | None |
The agent always has two more tools:
completefinishes the run as succeeded.give_upfinishes the run as failed. Thereasonfrom the agent becomes thedetailof the run.
Each tool call of the agent is a command. Thus the log of the run shows each tool call. You can also send commands to a run that has an agent.
If a reply from the model has no tool call, the agent sends a reminder to the model. After three replies without a tool call, one after the other, the run fails with incomplete.
The agent can do 200 steps one after the other without a command in the VM. A reply that calls only custom tools or web_search uses two steps: the reply and the answers. After 200 of these steps, the run fails with incomplete.
Manifests
Each entry has a path and a description. An entry can also have a max_bytes. The default max_bytes is the limit: 5 GB for an input file, and 50 GiB for the output. A path that ends with / is a folder. The folder must exist, but it can be empty. The max_bytes of a folder is the limit for all of its contents.
Jinn examines only if each entry exists, and its size. Your system prompt specifies the contents of each file.
- Input. If an entry is missing or too large, the run fails with
inputbefore setup. - Output. A
finishas succeeded examines/workspace/out. If an entry is missing or too large, the finish returns a list of the problems. The run then continues. Thecompletetool of the agent is a finish of this type. Thus the agent receives the problems and can correct them. - Jinn also returns the output files that are not in the manifest.
- A function without an output manifest returns no files. Jinn does not empty
/workspace/outand does not examine it. - A function without an input manifest takes no input. Jinn does not empty
/workspace/in. - Thus, a function without manifests keeps all of the files in
/workspacefrom the image.
Setup
Setup commands are equivalent to the RUN lines of a Dockerfile. Each command runs as root, in its own bash -euo pipefail -c. It has network access and the environment of the run. If a command exits with a status other than 0, the run fails with setup. The detail of the run shows the output of the command.
"setup": [
"apt-get update",
"apt-get install -y --no-install-recommends python3-pip poppler-utils",
"pip install --break-system-packages pandas==2.2.3"
]
Setup runs at the start of each run, from all images. A run from a saved image also runs setup again. Thus write commands that you can safely run again. To save the time of setup, save its result as an image one time. Then set that image in the function. See Images.
Debian packages come from deb.debian.org. apt-get update takes approximately 3 seconds. To install your own code, put it in the input folder. Then install it from /workspace/in.
Providers
A provider contains a model, its settings and your vendor key. The vendor can be OpenAI, Anthropic or xAI. The agent calls the model with your key, and the vendor bills you for the tokens. When you publish a provider, Jinn examines the key and the model against the model list of the vendor. No response contains the key.
| Field | Value |
|---|---|
model.provider | openai, anthropic or xai |
model.model | A model id from jinn models <vendor> |
model.reasoning_effort | One of the efforts that the model lists, or empty |
model.compact_at_tokens | When the conversation becomes this size, Jinn compacts it. The minimum is 8000, or 50000 for Anthropic. |
model.max_output_tokens | The maximum number of tokens in one reply. 0 uses the maximum of the model. For Anthropic, Jinn writes that maximum into the version when you publish it. |
A new key or a change to the model makes a new provider version. An agent with @latest uses the new version from its next run. To make a provider, use jinn provider, the console or POST /v1/providers.
To delete a provider, use jinn provider rm, the console or DELETE /v1/providers/{id}. Jinn deletes all its versions and their keys. Jinn refuses the delete in these conditions:
- The latest version of a function names the provider (
provider_in_use). Publish a version with a different provider, or delete the function. - A run that uses the provider is queued or running (
runs_active).
An older version of a function can name a deleted provider. That version cannot start runs.
Custom tools
A custom tool is an endpoint that you serve. When the agent calls the tool, Jinn sends the arguments as JSON in a POST request to url. The body of the response, as text, is the result. Put custom tools in agent.custom_tools.
This is the tool from the support ticket example. Jinn serves its endpoint. Thus the example works without changes:
{
"name": "lookup_customer",
"description": "Finds a customer by email address. Returns the plan, seats, prices and recent charges of the customer.",
"parameters": { "type": "object", "properties": { "email": { "type": "string" } }, "required": ["email"], "additionalProperties": false },
"url": "https://docs.usejinn.com/tools/lookup-customer",
"secret": "sk_example_support"
}
Each call has two headers:
| Header | Value |
|---|---|
Authorization | Bearer <secret>. Do not accept a call without it. |
Jinn-Run | The run that the call is for (run_…). Use it to log or trace the call, or to find the run. |
parametersis a JSON Schema object. Each object in the schema must setadditionalPropertiestofalse.- The agent receives an error if the endpoint returns an error status, if the request fails, or if no answer comes in
timeout_seconds. The run continues. timeout_secondsis 1 to 600. The default is 30.- Jinn calls only public HTTPS addresses. It does not follow redirects.
- The call comes from Jinn, not from the VM. The secret does not go into the VM.
Web search
web_search searches the public web through the provider of the agent, with your key. The vendor bills the searches.
| Vendor | How the agent searches |
|---|---|
| OpenAI | For each search, the agent calls gpt-5.6 with the web search tool of OpenAI. The agent receives the results and their source URLs. |
| Anthropic | The agent uses the web search tool of Anthropic, with a maximum of 20 searches in each model reply. An admin of an organization can disable web search in the Claude Console. Then the vendor refuses each model call that has the tool, and the run fails with provider. For this organization, remove web_search from agent.tools. |
| xAI | The agent uses the web search tool of xAI. |
usage.model.web_searches of a run counts its searches.
Secrets
Send a secret value one time, as secret, in a tool or an environment variable. Jinn encrypts the value for your account. The version keeps only a secret_id. To use the same value in a newer version, send that secret_id, not secret.
- Jinn sends the secret of a tool only to a tool with the same URL.
- A secret variable is in the environment of the VM. Thus the agent and all commands can read it.
- A key that can start the function can also send commands to its runs. Thus a person or program with that key can read the secret variables.
- Variable names cannot start with
JINN_.
Publish
$ jinn publish function.json
→ support-triage fnc_a3b59df3be29992f250c2e1e v12
If no function has the name of the file, jinn publish makes a new function. If one function has that name, jinn publish publishes its next version. With the API, POST /v1/functions makes a function, and POST /v1/functions/{id}/versions publishes the next version.
Delete a function
$ jinn function rm weekly-report
jinn function rm accepts the name or the id of the function. DELETE /v1/functions/{id} does the same. It requires an admin key or a person who signed in. The console has Delete on the page of the function.
- Jinn deletes the function, all of its versions and their secrets.
- The runs of the function stay until the end of their retention. The images of these runs also stay.
- A key that names the function cannot start it.
- The name becomes available. If you publish a function with this name, Jinn makes a new function with a new id.
- While a run of the function is
queuedorrunning, Jinn refuses the delete withruns_active. Finish the run, or wait for it to end. Then delete the function again.
A delete is permanent.