Jan

https://docs.jan.ai/
Admin
Jan is an open-source replacement for ChatGPT that enables users to run AI models locally or connect...
Tokens:249,127
Snippets:2,087
Trust Score:9.4
Update:14 hours ago
Show doc for...
Tokens:
Raw
### Install and start ADK runtime (JavaScript)

Source: https://docs.jan.ai/agent/adk-runtime

Installs the nightly runtime and starts it, printing server info. The installation verifies SHA-256 and caches the binary; it does not configure a model provider. Use the binary's 'login' or 'config set' command for that.

```JavaScript
import { installRuntime, JanRuntime } from '@janhq/adk'

const installed = await installRuntime()
const runtime = await JanRuntime.start({ bin: installed.bin })
try {
  console.log(runtime.serverInfo)
} finally {
  await runtime.close()
}
```

--------------------------------

### Install and start ADK runtime (Python)

Source: https://docs.jan.ai/agent/adk-runtime

Installs the nightly runtime and starts it as a context manager, printing server info. The installation verifies SHA-256 and caches the binary; it does not configure a model provider. Use the binary's 'login' or 'config set' command for that.

```Python
from jan_adk import install_runtime, JanRuntime

installed = install_runtime()
with JanRuntime.start(bin=installed.bin) as runtime:
    print(runtime.server_info)
```

--------------------------------

### Complete example script (hello.mjs)

Source: https://docs.jan.ai/agent/adk-ts

Saves a complete example as hello.mjs. It starts the JanRuntime, creates an ephemeral session without builtins, prompts the model, streams token events, and prints the stop reason. Throws an error if the stop reason is 'error'.

```javascript
import { JanRuntime } from '@janhq/adk'

const runtime = await JanRuntime.start()
try {
  const session = await runtime.createSession({ ephemeral: true, builtins: false })
  const turn = await session.prompt('Explain what a mutex is in one sentence.')

  for await (const event of turn) {
    if (event.type === 'token') process.stdout.write(event.text)
  }

  const result = await turn.result()
  if (result.stopReason === 'error') throw new Error(result.error)
  console.log(`\nFinished: ${result.stopReason}`)
} finally {
  await runtime.close()
}
```

--------------------------------

### jan mcp serve command examples

Source: https://docs.jan.ai/agent/mcp

Shows how to start the MCP server with stdio transport (default) or HTTP transport. The HTTP transport prints its URL and bearer token. Use --project to set the project root.

```bash
jan mcp serve --project .              # stdio, what another agent spawns as a child process
jan mcp serve --transport http         # loopback Streamable HTTP; prints its URL and bearer token
```

--------------------------------

### Complete Python example (hello.py)

Source: https://docs.jan.ai/agent/adk-python

A complete script that starts the Jan runtime, creates an ephemeral session, prompts the model, and prints response tokens as they arrive. Raises an error if the turn stops with an error.

```python
from jan_adk import JanRuntime

with JanRuntime.start() as runtime:
    session = runtime.create_session(ephemeral=True, builtins=False)
    turn = session.prompt("Explain what a mutex is in one sentence.")

    for event in turn:
        if event["type"] == "token":
            print(event["text"], end="", flush=True)

    result = turn.result()
    if result.stop_reason == "error":
        raise RuntimeError(result.error)
    print(f"\nFinished: {result.stop_reason}")
```

--------------------------------

### Using with OpenAI SDK - JavaScript client setup

Source: https://docs.jan.ai/desktop/api-preference

Point the OpenAI SDK at your local server by setting the base URL and API key. This example creates a client instance.

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://127.0.0.1:1337/v1",
  apiKey: "YOUR_API_KEY",
});
```

--------------------------------

### Install and start pinned runtime (JavaScript)

Source: https://docs.jan.ai/agent/adk-nightly

Reads the versioned manifest `adk-nightly.json`, installs the pinned runtime, and starts it with `JanRuntime.start()`. Expect the runtime's reported name and version, then a clean exit. The reported version can differ from the artifact version; the manifest pins the artifact while the ADK checks the wire protocol.

```javascript
import { readFile } from 'node:fs/promises'
import { JanRuntime, installRuntime } from '@janhq/adk'

