KHEISH · PERSISTENT AGENT RUNTIME

Agents thatoutlive the caller.

Kheish is the open-source daemon that runs the lab’s agents. A CLI, a Slack message or a webhook only asks; the daemon executes, journals every turn, waits for a human when it must, and stays accountable for every action an agent takes.

Take the tour Every feature

Air Overview on a Kheish daemon: runs in the last 24 hours, what waits on a human (a question and two approvals), runs over time and totals. — A Kheish daemon at work, seen through Air, its console: what waits on a human, runs over time, totals.

Real screens of Air on a local Kheish daemon, with demo sessions.

59built-in tools, from files and shell to scheduling, sub-agents and channels
211HTTP API paths, described in OpenAPI and driven by the same binary’s CLI
5model providers: Anthropic, OpenAI, Google, OpenRouter and xAI

THE INVARIANT

The caller asks. The daemon runs.

Whoever asks for a run, the CLI, Air, a channel, a webhook or your own code, only submits it. The daemon executes it, writes every turn to an append-only journal and keeps it under a named authority with a stated scope. The caller can disconnect, crash or never come back.

Kheish runtime: the CLI, Air and channels submit to the Kheish daemon, which runs agents and keeps a journal and approvals; a Kheishfile is planned, applied and verified. — Conceptual architecture: callers submit, the daemon owns the execution.

THE TOUR

Durable, governed, declarative.

RUNS

Runs that survive their callers.

A session holds one active run and a queue behind it. Every turn is flushed to an append-only journal; after a restart the daemon rebuilds its queues and schedules, runs waiting on a human come back still waiting, and nothing is silently lost.

Eight run states, from queued to interrupted
Input and output contracts, checked fail-closed
Idempotency keys on inputs, approvals and answers

Air Runs on a Kheish daemon: runs with their session, state, origin, tasks and duration.

GOVERNANCE

Nothing risky runs without a yes.

Five permission modes decide what asks first. An approval shows the exact tool input, and the approver can edit it before allowing; a question offers up to four structured choices and can expire.

Approvals with an edited input and a justification
Questions with options, free answers and an expiry
Capability and credential scopes, narrowed for every sub-agent

Air Inbox on a Kheish daemon: a question and two shell command approvals waiting, each with Deny and Approve.

STACKS

Agents as code.

A Kheishfile declares personas, sessions, schedules and their scopes. The daemon plans, applies in reconciliation order and verifies, records what it owns in a ledger, and refuses any scope wider than declared.

init, validate, plan, diff, apply, verify, import, down
Secrets referenced and fingerprinted, never stored
Drift from the manifest detected

Kheishfile.yaml, from examples/stacks/linear-triage-daily

apiVersion: kheish.ai/v1alpha1
kind: KheishStack
metadata:
  name: linear-triage-daily
spec:
  apply:
    strict_scopes: true
  requires:
    secrets:
      - ref: mcp.linear.LINEAR_API_KEY
  personas:
    - persona_id: linear-triage-operator
      soul_file: persona.md
      capability_scope:
        mcp_server_allow: ["linear"]
  sessions:
    - session_id: linear-triage-daily
      persona_id: linear-triage-operator
      credential_scope:
        route_allow: ["openai"]
        connector_deny: ["*"]
  schedules:
    - name: linear-triage-daily
      target_session_id: linear-triage-daily
      cadence: { type: interval, every_seconds: 86400 }
      overlap_policy: skip

AUTOMATION

Work that starts on its own.

Schedules fire once, at an interval or on a cron with seconds and time zones, with overlap and misfire policies. A session goal keeps an idle agent working toward an objective, within a token budget.

Pause and resume keep the remaining time
Durable wake-ups an agent sets itself
At-least-once deliveries, with dead letters and replay

kheish-daemon schedules

$ kheish-daemon schedules create morning-triage triage \
    --cron "0 0 9 * * *" --timezone Europe/Paris \
    --overlap-policy skip \
    "Triage the issues opened since yesterday"

$ kheish-daemon schedules pause schedule-1
$ kheish-daemon schedules trigger-now schedule-1

MODEL ROUTES

Five providers, one routes file.

Routes are declared in TOML and can be added or removed while the daemon runs. Each run is pinned to its route, and a fallback model takes over once after a rate limit or an outage.

Provider	Native web search	Images	Audio	Transcription
`anthropic`	yes	—	—	—
`openai`	yes	yes	yes	yes
`google`	—	yes	—	—
`openrouter`	—	yes	yes	yes
`xai`	yes	yes	—	—

