Skip to content
Back to search

loopengine

A minimal framework for building your own AI agent platforms.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/loopengine-co--loopengine/badge.svg)](/listings/loopengine-co--loopengine)

HTML

<a href="/listings/loopengine-co--loopengine"><img src="/api/listings/loopengine-co--loopengine/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npx create-loopengine@latest my-agents
cd my-agents
npm install
cp .env.example .env   # fill in ANTHROPIC_API_KEY
npm run dev             # HTTP server on :8787 — same as `npx loopengine dev`

This scaffolds a standalone project — its own repo, with `loopengine` as a dependency, a starter agent, and CLI + HTTP adapters already wired up. That's the intended way to use LoopEngine: an independent project you own and build agents in, not a library you import into an existing app.

Define your first agent

npx loopengine add-agent weather-agent
# -> Created agents/weather-agent/index.ts

That's the fastest way to start: it generates `agents/<name>/index.ts` with a working `AgentConfig` stub, so you don't have to memorize the folder shape by hand. Or write it yourself — an agent is just an `AgentConfig`: `name`, `systemPrompt`, `tools`, `rules`, and a `model`. Drop it in a folder under `agents/` — `agents/<name>/index.ts` — and it's picked up automatically, no registry to edit, no import to add.

Most fields don't even need to be written out — they default to a conventional path under the agent's own folder:

| Field | Defaults to | | --- | --- | | `rules` | `agents/<name>/actauth.yml` (missing → deny everything) | | `tools` | `agents/<name>/tools/index.ts`'s exported `tools` (missing → no tools) | | `skillsDirs` | `agents/<name>/skills` (missing → no skills) |

There's no `subagents` field to omit — `agents/<name>/subagents/*` is its own folder convention (drop another agent's folder there and it becomes one of this agent's tools automatically), always merged into `tools` on top of whatever the table above resolves to.