const manifest = JSON.parse(await readFile('adk-nightly.json', 'utf8'))
const installed = await installRuntime({
  manifestUrl: manifest.runtime.manifestUrl,
  version: manifest.runtime.version,
})
const runtime = await JanRuntime.start({ bin: installed.bin })
try {
  console.log(runtime.serverInfo)
} finally {
  await runtime.close()
}
```

--------------------------------

### Install and start pinned runtime (Python)

Source: https://docs.jan.ai/agent/adk-nightly

Reads the versioned manifest `adk-nightly.json`, installs the pinned runtime, and starts it with `JanRuntime.start()`. Expect the runtime's reported name and version, then a clean exit. The reported version can differ from the artifact version; the manifest pins the artifact while the ADK checks the wire protocol.

```python
import json
from pathlib import Path
from jan_adk import JanRuntime, install_runtime

manifest = json.loads(Path('adk-nightly.json').read_text())
installed = install_runtime(
    manifest_url=manifest['runtime']['manifestUrl'],
    version=manifest['runtime']['version'],
)
with JanRuntime.start(bin=installed.bin) as runtime:
    print(runtime.server_info)
```

--------------------------------

### Using with OpenAI SDK - Python client setup

Source: https://docs.jan.ai/desktop/api-preference

Point the OpenAI SDK at your local server by setting the base URL and API key. This example creates a client and sends a chat completion request.

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:1337/v1",
    api_key="YOUR_API_KEY"
)

response = client.chat.completions.create(
    model="jan-v3-4b-base-instruct",
    messages=[{"role": "user", "content": "Hello!"}]
)
```

--------------------------------

### Install Jan CLI with hosted installer (macOS/Linux/Windows)

Source: https://docs.jan.ai/agent/adk-nightly

One-liner commands to install the latest nightly `jan` CLI into `~/.local/bin` on macOS/Linux and Windows PowerShell. Ensure the directory is on PATH; on Windows use the `-AddToPath` form from the Agent quickstart.

```bash
curl -fsSL https://delta.jan.ai/jan-cli/install-jan-agent.sh | bash    # macOS / Linux
irm https://delta.jan.ai/jan-cli/install-jan-agent.ps1 | iex            # Windows PowerShell
```

--------------------------------

### Headless CLI: install and search plugins

Source: https://docs.jan.ai/agent/plugins

Install and search commands continue to print JSON results.

```text
jan plugin install https://github.com/acme/release-tools --project ~/code/app
jan plugin search prepare --project ~/code/app
```

--------------------------------

### Install jan runtime (macOS/Linux)

Source: https://docs.jan.ai/agent/adk-ts

Downloads and installs the jan runtime via a shell script, then adds the installation directory to PATH. Follow the installer's PATH instructions before continuing.

```bash
curl -fsSL https://delta.jan.ai/jan-cli/install-jan-agent.sh | bash
export PATH="$HOME/.local/bin:$PATH"
```

--------------------------------

### GET /v1/models - Example JSON response

Source: https://docs.jan.ai/desktop/api-preference

Example response from the /v1/models endpoint, showing the list of available models.

```json
{
  "object": "list",
  "data": [
    { "id": "jan-v3-4b-base-instruct", "object": "model" }
  ]
}
```

--------------------------------

### Model metadata example (model.yml)

Source: https://docs.jan.ai/desktop/data-folder

Example model.yml file for an installed model, specifying the model path, name, size, embedding flag, and SHA256 checksum.

```yaml
model_path: llamacpp/models/janhq/Jan-v3-4B-base-instruct-gguf/Jan-v3-4b-base-instruct-Q4_K_XL.gguf
name: Jan-v3-4B-base-instruct-gguf
size_bytes: 2999182272
embedding: false
model_sha256: 1dc700f26bfb10e53d1b2daebd86d4c5f2accc50fe13acd863c59453f9abfa48
```

--------------------------------

### stream-json init record example

Source: https://docs.jan.ai/agent/cli

Example of the init record printed at the start of a stream-json run. Contains protocol_version, session_id, model, cwd, tools, tool_specs, input_kinds, and input_content_parts.

```json
{"type":"init","protocol_version":1,"session_id":"3f7a91c2-4e5d-4a6b-8c7d-0e1f2a3b4c5d","model":"tokamak-1-preview","cwd":"/home/me/app","tools":["read","write","shell","host__robot_arm_move"],"tool_specs":[{"type":"function","function":{"name":"host__robot_arm_move","description":"Move the arm.","parameters":{"type":"object"}}}],"input_kinds":["user","abort","permission","tool_result"],"input_content_parts":{"mime_types":["image/png","image/jpeg","image/gif","image/webp"],"max_image_bytes":5242880,"max_message_image_bytes":10485760,"max_images":8,"max_line_bytes":16777216,"max_echo_bytes":4096}}
```

--------------------------------

