Changelog

1.0.0 (2026-09-23)

• feat(scaffold): gh profile/persona guidance + GH_TOKEN scrub-inert validate finding (#1228)
• #1226: fix daemon-tier suite failures from the app:// resolver seam
• feat: app:// secret references resolved at spawn by the owning application (#1226)
• feat: workspace home (.home) for model-driven subprocesses (#1225)
• Download workspace files: workspace.file.fetch (protocol 1.20) and offer_download
• docs(explain): surface the predefined plan-file schema in explain plugin todo (#1222)
• #1079: fix two post-merge CI legs — scaffold dep resolver + SDK-floor reversion anchors
• Rename squatted top-level packages to jaato_server / jaato_tui (#1079)
• Update spawn-profile-enum guard for the inherit reserved value (#1198)
• subagent: add reserved "inherit" profile value (#1198)
• Close a fence only with its own closer, so prose is not drawn as code
• Show when GC last ran, what it freed, and the GC policy (#1190)
• Files panel reset that survives a reconnect (#1189)
• fix(service_connector): an untrusted spec can no longer bind a daemon credential
• fix(service_connector): tell the three pass:// resolution failures apart (#1188)
• feat(todo): a plan the profile names, not the model (#1195)
• Split the notebook-marker scan so the guard stays under the complexity ceiling
• Stop server markup reaching the transcript as tags (#1191, #1193)
• fix(server): stage an attached file where the session actually runs
• fix(cli): one verdict per program, and a refusal that says it is one (#1202)
• test(server): split the guard's AST helper to clear the complexity ceiling
• fix(server): report the permission policy the enforcer holds, and on attach
• test(server): repoint a reversion anchor the complexity extraction moved
• fix(runner): hand the subagent plugin the UI hooks nobody installed (#1179)
• fix(session): one name for the workspace index (#1176, #1056)
• fix(packaging): declare the SDK floor at the cut's lowest point (#1153)
• A session you deleted, and a listing that was not yours

jaato-server

The runtime and daemon behind jaato — a multi-provider agentic tool orchestrator. This package holds the session runtime, the plugin system, ~24 model-provider adapters, and the daemon that clients connect to over a Unix socket or WebSocket.

You install this on the machine where agents should run. To talk to it from Python, install jaato-sdk; for a terminal client, jaato-tui.

Installation

pip install jaato-server
# or:  uv pip install jaato-server

The base install carries the daemon, the session runtime and the plugins that need no third-party SDK. Provider SDKs and the heavier tool plugins are extras, so you install only the ones you use:

pip install 'jaato-server[all]'

Anthropic's SDK, mcp, websockets and jaato-sdk are base dependencies — Claude, MCP servers and the WebSocket transport work out of the box. Requires Python 3.12+.

Quick start

Start the daemon:

# Local clients over a Unix domain socket
jaato-server --ipc-socket /tmp/jaato.sock --daemon

# Add a WebSocket port for remote or browser clients.  A bearer token is
# generated at ~/.jaato/ws.token on first WS start if you supply none.
jaato-server --ipc-socket /tmp/jaato.sock --web-socket :8080 --daemon

jaato-server --status
jaato-server --stop

Then drive it from Python:

import asyncio
import jaato          # from jaato-sdk

async def main():
    async with jaato.session(mode="ipc", profile="researcher") as s:
        print(await s.ask("What changed in this repo last week?"))

asyncio.run(main())

The same code runs against an embedded runtime (mode="in_process", no daemon), a local daemon ("ipc"), or a remote one ("ws").

Model providers

One session interface over every backend below; a profile picks the provider and model, and enter_tier can switch bindings mid-session.

Several ship an interactive auth command (anthropic-auth login, github-auth login, openrouter-auth key …) so a credential need never be pasted into a shell profile.

Plugins

Tools reach the model through plugins, discovered from this package and from any installed distribution declaring a jaato.plugins entry point. Built-ins include:

• Execution — cli (shell), interactive_shell (PTY sessions for REPLs, debuggers, wizards), notebook, mcp (any stdio MCP server)
• Code and files — file_edit, filesystem_query, ast_search, lsp, references
• Web — web_fetch, web_search, webmcp, service_connector (call an OpenAPI service by alias), webhook (inbound events)
• Orchestration — subagent, todo, clarification, waypoint, reliability, template
• Context management — four GC strategies (gc_truncate, gc_summarize, gc_hybrid, gc_budget) plus provider prompt-caching plugins
• Control — permission, sandbox_manager, telemetry

Agent profiles

A profile is a YAML file in .jaato/profiles/ binding a model, a provider, a plugin set, a GC strategy and resource ceilings:

name: researcher
description: Deep research profile
provider: anthropic
model: claude-sonnet-4-20250514
plugins: [cli, web_search, memory, todo(preload)]
default_agent: researcher        # the persona in .jaato/agents/researcher.md
runtime_limits:
  max_parallel_tools: 2
  max_orphan_seconds: 300
budget_control:
  limits: {usd: 5.0, tool_calls: 200}
  degrade:
    - {at: 95,  action: finalize}
    - {at: 100, action: abort}

jaato-scaffold interrogates the installed framework rather than a copy of the docs, so it cannot go stale:

jaato-scaffold explain profile         # every profile key, with its vocabulary
jaato-scaffold explain providers       # providers, their knobs and caveats
jaato-scaffold explain plugins         # what is installed, and where it came from
jaato-scaffold validate                # check a workspace before you run it
jaato-scaffold new client --profile researcher

explain covers 20-odd scopes — env, tiers, completion, runtime, paths, services among them.

Isolation and secrets

Sessions run in a subprocess runner, and the daemon confines it where the host allows:

• AppArmor — a per-boundary profile confines the runner to its workspace when the LSM is available. Opt in per client, or require it with JAATO_REQUIRE_APPARMOR=1 so an unconfined host refuses to start rather than degrading silently.
• cgroup v2 — runtime_limits caps memory, pids and CPU; tool timeouts, output size, tool-pool width and two wall-clock bounds are enforced by the framework itself.
• Secret scrubbing — provider keys and tokens are stripped from the environment handed to every model-driven subprocess by default; scrub_secret_env narrows or waives it, and waiving is announced.
• Permissions — every tool call passes a policy that can allow, deny or ask, per session, with the decision recorded.

Configuration

Workspace configuration lives under .jaato/ (profiles, agents, GC settings, permissions) with ~/.jaato/ as the fallback tier. MCP servers are declared in .mcp.json. Credentials resolve from a profile knob, then the environment, then a stored auth file — pass:// and vault:// URIs are resolved daemon-side so a secret never sits on disk in the clear.

jaato-scaffold explain env prints every environment variable the installed tree reads, each tagged with its scope and the typed profile key that supersedes it.

Documentation

• Project README
• Architecture · Sequence diagrams
• Design philosophy
• Permission system
• AppArmor setup
• OpenTelemetry
• Issues

License

BUSL-1.1. See LICENSE.