A pack that keeps walking.

Sub-agents split the work: plan, verify, coordinate, each in the shared workspace or its own git worktree. A child never gets more permission than its parent, and quotas bound depth, fan-out and spend.

COMMAND LINE

One binary, daemon and client.

The same kheish-daemon executable serves the API and drives it, with 31 commands over sessions, runs, approvals, stacks, schedules and more.

kheish-daemon up# start with zero config, open the console

kheish-daemon sessions create triage --persona-id analyst# a durable session

kheish-daemon sessions input triage "Triage the new issues"# submit, then leave

kheish-daemon approvals allow triage <request-id> --justification "read-only"# a human says yes

kheish-daemon runs wait run-42# come back when you want

kheish-daemon stack apply -f Kheishfile.yaml# agents as code

ACCOUNTABLE BY DESIGN

Every action under a named authority.

Signed audit
External actions go to an append-only, hash-chained ledger signed with Ed25519, fail-closed.
Brokered leases
Routes, connectors and MCP servers get short-lived, revocable credential leases, never raw keys.
Write-only secrets
One encrypted store under a master key; a secret can be set or used, never read back.
Hooks
27 events and 5 executor types, failing open or closed, with their own dead letters.
Guarded network
Outbound HTTP, web fetches and hooks are protected against server-side request forgery.
A stated threat model
The docs say what Kheish does not protect against: a compromised host, a leaked master key, the model itself.

EVERY FEATURE

Everything the daemon does.

The full list, area by area, as the code ships it today.

Durable execution

Append-only journal, flushed three times per turn
Restart recovery of queues, approvals, questions, schedules and deliveries
A run cut by a restart is marked interrupted, never silently dropped
Idempotency keys on inputs, approvals and answers
Offline journal vacuum with a verified, atomic swap
One state root, locked by a single daemon

Sessions and runs

One active run per session, with a queue behind it
Ten run kinds: input, goal, schedule, mailbox, channel, resumes and more
Input and output contracts, fail-closed, with a repair budget
Personas: a soul, a scope and default skills, snapshotted per session
Goals that keep an idle session working, within a token budget
A turn ceiling and a daemon-wide model budget
Automatic context compaction, with hooks before and after
Images and audio as input, and a file store for assets

Sub-agents and tasks

Sub-agents typed default, plan, verification or coordinator
The shared workspace or a git worktree per child
Mailboxes with acknowledgements and dead letters
A child’s question surfaces on its parent’s session
Background tasks with their output kept on disk
Quotas on depth, fan-out, spawns and spend

Governance

Five permission modes, with rules per user, project and session, and a dry-run explainer
Approvals that can edit the tool input before it runs
One to four questions per request, each with two to four options, and an expiry
Capability and credential scopes, intersected with the persona’s
Brokered, short-lived, revocable credential leases
Operator contact: notify or ask a named human

Tools and integrations

59 built-in tools: files, shell, patches, search, web, media, scheduling, agents
MCP over stdio or HTTP, with OAuth, resources and a catalog of 17 servers
Model routes and MCP servers added live, without a restart
Per-session route policy with reasoning effort and budgets
Byte, time and parallelism limits on tools, tunable live
78 bundled skills, plus your own SKILL.md
Connectors for Telegram, Slack and signed HTTP
Sidecars for Discord, email, SMS and webhooks; Matrix best-effort; Signal and WhatsApp experimental
Encrypted, write-only secret store; Codex and Claude Code accounts importable

Automation

Schedules: once, at an interval, or cron with seconds and time zones
Overlap and misfire policies, pause and resume
Stacks: plan, diff, apply, verify, import and tear down, with an ownership ledger
Playbooks released through verified, canary and active
Flows that require evidence before they complete
At-least-once deliveries, dead letters and replay

Collaboration

Channels where people and agents talk, with threads and reactions
@mentions, four participation modes and turn leases against reply storms
An autonomy policy: speakers, cooldowns and quiet periods
Projects with task dependencies that agents claim themselves
Boards: shared whiteboards agents draw on

Memory and learning

Recovered run memory, scrubbed of personal data
Learnings: facts, preferences and decisions, scoped to a session, persona, project or workspace
Shadow mode by default; anything that looks like a secret is rejected
Procedures promoted to skills through draft, verified, canary and active

Capture

Screen, webcam and microphone sources, each with its own upload token
Transcription and previews as derivations, turned into runs at once or on a schedule
Capture agents provisioned per machine, revocable in one command