Functions

A function is a definition with a name. Each publish makes a new version. A version never changes. A run names a version, or uses the latest.

A function's id (fnc_…) is its address. Names are for people: two functions can have the same name.

A definition

{
  "base": "debian-12-20260801-72c15f01",
  "setup": ["apt-get update", "apt-get install -y --no-install-recommends poppler-utils"],
  "provider": "prv_8c1f04d2a7b93e650f1a2c47@latest",
  "system_prompt": "You answer billing tickets.",
  "tools": ["bash", "read", "write", "web_search"],
  "custom_tools": [],
  "input_manifest": [{ "path": "ticket.json", "description": "The ticket", "max_bytes": 1000000 }],
  "output_manifest": [{ "path": "reply.md", "description": "The reply", "max_bytes": 100000 }],
  "environment": [{ "name": "LOCALE", "value": "en-GB" }],
  "size": "s",
  "timeout_minutes": 30
}

Field	What it is
`base`	The disk the machine boots. `GET /v1/bases` and `jinn bases` list them. A base is Debian 12 with Python 3, git, curl, jq, ripgrep, zstd, Chromium and a headless display. Anything else comes from `setup`.
`setup`	Commands that run before the agent starts, in order. Each runs as root in its own `bash -euo pipefail -c`, with network access and the environment. If one fails, the run fails with `setup`. At most 64 commands.
`provider`	The model the agent uses: `prv_…@3` (version 3) or `prv_…@latest` (the newest version when the run starts). See Providers.
`system_prompt`	The agent's instructions. The run's prompt is its first message.
`tools`	Tools the agent can use: `bash`, `read`, `write`, `edit`, `screenshot`, `web_search`. `submit_result` is always there.
`custom_tools`	Tools you serve over HTTPS. See Custom tools.
`input_manifest`	Files and folders the input folder must hold. Jinn checks each exists and is within `max_bytes` before the agent starts. A path that ends in `/` is a folder.
`output_manifest`	Files and folders the agent must leave in `/workspace/out`. The agent cannot finish until they exist and fit.
`environment`	Variables for setup and the agent's commands: a `value`, or a `secret`. See Secrets.
`size`	The machine: `s` (1 vCPU, 2 GiB), `m` (2 vCPU, 4 GiB), `l` (4 vCPU, 8 GiB), `xl` (8 vCPU, 16 GiB). Each GiB of memory comes with 20 GiB of disk. Your account's limits name the sizes you can use.
`timeout_minutes`	How long a run can work before it fails with `timeout`.

Bases and setup

Use setup like a Dockerfile's RUN lines. Debian packages come from deb.debian.org, so setup usually takes seconds:

"setup": [
  "apt-get update",
  "apt-get install -y --no-install-recommends poppler-utils python3-pip",
  "pip install --break-system-packages pandas==2.2.3"
]

To bring your own code, put it in the input folder. Setup can install it from /workspace/in.

Providers

A provider holds a model and your vendor API key: OpenAI, Anthropic or xAI. Your runs call the model with your key, so the vendor bills you for tokens. Jinn checks the key and the model against the vendor's catalog when you publish. Jinn never shows a key again.

A provider has versions, like a function. A new key is a new version. Functions that use prv_…@latest get it at their next run.

Make providers in the console, or with the API (POST /v1/providers).

Custom tools

A custom tool is an endpoint you serve. When the agent calls the tool, Jinn sends the agent's arguments as a JSON POST to your URL, with the tool's secret as Authorization: Bearer. The response body is the tool's result. An error status or no answer within timeout_seconds (at most 600) is the tool's error, and the run goes on.

{
  "name": "lookup_customer",
  "description": "Find a customer by email.",
  "parameters": { "type": "object", "properties": { "email": { "type": "string" } }, "required": ["email"] },
  "url": "https://support.example/tools/customer",
  "secret": "sk_tool_4f9a…",
  "timeout_seconds": 30
}

Only public HTTPS addresses work, and Jinn does not follow redirects.

Secrets

Send a secret value once, in secret. Jinn stores it encrypted for your account and returns a secret_id in the version. To keep the value in a later version, send that secret_id instead of the value. A tool's secret is only sent to a tool at the same URL. Jinn never returns or logs a secret.

Versions

jinn publish function.json      # makes the function, or publishes its next version

With the API, POST /v1/functions makes a function and its first version, and POST /v1/functions/{id}/versions publishes the next one.