agents

mcp
Security Audit
Pass
Health Pass
  • License — License: Apache-2.0
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Community trust — 19 GitHub stars
Code Pass
  • Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

SUMMARY

The open-source runtime for AI agents. Define agents as files; run them on durable infrastructure you host.

README.md

Nylorun

The open-source runtime for AI agents.

Define agents as files. Run them on durable infrastructure you host.

CI
npm
License
Discussions

Docs ·
Quickstart ·
Self-host ·
Examples ·
API reference

[!WARNING]
Beta. APIs and on-disk formats change before 1.0. Upgrade every Nylorun
package together and read Compatibility
before you skip a release.

Clients (CLI, Agents SDK, Admin SDK, Studio, HTTP) call the Runtime API and Management API. Inside the Runtime: sessions, a store on Postgres, artifacts on RustFS, sandboxes (virtual, or pods on Kubernetes), durable execution on Restate and durable streams on S2. Calls to model providers, MCP servers, HTTP tools and the web leave through the gateway, which holds the keys.

Why Nylorun

  • Agents are files. An agent is a folder of Markdown and JSON (instructions, tools,
    MCP servers, skills, triggers) or a TypeScript definition. Review it in a PR, then apply it.
  • Durable sessions. Turns run on durable execution (Restate) and durable streams (S2),
    with sessions stored in Postgres.
  • Your infrastructure, your keys. One Docker Compose stack on a laptop or a VM, or a Helm
    chart on Kubernetes. Model and tool keys stay in the gateway. Your identity provider signs
    people in.
  • Open protocols. MCP for tools, AG-UI and A2A for apps and other agents, and an open
    Harness API to run turns in any language.

Quickstart

You need Node.js 24 and Docker Compose v2 (on Windows, use WSL2). npx nylorun doctor checks both.

# 1. Start a Runtime and Studio on this machine (the first run pulls about 3 GB of images)
npx nylorun up

# 2. Pick a model provider; the key is stored in the Tenant's vault
npx nylorun tenant models set

# 3. Write an agent, check it offline, save it
npx nylorun init agents/hello
npx nylorun check agents/hello
npx nylorun apply agents/hello --agent

# 4. Talk to it
npx nylorun chat hello

npx nylorun studio signs your browser in to Studio, where you can chat and inspect sessions.
npx nylorun down stops the stack. Your data stays in Docker volumes.

Define an agent

An agent folder needs one file, AGENT.md:

---
name: hello
description: "Answers questions about orders."
---
You are hello. Answer briefly, and ask for the order id when you need it.

Tools, MCP servers, skills and triggers go next to it. npx nylorun init agents/hello --example
writes one of each. The same agent in TypeScript, with an HTTP tool, using the
Agents SDK:

import { Agent, http } from "@nylorun/agents";
import { z } from "zod";

const lookupOrder = http({
  name: "lookup_order",
  description: "Look up an order by id.",
  input: z.object({ orderId: z.string() }),
  url: "https://orders.example.com/lookup",
});

export const hello = Agent({ id: "hello" })
  .instructions("Answer briefly. Use lookup_order for orders.")
  .tools(lookupOrder);

Next: Tools ·
MCP ·
Flow agents ·
Serve your users

Self-host

Everything in this repository runs without a Nylorun account.

You want to Start here
Run on one machine or VM with Docker Compose Deploy on a VM · Compose reference
Sign people in with your own identity provider Identity and access · Keycloak example
Run on Kubernetes with pod sandboxes Kubernetes guide · Helm chart
Collect metrics, traces and audit events Observability
Upgrade between beta releases Compatibility · Migration notes

Documentation

Learn and build at docs.nylorun.com:
Concepts ·
Build ·
Run ·
Deploy ·
Runtime API ·
Troubleshooting.

Operator and contributor references live in docs/ in this repository.

Using a coding agent? Point it at llms.txt. Every docs page
is also available as Markdown: add .md to its URL.

Examples

Example Shows
examples/agents/triage An agent written as a folder of Markdown and JSON
examples/agents/repo-brief One flow agent with map, parallel, loop and an HTTP tool
examples/self-host Keycloak and oauth2-proxy in front of a Tenant, with an end-to-end smoke
examples/harness-minimal Your own harness on the Harness API
examples/observability OpenTelemetry metrics and traces from the Runtime

All examples

Contributing

This is a TypeScript monorepo (Runtime, Studio, CLI, SDKs) with a Go sandbox service.
docs/reference/packages.md maps each folder to what it publishes.
You need Node 24 and npm 11:

git clone https://github.com/nylorun/agents.git && cd agents
npm run setup   # install and build the packages
npm run dev     # run the examples' Tenant from source, rebuilding as you edit

Read CONTRIBUTING.md for checks and pull requests.

Community

License

Apache-2.0

Reviews (0)

No results found