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
Markdown
[](/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
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
- # LoopEngine
- [](https://github.com/loopengine-co/loopengine/actions/workflows/ci.yml)
- LoopEngine is a runtime for building AI agents: a persona, a set of tools,
- and permission rules, run through a transparent ReAct loop. No chain DSL,
- no hidden control flow — `core/run-agent.ts` is a single function you can read
- top to bottom. Run agents over a CLI, an HTTP API, or both.
- ## Why LoopEngine
- - **Up and running in one command.** `npx create-loopengine@latest` scaffolds
- a real, standalone project — its own repo, a starter agent, CLI and HTTP
- adapters already wired up. `npm install && npm run dev` and you have a
- running agent server, not a half-finished template to wire up yourself.
- - **A real Admin UI, not just logs.** Open `/agents/config` in a browser to
- see and edit a live agent: its resolved config, permission rules, skills,
- tool connections, and secrets — no redeploy to change a rule or add a
- skill. See [Admin UI](#admin-ui) below.
- - **Human-in-the-loop, wired for real notification channels.** A risky tool
- call or a genuinely ambiguous question routes to a human — live in a chat
- session, or durably via Slack, Lark, email, a generic webhook, or a
- polling queue, resumable minutes or days later. See
- [Human in the loop](#human-in-the-loop) below.
- - **Sessions persist automatically.** Send a message, get a reply, come
- back later with the same session id and continue — no database to wire
- up yourself, and it survives a crash mid-turn cleanly.
- - **An ability system for reusable capabilities.** Install a bundle of
- tools, a skill, and the permission rules that gate them with one command
- — real, reviewable files in your own repo, not an opaque dependency. See
- [Ability system](#ability-system) below.
- - **Does real work, safely.** Tools can hit a database, send emails, call
- GitHub/Slack, anything with an `execute` function. Permission rules gate
- what happens without a human: safe reads auto-run, risky actions get
- approval or are denied outright.
- - **Multi-tenant and composable out of the box.** The same deployed agent
- serves different customers with different permission levels, no forking
- required — and one agent's folder drops under another's `subagents/` to
- become a tool the parent can delegate to, own tools/rules/loop intact.
- So the payoff: you write one `AgentConfig`, and get a deployable,
- persistent, permission-safe service — not just a prompt-and-response demo.
- ## Quick start
- ```bash
- 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
- ```bash
- 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/`:
- ```ts
- 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.
- ## Admin UI
- Run the HTTP adapter and open `http://localhost:8787/agents` — one
- console for every registered agent: a sidebar of agents (with a badge
- when one still needs a setting), and for each agent a set of tabs. No
- code changes or redeploy needed for most of it:
- | Tab | What you can do |
- | --- | --- |
- | **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. |
- | **Overview** | A card per tab (tools, permissions, skills, settings), plus the system prompt, model, hooks and limits, each editable in place. |
- | **Abilities** | Install, upgrade, and uninstall abilities (see [Ability system](#ability-system)). |
- | **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. |
- | **Skills** | Create, edit, and delete `SKILL.md` files for this agent directly in the browser — write the body, preview the rendered markdown, save. |
- | **Permissions** | Add, edit, and delete permission rules (actauth) — who, tool, decision — and choose what happens when no rule matches. |
- | **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. |
- | **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. |
- Models and Integrations in the sidebar show which model providers have a
- key set and which outside tool sources are connected. Tabs deep-link:
- `/agents/config?agent=<name>&tab=tools`, `/playground?agent=<name>` for
- Chat.
- Every tab is backed by a real API (`GET /agents/:name/config`, `.../actauth`,
- `.../env`, ...) that reuses the exact same resolution `runAgent()` itself
- uses — so what you see here can't drift out of sync with what a real
- request actually gets, and never returns a model API key.
- ## Human in the loop
- A risky tool call (`actauth`'s `ask` decision) or a genuinely ambiguous
- question the model itself raises both need a human — and LoopEngine
- handles both the same way, live or durable:
- - **Live** — someone's actively watching right now (a terminal, an open
- chat session). The turn just waits; `cli`/`http_stream` get this
- automatically, with nothing to configure.
- - **Durable** — nobody's watching (a webhook-triggered run, a ticket that
- came in overnight). The turn ends immediately with a resumable pending
- state, and a real notification goes out on whichever channel you've
- configured — resolvable minutes or days later without holding any
- process open in between.
- Six channels ship as real, working notifiers — configure one and the
- "send a notification" side is done for you:
- | Channel | What it does |
- | --- | --- |
- | `webhook` | Signed HMAC-SHA256 POST to any URL you own |
- | `slack` | An interactive message via `chat.postMessage`, with Approve/Deny buttons |
- | `lark` | A Lark/Feishu interactive card |
- | `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 |
- | `database` | Writes a row for your own worker/dashboard to poll |
- | `redis` | Pushes a queue entry for your own worker to consume |
- ```ts
- export const config: AgentConfig = {
- // ...
- httpNotifier: {
- channel: 'slack',
- config: { botToken: process.env.SLACK_BOT_TOKEN!, channelId: process.env.SLACK_CHANNEL_ID! },
- events: ['approval', 'question'],
- },
- }
- ```
- Or skip the code: in the console, the agent's **Messaging** tab sets a
- webhook, Slack, Lark or email target for one agent (email sends through
- Resend, SendGrid or Postmark with your API key, each email linking to the
- decision page) (saved to
- `agents/<name>/messaging.yml`, with its secret in the agent's own `.env`;
- an older `notifier.yml` is still read), sends a test and shows recent
- deliveries. With Slack, people can also reply in a request's thread to
- ask the agent about it, and it answers there (**Answer replies in a
- request's thread**, on by default). **Approvers**, picked from the
- channel's members, can also decide a request by replying ("yes, go
- ahead", "no", or the answer to a question); a separate model call reads
- only their own message to tell whether it's a decision, and anything
- unclear is treated as a question. An approver can also change a request
- first ("make it $40"): the change is checked against the tool's schema
- and the permission rules and shown with **Approve as changed / Keep
- original / Deny**, and nothing runs until they approve it. A plain "yes"
- ("approve", "go ahead", "好的", "はい", "sí", 👍…: the whole message,
- matched against a fixed list of phrases in common languages, not by a
- model) runs it; any other reply read as approval ("sure, send
- it", "yes but check the amount") shows exactly what will run with a
- **Confirm** button, and only that click runs it. Arguments are shown
- as labelled fields, with long text such as an email body quoted, not as
- JSON. Once approvers are listed, only their button clicks count too. The same tab lists every decision
- still waiting with Approve/Deny buttons (its count shows on the tab), and
- warns you when an agent has `ask` rules but nobody would be told.
- Not sure what to automate? The console's **Find your first agent**
- (`/interview`, linked from the sidebar and the Agents page) is a short
- interview about your work, in any language. It suggests up to three
- agents worth building, ranked by the time they'd save, and creates the
- one you pick: its instructions, permissions where every tool asks you
- first, and a paused schedule if it runs on a timer, plus a checklist of
- what's left to connect. The interviewer runs on the model of one of your
- agents, can't see your systems, and creates nothing until you click.
- Or skip the interview: **Templates** (`/templates`, linked from the
- sidebar and the Agents page) are ready-made agents: answer customer
- emails, refund approvals, triage incidents, check expense claims, lead
- follow-up, inbox to tasks, and a weekly research digest. Preview one's instructions and setup checklist, then create it
- the same way, as many times as you like. Templates live in
- `core/system-agents/templates.ts`, in the same shape the interview
- suggests.
- Every notification links to a **decision page**: a signed, single-use
- link (`/decide/<token>`, valid 7 days) where whoever got the message can
- approve, deny, edit the arguments or answer a question, with no login and
- no app of your own. So the quickest setup is Slack: create the Slack app
- from the manifest the console shows, paste its bot token, pick a channel
- from the list, save; each approval arrives with an "Open to approve or
- deny" link. Add the app's signing secret too and the message also gets
- Approve/Deny buttons, handled by LoopEngine itself at
- `/hooks/slack/<agent>`, with no handler to deploy. Lark cards carry the
- same link. Links and buttons need the server to be reachable from where
- people click (a public HTTPS address or a tunnel).
- For a third-party app calling an agent over plain HTTP:
- 1. `POST /agents/<name>/messages` → when a call needs approval, the reply
- has `stopReason: "pending_approval"` and a `pending` list, each item
- with its `pendingId` and `resolvePath`.
- 2. The webhook carries the same `pendingId`, `resolvePath` (and a full
- `resolveUrl` when `LOOPENGINE_PUBLIC_URL` is set), signed with
- `X-Actauth-Signature`. Failed deliveries are retried.
- 3. `POST <resolvePath>` with `{"decision":"approve"}` (or `"deny"`) runs
- the tool, resumes the turn, and returns the agent's reply.
- `GET /agents/<name>/pending` lists what's waiting, for apps that poll
- instead of receiving webhooks.
- Reference implementations for the receiving side (verifying a Slack
- click, a webhook HMAC signature, a magic-link token) ship under
- `examples/notifier-handler/` for the four channels that need one. See
- [`HUMAN_IN_THE_LOOP.md`](HUMAN_IN_THE_LOOP.md) for the full setup guide —
- live and durable, worked examples, and how resumption actually works
- under the hood.
- ## Scheduled tasks
- The server runs one scheduler (`core/scheduler.ts`) that sends a message
- to an agent later — once (`run_at`) or on an interval (`every: "1h"`),
- optionally from a set first run (`start_at`), which every later run keeps:
- `every: "1d"` from a 9:00 start runs daily at 9:00, `every: "7d"` from a
- Monday runs on Mondays. `at: "09:00"` (plus `weekday: "monday"`) picks
- that start for you. Times of day are in the workspace's time zone, chosen
- in the console's **Settings** (`LOOPENGINE_TIME_ZONE`; the server's own
- when unset): a timestamp without an offset is read there, and daily and
- weekly tasks keep their time of day when the clocks change. Schedule
- from the console's **Schedules** tab, the `GET/POST
- /agents/<name>/schedules` API, or the agent itself: every agent has
- built-in `system_schedule_task`, `system_list_scheduled_tasks`,
- `system_check_scheduled_task` and `system_cancel_scheduled_task` tools,
- so "remind me tomorrow at 9" just works. An
- agent can only schedule, see or cancel its own tasks, up to 25 active at
- a time (`LOOPENGINE_SCHEDULER_MAX_PER_AGENT`); `selfScheduling: false` in
- its config removes the tools. Tasks left by the old `lp-task-scheduler`
- ability are imported at start. Each run goes through the same
- path as an HTTP call: an approval goes wherever the Permissions tab sends
- it (and resumes the run once decided); with nowhere set, a call that
- needs approval is denied. Intervals keep their original slot (an hourly
- task created at 10:07 stays on :07); a run missed while the server was
- down fires once when it's back. Tasks live in `.scheduler/` (or
- `LOOPENGINE_SCHEDULER_DIR`); the tick is `LOOPENGINE_SCHEDULER_TICK_MS`
- (10 s); `LOOPENGINE_SCHEDULER=off` turns the loop off for this process.
- Behind a hosting platform, `GET /internal/activity` reports `nextWakeAt`
- and `POST /internal/scheduler/tick` fires whatever is due, so a stopped
- server can be woken in time.
- ## Ability system
- Giving an agent a new capability is usually three separate, hand-authored
- things: a tool file, a `SKILL.md` teaching the model when to use it, and
- an `actauth` rule allowing it to actually run. A **loopengine ability**
- bundles all three into one installable unit:
- ```bash
- npx loopengine add-ability <spec> --agent customer-service
- ```
- `<spec>` is anything `npm pack` understands — a public or private npm
- package, a scoped package on a private registry, or a plain git repo. The
- tool files, skill directory, and actauth rules all land as real files in
- the agent's own tree, copied in rather than imported as a `node_modules`
- dependency — reviewable, diffable, and editable the same as anything you
- would have hand-written, not an opaque black box.
- ```bash
- npx loopengine upgrade-ability <abilityName> --agent customer-service
- npx loopengine remove-ability <abilityName> --agent customer-service
- ```
- Upgrading does a real three-way merge per file — a hand-edit since install
- survives, a genuine conflict leaves `<<<<<<<` markers to resolve by hand
- instead of silently overwriting either side. Removing refuses a file
- that's been modified since install unless you pass `--force`. An ability
- can also declare the env vars its tools need, which then show up in the
- Admin UI's [Environment tab](#admin-ui) automatically once installed. See
- [`ABILITIES.md`](ABILITIES.md) for the full design — format, publishing,
- and how the merge/upgrade mechanics work in detail.
- ## Running an agent
- `adapters/cli.ts` and `adapters/http.ts` are files your own scaffolded
- project owns (see "Quick start" above), not something hidden inside the
- `loopengine` package — run them directly with `tsx`, or through shorter
- `loopengine` commands that just call the same files for you:
- ```bash
- npx loopengine run customer-service --session s1 "order A-1001 arrived broken"
- npx loopengine run customer-service --session s1 --input "order A-1001 arrived broken"
- npx loopengine serve # HTTP server on :8787
- npx loopengine dev # same server, restarts on file changes (tsx watch)
- ```
- `--session <id>` is just an arbitrary string you pick — `s1` above isn't
- special, it's only a label. Omit it entirely for a fresh, one-off
- conversation each call; reuse the same value on a later call to continue
- that exact conversation (the id is printed to stderr if you omit it, so
- you can capture it for next time). `--input "<message>"` is an
- alternative to the trailing positional message, for scripts that build
- the argument list programmatically and would rather not depend on the
- message always being the last argument.
- `run`/`serve`/`dev` are thin wrappers, not a separate implementation —
- each shells out to your project's own `adapters/cli.ts` or
- `adapters/http.ts` via `npx tsx` (so it's always *your* copy that runs,
- edits included, resolved from your project's own `node_modules`), and
- fails with a clear message pointing at `create-loopengine` if that file
- doesn't exist yet. `.env` is loaded automatically for all three,
- equivalent to passing `--env-file-if-exists=.env` to `tsx` yourself.
- The same thing, spelled out without the wrapper:
- **CLI:**
- ```bash
- npx tsx adapters/cli.ts --agent customer-service --session s1 "order A-1001 arrived broken"
- ```
- **HTTP:**
- ```bash
- npx tsx --env-file-if-exists=.env adapters/http.ts
- curl -X POST localhost:8787/agents/customer-service/messages \
- -H 'content-type: application/json' \
- -d '{"customerEmail":"a@example.com","message":"order A-1001 arrived broken"}'
- ```
- Add `/stream` to the URL for a Server-Sent Events response — one event per
- loop step (tool call, permission decision, budget check) instead of a
- single reply at the end.
- Three small browser pages, all cross-linked, share one look
- (`adapters/dev-ui-styles.ts`), and never need a build step — each is a
- self-contained HTML string served straight out of `adapters/http.ts`:
- **Agents list:** open `http://localhost:8787/agents` in a browser (the
- same route returns plain `{agents: [...]}` JSON to a non-browser client —
- content-negotiated on the `Accept` header, so nothing that already calls
- it as an API needs to change) to see every registered agent with links
- into the playground and config page below.
- **Chat:** open `http://localhost:8787/playground` (optionally
- `?agent=<name>` to preselect one) — the console's Chat tab: talk to an
- agent and watch the loop-step event stream render live in the Run trace
- instead of reading raw SSE frames. Same `/messages/stream` route
- underneath.
- **Building your own client:** the playground is one UI on top of a typed
- event protocol, not the only way to consume a turn — see
- [`PROTOCOL.md`](PROTOCOL.md) for the full `LoopEvent` catalog, the SSE/
- plain-HTTP/CLI transport bindings, and a JSON Schema
- (`protocol/loop-event.schema.json`) any language can validate against.
- `core/client.ts` and the `examples/chatbox/react`/`examples/chatbox/vue`
- hooks are reference implementations of it.
- **Agent config page:** this is the [Admin UI](#admin-ui) described above
- — open `http://localhost:8787/agents/config` (optionally `?agent=<name>`).
- ## Wiring a real model
- Declare `AgentConfig.model` and the runtime builds a real `ModelCall` for
- you, using the matching API key from the environment:
- | `provider` | env var | `model` required? |
- | --- | --- | --- |
- | `'anthropic'` | `ANTHROPIC_API_KEY` | no — defaults to `claude-sonnet-5-5` |
- | `'openai'` | `OPENAI_API_KEY` | yes |
- | `'deepseek'` | `DEEPSEEK_API_KEY` | yes |
- | `'kimi'` | `MOONSHOT_API_KEY` | yes |
- | `'glm'` | `GLM_API_KEY` | yes |
- | `'gemini'` | `GEMINI_API_KEY` | yes |
- | `'xai'` | `XAI_API_KEY` | yes |
- | `'meta'` | `META_API_KEY` | yes |
- `'kimi'`'s env var is `MOONSHOT_API_KEY`, not `KIMI_API_KEY` — deliberate,
- matching Moonshot AI's own docs (the API/company behind Kimi) rather than
- this package's own provider name. `'meta'` (Meta's Muse models, e.g.
- `muse-spark-1.3`, through the Meta Model API) reads `META_API_KEY`,
- LiteLLM's name, rather than the generic `MODEL_API_KEY` in Meta's own
- examples. `openai`/`deepseek`/`kimi`/`glm`/`gemini`/`xai`/`meta` all reuse the same OpenAI-Chat-Completions-compatible request
- translation, just pointed at each provider's own base URL — see
- `core/model-calls/*.ts` for the provider-specific details (base URLs,
- `max_completion_tokens` vs `max_tokens`, and Gemini's own "still in beta"
- caveat on Google's compatibility layer).
- The console's model dropdown (New agent, and an agent's Model > Edit)
- lists each provider's models live from its API once its key is saved. To
- choose the list yourself, add a `models.yaml` next to `.env` mapping each
- provider to its models; a provider listed there offers exactly those, in
- that order, with no key needed, and edits show the next time the
- dropdown loads (`LOOPENGINE_MODELS_FILE` points at a different file):
- ```yaml
- anthropic:
- - claude-opus-5-5
- - claude-sonnet-5-5
- deepseek:
- - deepseek-v4-pro
- ```
- For anything else (a custom SDK client, a canned/simulated model for
- testing), export your own `createModelCall(): ModelCall` instead.
- ## Built on
- | Package | Responsibility |
- |---|---|
- | [`actauth`](https://www.npmjs.com/package/actauth) | Permission gating (allow/ask/deny/pending) with live and durable human-approval hooks |
- | `core/budget.ts` / `core/compaction.ts` | Context-window budget tracking and tail-preserving compaction (vendored in-repo, not an external dependency) |
- | `core/recovery.ts` | Retries prompt-too-long / truncated-output failures (vendored in-repo, not an external dependency) |
- | `core/durable-approvals.ts` | `TurnCheckpoint`/`CheckpointStore` (file/Redis) backing durable, resumable `ask` decisions — see `HUMAN_IN_THE_LOOP.md` |
- | `core/sessionknit.ts` | Durable session log with crash-interruption detection (vendored in-repo, not an external dependency) |
- | `core/skillgarden/` | `SKILL.md` discovery and lazy loading (vendored in-repo, not an external dependency) |
- | `core/toollane.ts` | Parallel/solo tool-call scheduling (vendored in-repo, not an external dependency) |
- | `core/mcpplug.ts` | Gateway tool sourcing (e.g. Composio) (vendored in-repo, not an external dependency) |
- Installing `loopengine` pulls in `actauth` as a regular dependency —
- install it directly only if you want to use it standalone. Everything
- else in this table ships inside `loopengine` itself.
- ## Deployment
- ```bash
- docker compose up --build
- ```
- Builds the HTTP adapter into a container and starts it alongside Redis.
- For production, push the image to any container platform with `REDIS_URL`
- and your model/tool API keys set as environment variables.
- ### Hosting behind a platform
- These settings are for running LoopEngine inside a hosting platform
- (one workspace per user, behind a router that has already authenticated
- them). All are off by default; a self-hosted install that doesn't set
- them behaves exactly as described above.
- | Setting | What it does |
- | --- | --- |
- | `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. |
- | `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. |
- | `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. |
- | `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. |
- `GET /healthz` answers `{"ok":true}` with no login, on every server,
- for health checks; it returns 503 once the server starts shutting down,
- and doesn't count as activity.
- `deploy/workspace/Dockerfile` is a runtime image for this: it serves a
- scaffolded project mounted at `/workspace` instead of baking agents in.
- ## License
- LoopEngine is open source under the [MIT License](LICENSE): use, change,
- self-host and redistribute it for anything, commercial use included.
- Third-party software included in LoopEngine keeps its own license: see
- [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.