### Run the Python script

Source: https://docs.jan.ai/agent/adk-python

Executes the hello.py script to run the example.

```bash
python hello.py
```

--------------------------------

### agent.toml configuration example

Source: https://docs.jan.ai/agent/project-config

Complete example of the agent.toml file with commented-out options for [agent], [provider], [budget], [tools], and [skills] sections. Shows default values and available settings. After editing certain keys, run /reload config to apply them without restarting.

```toml
[agent]
# model = "Jan-V4"
# context_window = 128000
# compaction_ratio = 0.8  # share of the window a prompt may fill before compacting
# compaction_reserve_tokens = 16384  # absolute headroom instead, in tokens; wins over compaction_ratio
# max_tokens = 4096
# max_parallel_subagents = 10  # max concurrently-running subagents per run; extra dispatches queue FIFO
# show_reasoning = false  # unfold thinking blocks in the transcript (Ctrl-O still toggles)
# send_reasoning = true   # resend prior reasoning to the model; false drops it from the request
# worktree = true         # give each session its own git checkout instead of editing this one

# [provider]
# name = "openai"
# api_key = "sk-..."
# base_url = "https://api.openai.com/v1"
# models = ["gpt-4o"]
# compaction_ratio = 0.6  # override the [agent] ratio for this provider's routes

# The run's only cap: new token spend across all turns (replayed context is not
# recharged each turn). There is no turn limit. Defaults to the model's context
# window when unset (128000 if the window is unknown); 0 disables the cap.
[budget]
# max_tokens = 128000
# max_usd = 5.00

[tools]
default = "read-only"
allow = []
deny = []
allow_write = []
# sandbox = true
# env_passthrough = ["SSH_AUTH_SOCK", "GIT_*"]
# [tools.env_set]
# RUST_LOG = "info"

[skills]
enabled = []
```

--------------------------------

### --host-tools declaration example

Source: https://docs.jan.ai/agent/cli

Example JSON array passed to the --host-tools flag to declare client-implemented tools. Each tool requires a name, description, and capability; parameters follow JSON Schema format.

```json
[
  {"name": "camera", "description": "Grab a frame.", "capability": "read"},
  {"name": "yam.move_ee_ik", "description": "Move the arm.", "capability": "actuator",
   "parameters": {"type": "object", "properties": {"joints": {"type": "array", "items": {"type": "number"}, "minItems": 6}}, "required": ["joints"]}}
]
```

--------------------------------

### jan cli mcp add examples (stdio and http)

Source: https://docs.jan.ai/agent/cli

Shows how to add a stdio server (default transport) with environment variables, and an HTTP server with a header and marked active immediately. Newly added servers default to inactive unless `--active` is used.

```bash
# stdio (the default transport)
jan cli mcp add files --command npx --arg -y --arg @modelcontextprotocol/server-filesystem \
  --env FOO=bar

# http, with a header and marked active immediately
jan cli mcp add exa --type http --url https://mcp.exa.ai/mcp --header Authorization=Bearer-secret \
  --active
```

--------------------------------

### Skill definition with disable-model-invocation: true

Source: https://docs.jan.ai/agent/skill-invocation

Example SKILL.md frontmatter and instructions for a user-invoked skill. Setting disable-model-invocation: true keeps the skill out of the agent's catalog, so its description costs zero context. This is suitable for personal procedures or anything the agent should never start on its own.

```markdown
---
name: release
description: Cut and publish a release
disable-model-invocation: true
---

# Cutting a release

1. Confirm `main` is green in CI.
2. Bump the version in `Cargo.toml` and `package.json` - they must match.
3. Tag `v<version>` and push the tag.

Never publish from a dirty working tree.

```

--------------------------------

### jan CLI usage examples

Source: https://docs.jan.ai/agent/cli

Common invocations of the `jan` CLI: starting in the current directory, specifying a project, seeding a task, resuming sessions, enabling plan/safe/sandbox modes, forking a session, and using a worktree. Note that tool calls are auto-approved by default and shell commands are not sandboxed by default.

```bash
jan                                     # current directory
jan --project ~/code/app                # somewhere else
jan --task "fix the failing test"       # with a first message
jan -c                                  # resume the latest session
jan --resume 3f7a91c2                   # resume by id prefix
jan --plan                              # read-only
jan --safe                              # ask before writes and shell commands
jan --sandbox                           # confine shell commands to the project
jan -c --fork-session                   # branch the latest session into a new one
jan --worktree                          # work in a dedicated checkout, not yours
```
Tokens:
Raw