`rules` is how you gate what a tool can do without approval — each rule maps a `scope` (tenant/environment) + tool name to `allow`/`ask`/`deny`, with an `ask` decision routing to a human — see [Human in the loop](#human-in-the-loop) below.

The simplest possible agent, `agents/weather-agent/index.ts` — `tools`, `rules`, and `skillsDirs` all omitted, so they default to `agents/weather-agent/tools/`, `actauth.yml`, and `skills/`:

import type { AgentConfig } from '../../agent-config.js'

export const config: AgentConfig = {
  name: 'weather-agent',
  systemPrompt: 'You answer questions about the weather.',
  model: { provider: 'anthropic', model: 'claude-sonnet-5-5' }, // reads ANTHROPIC_API_KEY
}

See `agents/customer-service/` and `agents/file-agent/` for complete, working examples.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 491 lines
  1. # LoopEngine
  2. [![CI](https://github.com/loopengine-co/loopengine/actions/workflows/ci.yml/badge.svg)](https://github.com/loopengine-co/loopengine/actions/workflows/ci.yml)
  3. LoopEngine is a runtime for building AI agents: a persona, a set of tools,
  4. and permission rules, run through a transparent ReAct loop. No chain DSL,
  5. no hidden control flow — `core/run-agent.ts` is a single function you can read
  6. top to bottom. Run agents over a CLI, an HTTP API, or both.
  7. ## Why LoopEngine
  8. - **Up and running in one command.** `npx create-loopengine@latest` scaffolds
  9. a real, standalone project — its own repo, a starter agent, CLI and HTTP
  10. adapters already wired up. `npm install && npm run dev` and you have a
  11. running agent server, not a half-finished template to wire up yourself.
  12. - **A real Admin UI, not just logs.** Open `/agents/config` in a browser to
  13. see and edit a live agent: its resolved config, permission rules, skills,
  14. tool connections, and secrets — no redeploy to change a rule or add a
  15. skill. See [Admin UI](#admin-ui) below.
  16. - **Human-in-the-loop, wired for real notification channels.** A risky tool
  17. call or a genuinely ambiguous question routes to a human — live in a chat
  18. session, or durably via Slack, Lark, email, a generic webhook, or a
  19. polling queue, resumable minutes or days later. See
  20. [Human in the loop](#human-in-the-loop) below.
  21. - **Sessions persist automatically.** Send a message, get a reply, come
  22. back later with the same session id and continue — no database to wire
  23. up yourself, and it survives a crash mid-turn cleanly.
  24. - **An ability system for reusable capabilities.** Install a bundle of
  25. tools, a skill, and the permission rules that gate them with one command
  26. — real, reviewable files in your own repo, not an opaque dependency. See
  27. [Ability system](#ability-system) below.
  28. - **Does real work, safely.** Tools can hit a database, send emails, call
  29. GitHub/Slack, anything with an `execute` function. Permission rules gate
  30. what happens without a human: safe reads auto-run, risky actions get
  31. approval or are denied outright.
  32. - **Multi-tenant and composable out of the box.** The same deployed agent
  33. serves different customers with different permission levels, no forking
  34. required — and one agent's folder drops under another's `subagents/` to
  35. become a tool the parent can delegate to, own tools/rules/loop intact.
  36. So the payoff: you write one `AgentConfig`, and get a deployable,
  37. persistent, permission-safe service — not just a prompt-and-response demo.
  38. ## Quick start
  39. ```bash
  40. npx create-loopengine@latest my-agents
  41. cd my-agents
  42. npm install
  43. cp .env.example .env # fill in ANTHROPIC_API_KEY
  44. npm run dev # HTTP server on :8787 — same as `npx loopengine dev`
  45. ```
  46. This scaffolds a standalone project — its own repo, with `loopengine` as
  47. a dependency, a starter agent, and CLI + HTTP adapters already wired up.
  48. That's the intended way to use LoopEngine: an independent project you own
  49. and build agents in, not a library you import into an existing app.
  50. ### Define your first agent
  51. ```bash
  52. npx loopengine add-agent weather-agent
  53. # -> Created agents/weather-agent/index.ts
  54. ```
  55. That's the fastest way to start: it generates `agents/<name>/index.ts`
  56. with a working `AgentConfig` stub, so you don't have to memorize the
  57. folder shape by hand. Or write it yourself — an agent is just an
  58. `AgentConfig`: `name`, `systemPrompt`, `tools`, `rules`, and a `model`.
  59. Drop it in a folder under `agents/` — `agents/<name>/index.ts` — and it's
  60. picked up automatically, no registry to edit, no import to add.
  61. Most fields don't even need to be written out — they default to a
  62. conventional path under the agent's own folder:
  63. | Field | Defaults to |
  64. | --- | --- |
  65. | `rules` | `agents/<name>/actauth.yml` (missing → deny everything) |
  66. | `tools` | `agents/<name>/tools/index.ts`'s exported `tools` (missing → no tools) |
  67. | `skillsDirs` | `agents/<name>/skills` (missing → no skills) |
  68. There's no `subagents` field to omit — `agents/<name>/subagents/*` is its
  69. own folder convention (drop another agent's folder there and it becomes
  70. one of this agent's tools automatically), always merged into `tools` on
  71. top of whatever the table above resolves to.
  72. `rules` is how you gate what a tool can do without approval — each rule
  73. maps a `scope` (tenant/environment) + tool name to `allow`/`ask`/`deny`,
  74. with an `ask` decision routing to a human — see
  75. [Human in the loop](#human-in-the-loop) below.
  76. The simplest possible agent, `agents/weather-agent/index.ts` — `tools`,
  77. `rules`, and `skillsDirs` all omitted, so they default to
  78. `agents/weather-agent/tools/`, `actauth.yml`, and `skills/`:
  79. ```ts
  80. import type { AgentConfig } from '../../agent-config.js'
  81. export const config: AgentConfig = {
  82. name: 'weather-agent',
  83. systemPrompt: 'You answer questions about the weather.',
  84. model: { provider: 'anthropic', model: 'claude-sonnet-5-5' }, // reads ANTHROPIC_API_KEY
  85. }
  86. ```
  87. See `agents/customer-service/` and `agents/file-agent/` for complete,
  88. working examples.
  89. ## Admin UI
  90. Run the HTTP adapter and open `http://localhost:8787/agents` — one
  91. console for every registered agent: a sidebar of agents (with a badge
  92. when one still needs a setting), and for each agent a set of tabs. No
  93. code changes or redeploy needed for most of it:
  94. | Tab | What you can do |
  95. | --- | --- |
  96. | **Chat** | Talk to the agent, approve or deny tool calls as they come up, and follow each step (model calls, tool calls, permission checks) in the Run trace. Past conversations are under History. |
  97. | **Overview** | A card per tab (tools, permissions, skills, settings), plus the system prompt, model, hooks and limits, each editable in place. |
  98. | **Abilities** | Install, upgrade, and uninstall abilities (see [Ability system](#ability-system)). |
  99. | **Tools** | Your hand-written tools, tools from integrations (e.g. [Composio](https://composio.dev)) and subagents, with whether each call runs on its own, asks first, or is denied. Build an HTTP tool or connect an integration without touching a file. |
  100. | **Skills** | Create, edit, and delete `SKILL.md` files for this agent directly in the browser — write the body, preview the rendered markdown, save. |
  101. | **Permissions** | Add, edit, and delete permission rules (actauth) — who, tool, decision — and choose what happens when no rule matches. |
  102. | **Schedules** | One of the agent's workflows (with values for its parameters), or a custom message, run on a timer — once at a set time, or every N minutes/hours/days. A workflow schedule starts each run with the workflow's start message and steps as they are then. Run now, pause, resume, cancel, see each run's result, and optionally send results through the agent's notifier. |
  103. | **Environment** | Every setting an installed ability reads, with its project-wide value and this agent's own value side by side, and which one the agent actually uses. A secret is never shown again once set. |
  104. Models and Integrations in the sidebar show which model providers have a
  105. key set and which outside tool sources are connected. Tabs deep-link:
  106. `/agents/config?agent=<name>&tab=tools`, `/playground?agent=<name>` for
  107. Chat.
  108. Every tab is backed by a real API (`GET /agents/:name/config`, `.../actauth`,
  109. `.../env`, ...) that reuses the exact same resolution `runAgent()` itself
  110. uses — so what you see here can't drift out of sync with what a real
  111. request actually gets, and never returns a model API key.
  112. ## Human in the loop
  113. A risky tool call (`actauth`'s `ask` decision) or a genuinely ambiguous
  114. question the model itself raises both need a human — and LoopEngine
  115. handles both the same way, live or durable:
  116. - **Live** — someone's actively watching right now (a terminal, an open
  117. chat session). The turn just waits; `cli`/`http_stream` get this
  118. automatically, with nothing to configure.
  119. - **Durable** — nobody's watching (a webhook-triggered run, a ticket that
  120. came in overnight). The turn ends immediately with a resumable pending
  121. state, and a real notification goes out on whichever channel you've
  122. configured — resolvable minutes or days later without holding any
  123. process open in between.
  124. Six channels ship as real, working notifiers — configure one and the
  125. "send a notification" side is done for you:
  126. | Channel | What it does |
  127. | --- | --- |
  128. | `webhook` | Signed HMAC-SHA256 POST to any URL you own |
  129. | `slack` | An interactive message via `chat.postMessage`, with Approve/Deny buttons |
  130. | `lark` | A Lark/Feishu interactive card |
  131. | `email` | An email per decision, through your own `sendEmail`: with signed, expiring magic links to your endpoints, or a link to this server's decision page |
  132. | `database` | Writes a row for your own worker/dashboard to poll |
  133. | `redis` | Pushes a queue entry for your own worker to consume |
  134. ```ts
  135. export const config: AgentConfig = {
  136. // ...
  137. httpNotifier: {
  138. channel: 'slack',
  139. config: { botToken: process.env.SLACK_BOT_TOKEN!, channelId: process.env.SLACK_CHANNEL_ID! },
  140. events: ['approval', 'question'],
  141. },
  142. }
  143. ```
  144. Or skip the code: in the console, the agent's **Messaging** tab sets a
  145. webhook, Slack, Lark or email target for one agent (email sends through
  146. Resend, SendGrid or Postmark with your API key, each email linking to the
  147. decision page) (saved to
  148. `agents/<name>/messaging.yml`, with its secret in the agent's own `.env`;
  149. an older `notifier.yml` is still read), sends a test and shows recent
  150. deliveries. With Slack, people can also reply in a request's thread to
  151. ask the agent about it, and it answers there (**Answer replies in a
  152. request's thread**, on by default). **Approvers**, picked from the
  153. channel's members, can also decide a request by replying ("yes, go
  154. ahead", "no", or the answer to a question); a separate model call reads
  155. only their own message to tell whether it's a decision, and anything
  156. unclear is treated as a question. An approver can also change a request
  157. first ("make it $40"): the change is checked against the tool's schema
  158. and the permission rules and shown with **Approve as changed / Keep
  159. original / Deny**, and nothing runs until they approve it. A plain "yes"
  160. ("approve", "go ahead", "好的", "はい", "sí", 👍…: the whole message,
  161. matched against a fixed list of phrases in common languages, not by a
  162. model) runs it; any other reply read as approval ("sure, send
  163. it", "yes but check the amount") shows exactly what will run with a
  164. **Confirm** button, and only that click runs it. Arguments are shown
  165. as labelled fields, with long text such as an email body quoted, not as
  166. JSON. Once approvers are listed, only their button clicks count too. The same tab lists every decision
  167. still waiting with Approve/Deny buttons (its count shows on the tab), and
  168. warns you when an agent has `ask` rules but nobody would be told.
  169. Not sure what to automate? The console's **Find your first agent**
  170. (`/interview`, linked from the sidebar and the Agents page) is a short
  171. interview about your work, in any language. It suggests up to three
  172. agents worth building, ranked by the time they'd save, and creates the
  173. one you pick: its instructions, permissions where every tool asks you
  174. first, and a paused schedule if it runs on a timer, plus a checklist of
  175. what's left to connect. The interviewer runs on the model of one of your
  176. agents, can't see your systems, and creates nothing until you click.
  177. Or skip the interview: **Templates** (`/templates`, linked from the
  178. sidebar and the Agents page) are ready-made agents: answer customer
  179. emails, refund approvals, triage incidents, check expense claims, lead
  180. follow-up, inbox to tasks, and a weekly research digest. Preview one's instructions and setup checklist, then create it
  181. the same way, as many times as you like. Templates live in
  182. `core/system-agents/templates.ts`, in the same shape the interview
  183. suggests.
  184. Every notification links to a **decision page**: a signed, single-use
  185. link (`/decide/<token>`, valid 7 days) where whoever got the message can
  186. approve, deny, edit the arguments or answer a question, with no login and
  187. no app of your own. So the quickest setup is Slack: create the Slack app
  188. from the manifest the console shows, paste its bot token, pick a channel
  189. from the list, save; each approval arrives with an "Open to approve or
  190. deny" link. Add the app's signing secret too and the message also gets
  191. Approve/Deny buttons, handled by LoopEngine itself at
  192. `/hooks/slack/<agent>`, with no handler to deploy. Lark cards carry the
  193. same link. Links and buttons need the server to be reachable from where
  194. people click (a public HTTPS address or a tunnel).
  195. For a third-party app calling an agent over plain HTTP:
  196. 1. `POST /agents/<name>/messages` → when a call needs approval, the reply
  197. has `stopReason: "pending_approval"` and a `pending` list, each item
  198. with its `pendingId` and `resolvePath`.
  199. 2. The webhook carries the same `pendingId`, `resolvePath` (and a full
  200. `resolveUrl` when `LOOPENGINE_PUBLIC_URL` is set), signed with
  201. `X-Actauth-Signature`. Failed deliveries are retried.
  202. 3. `POST <resolvePath>` with `{"decision":"approve"}` (or `"deny"`) runs
  203. the tool, resumes the turn, and returns the agent's reply.
  204. `GET /agents/<name>/pending` lists what's waiting, for apps that poll
  205. instead of receiving webhooks.
  206. Reference implementations for the receiving side (verifying a Slack
  207. click, a webhook HMAC signature, a magic-link token) ship under
  208. `examples/notifier-handler/` for the four channels that need one. See
  209. [`HUMAN_IN_THE_LOOP.md`](HUMAN_IN_THE_LOOP.md) for the full setup guide —
  210. live and durable, worked examples, and how resumption actually works
  211. under the hood.
  212. ## Scheduled tasks
  213. The server runs one scheduler (`core/scheduler.ts`) that sends a message
  214. to an agent later — once (`run_at`) or on an interval (`every: "1h"`),
  215. optionally from a set first run (`start_at`), which every later run keeps:
  216. `every: "1d"` from a 9:00 start runs daily at 9:00, `every: "7d"` from a
  217. Monday runs on Mondays. `at: "09:00"` (plus `weekday: "monday"`) picks
  218. that start for you. Times of day are in the workspace's time zone, chosen
  219. in the console's **Settings** (`LOOPENGINE_TIME_ZONE`; the server's own
  220. when unset): a timestamp without an offset is read there, and daily and
  221. weekly tasks keep their time of day when the clocks change. Schedule
  222. from the console's **Schedules** tab, the `GET/POST
  223. /agents/<name>/schedules` API, or the agent itself: every agent has
  224. built-in `system_schedule_task`, `system_list_scheduled_tasks`,
  225. `system_check_scheduled_task` and `system_cancel_scheduled_task` tools,
  226. so "remind me tomorrow at 9" just works. An
  227. agent can only schedule, see or cancel its own tasks, up to 25 active at
  228. a time (`LOOPENGINE_SCHEDULER_MAX_PER_AGENT`); `selfScheduling: false` in
  229. its config removes the tools. Tasks left by the old `lp-task-scheduler`
  230. ability are imported at start. Each run goes through the same
  231. path as an HTTP call: an approval goes wherever the Permissions tab sends
  232. it (and resumes the run once decided); with nowhere set, a call that
  233. needs approval is denied. Intervals keep their original slot (an hourly
  234. task created at 10:07 stays on :07); a run missed while the server was
  235. down fires once when it's back. Tasks live in `.scheduler/` (or
  236. `LOOPENGINE_SCHEDULER_DIR`); the tick is `LOOPENGINE_SCHEDULER_TICK_MS`
  237. (10 s); `LOOPENGINE_SCHEDULER=off` turns the loop off for this process.
  238. Behind a hosting platform, `GET /internal/activity` reports `nextWakeAt`
  239. and `POST /internal/scheduler/tick` fires whatever is due, so a stopped
  240. server can be woken in time.
  241. ## Ability system
  242. Giving an agent a new capability is usually three separate, hand-authored
  243. things: a tool file, a `SKILL.md` teaching the model when to use it, and
  244. an `actauth` rule allowing it to actually run. A **loopengine ability**
  245. bundles all three into one installable unit:
  246. ```bash
  247. npx loopengine add-ability <spec> --agent customer-service
  248. ```
  249. `<spec>` is anything `npm pack` understands — a public or private npm
  250. package, a scoped package on a private registry, or a plain git repo. The
  251. tool files, skill directory, and actauth rules all land as real files in
  252. the agent's own tree, copied in rather than imported as a `node_modules`
  253. dependency — reviewable, diffable, and editable the same as anything you
  254. would have hand-written, not an opaque black box.
  255. ```bash
  256. npx loopengine upgrade-ability <abilityName> --agent customer-service
  257. npx loopengine remove-ability <abilityName> --agent customer-service
  258. ```
  259. Upgrading does a real three-way merge per file — a hand-edit since install
  260. survives, a genuine conflict leaves `<<<<<<<` markers to resolve by hand
  261. instead of silently overwriting either side. Removing refuses a file
  262. that's been modified since install unless you pass `--force`. An ability
  263. can also declare the env vars its tools need, which then show up in the
  264. Admin UI's [Environment tab](#admin-ui) automatically once installed. See
  265. [`ABILITIES.md`](ABILITIES.md) for the full design — format, publishing,
  266. and how the merge/upgrade mechanics work in detail.
  267. ## Running an agent
  268. `adapters/cli.ts` and `adapters/http.ts` are files your own scaffolded
  269. project owns (see "Quick start" above), not something hidden inside the
  270. `loopengine` package — run them directly with `tsx`, or through shorter
  271. `loopengine` commands that just call the same files for you:
  272. ```bash
  273. npx loopengine run customer-service --session s1 "order A-1001 arrived broken"
  274. npx loopengine run customer-service --session s1 --input "order A-1001 arrived broken"
  275. npx loopengine serve # HTTP server on :8787
  276. npx loopengine dev # same server, restarts on file changes (tsx watch)
  277. ```
  278. `--session <id>` is just an arbitrary string you pick — `s1` above isn't
  279. special, it's only a label. Omit it entirely for a fresh, one-off
  280. conversation each call; reuse the same value on a later call to continue
  281. that exact conversation (the id is printed to stderr if you omit it, so
  282. you can capture it for next time). `--input "<message>"` is an
  283. alternative to the trailing positional message, for scripts that build
  284. the argument list programmatically and would rather not depend on the
  285. message always being the last argument.
  286. `run`/`serve`/`dev` are thin wrappers, not a separate implementation —
  287. each shells out to your project's own `adapters/cli.ts` or
  288. `adapters/http.ts` via `npx tsx` (so it's always *your* copy that runs,
  289. edits included, resolved from your project's own `node_modules`), and
  290. fails with a clear message pointing at `create-loopengine` if that file
  291. doesn't exist yet. `.env` is loaded automatically for all three,
  292. equivalent to passing `--env-file-if-exists=.env` to `tsx` yourself.
  293. The same thing, spelled out without the wrapper:
  294. **CLI:**
  295. ```bash
  296. npx tsx adapters/cli.ts --agent customer-service --session s1 "order A-1001 arrived broken"
  297. ```
  298. **HTTP:**
  299. ```bash
  300. npx tsx --env-file-if-exists=.env adapters/http.ts
  301. curl -X POST localhost:8787/agents/customer-service/messages \
  302. -H 'content-type: application/json' \
  303. -d '{"customerEmail":"a@example.com","message":"order A-1001 arrived broken"}'
  304. ```
  305. Add `/stream` to the URL for a Server-Sent Events response — one event per
  306. loop step (tool call, permission decision, budget check) instead of a
  307. single reply at the end.
  308. Three small browser pages, all cross-linked, share one look
  309. (`adapters/dev-ui-styles.ts`), and never need a build step — each is a
  310. self-contained HTML string served straight out of `adapters/http.ts`:
  311. **Agents list:** open `http://localhost:8787/agents` in a browser (the
  312. same route returns plain `{agents: [...]}` JSON to a non-browser client —
  313. content-negotiated on the `Accept` header, so nothing that already calls
  314. it as an API needs to change) to see every registered agent with links
  315. into the playground and config page below.
  316. **Chat:** open `http://localhost:8787/playground` (optionally
  317. `?agent=<name>` to preselect one) — the console's Chat tab: talk to an
  318. agent and watch the loop-step event stream render live in the Run trace
  319. instead of reading raw SSE frames. Same `/messages/stream` route
  320. underneath.
  321. **Building your own client:** the playground is one UI on top of a typed
  322. event protocol, not the only way to consume a turn — see
  323. [`PROTOCOL.md`](PROTOCOL.md) for the full `LoopEvent` catalog, the SSE/
  324. plain-HTTP/CLI transport bindings, and a JSON Schema
  325. (`protocol/loop-event.schema.json`) any language can validate against.
  326. `core/client.ts` and the `examples/chatbox/react`/`examples/chatbox/vue`
  327. hooks are reference implementations of it.
  328. **Agent config page:** this is the [Admin UI](#admin-ui) described above
  329. — open `http://localhost:8787/agents/config` (optionally `?agent=<name>`).
  330. ## Wiring a real model
  331. Declare `AgentConfig.model` and the runtime builds a real `ModelCall` for
  332. you, using the matching API key from the environment:
  333. | `provider` | env var | `model` required? |
  334. | --- | --- | --- |
  335. | `'anthropic'` | `ANTHROPIC_API_KEY` | no — defaults to `claude-sonnet-5-5` |
  336. | `'openai'` | `OPENAI_API_KEY` | yes |
  337. | `'deepseek'` | `DEEPSEEK_API_KEY` | yes |
  338. | `'kimi'` | `MOONSHOT_API_KEY` | yes |
  339. | `'glm'` | `GLM_API_KEY` | yes |
  340. | `'gemini'` | `GEMINI_API_KEY` | yes |
  341. | `'xai'` | `XAI_API_KEY` | yes |
  342. | `'meta'` | `META_API_KEY` | yes |
  343. `'kimi'`'s env var is `MOONSHOT_API_KEY`, not `KIMI_API_KEY` — deliberate,
  344. matching Moonshot AI's own docs (the API/company behind Kimi) rather than
  345. this package's own provider name. `'meta'` (Meta's Muse models, e.g.
  346. `muse-spark-1.3`, through the Meta Model API) reads `META_API_KEY`,
  347. LiteLLM's name, rather than the generic `MODEL_API_KEY` in Meta's own
  348. examples. `openai`/`deepseek`/`kimi`/`glm`/`gemini`/`xai`/`meta` all reuse the same OpenAI-Chat-Completions-compatible request
  349. translation, just pointed at each provider's own base URL — see
  350. `core/model-calls/*.ts` for the provider-specific details (base URLs,
  351. `max_completion_tokens` vs `max_tokens`, and Gemini's own "still in beta"
  352. caveat on Google's compatibility layer).
  353. The console's model dropdown (New agent, and an agent's Model > Edit)
  354. lists each provider's models live from its API once its key is saved. To
  355. choose the list yourself, add a `models.yaml` next to `.env` mapping each
  356. provider to its models; a provider listed there offers exactly those, in
  357. that order, with no key needed, and edits show the next time the
  358. dropdown loads (`LOOPENGINE_MODELS_FILE` points at a different file):
  359. ```yaml
  360. anthropic:
  361. - claude-opus-5-5
  362. - claude-sonnet-5-5
  363. deepseek:
  364. - deepseek-v4-pro
  365. ```
  366. For anything else (a custom SDK client, a canned/simulated model for
  367. testing), export your own `createModelCall(): ModelCall` instead.
  368. ## Built on
  369. | Package | Responsibility |
  370. |---|---|
  371. | [`actauth`](https://www.npmjs.com/package/actauth) | Permission gating (allow/ask/deny/pending) with live and durable human-approval hooks |
  372. | `core/budget.ts` / `core/compaction.ts` | Context-window budget tracking and tail-preserving compaction (vendored in-repo, not an external dependency) |
  373. | `core/recovery.ts` | Retries prompt-too-long / truncated-output failures (vendored in-repo, not an external dependency) |
  374. | `core/durable-approvals.ts` | `TurnCheckpoint`/`CheckpointStore` (file/Redis) backing durable, resumable `ask` decisions — see `HUMAN_IN_THE_LOOP.md` |
  375. | `core/sessionknit.ts` | Durable session log with crash-interruption detection (vendored in-repo, not an external dependency) |
  376. | `core/skillgarden/` | `SKILL.md` discovery and lazy loading (vendored in-repo, not an external dependency) |
  377. | `core/toollane.ts` | Parallel/solo tool-call scheduling (vendored in-repo, not an external dependency) |
  378. | `core/mcpplug.ts` | Gateway tool sourcing (e.g. Composio) (vendored in-repo, not an external dependency) |
  379. Installing `loopengine` pulls in `actauth` as a regular dependency —
  380. install it directly only if you want to use it standalone. Everything
  381. else in this table ships inside `loopengine` itself.
  382. ## Deployment
  383. ```bash
  384. docker compose up --build
  385. ```
  386. Builds the HTTP adapter into a container and starts it alongside Redis.
  387. For production, push the image to any container platform with `REDIS_URL`
  388. and your model/tool API keys set as environment variables.
  389. ### Hosting behind a platform
  390. These settings are for running LoopEngine inside a hosting platform
  391. (one workspace per user, behind a router that has already authenticated
  392. them). All are off by default; a self-hosted install that doesn't set
  393. them behaves exactly as described above.
  394. | Setting | What it does |
  395. | --- | --- |
  396. | `LOOPENGINE_TRUSTED_PROXY_SECRET` | Every request must carry an `X-LoopEngine-Identity` header signed with this secret (`signProxyIdentity` creates one; unsigned requests get 401). `LOOPENGINE_ADMIN_AUTH`, if also set, still works for direct access. Also enables `GET /internal/activity`: in-flight turns, open streams and idle time, so the host never stops a server mid-turn. |
  397. | `LOOPENGINE_EXIT_ON_CODE_CHANGE=1` | After an ability install, upgrade, uninstall or dependency install through the Admin UI, the server drains and exits so the platform restarts it with the new code loaded. Only set this when something restarts the process. |
  398. | `LOOPENGINE_USAGE_LOG` | `stdout` (one JSON line per model call) or a file path (JSON lines) — tokens per call with agent, tenant, session and model. Or call `setUsageSink()` in code. |
  399. | `setSecretStore()` | In code, at startup: keep env values set through the Admin UI somewhere other than `.env` files (a vault, a secret manager). The default `FileSecretStore` is today's behaviour. |
  400. `GET /healthz` answers `{"ok":true}` with no login, on every server,
  401. for health checks; it returns 503 once the server starts shutting down,
  402. and doesn't count as activity.
  403. `deploy/workspace/Dockerfile` is a runtime image for this: it serves a
  404. scaffolded project mounted at `/workspace` instead of baking agents in.
  405. ## License
  406. LoopEngine is open source under the [MIT License](LICENSE): use, change,
  407. self-host and redistribute it for anything, commercial use included.
  408. Third-party software included in LoopEngine keeps its own license: see
  409. [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.