Skip to main content
Glama
README.md
![Submilli](docs-site/public/favicon.svg)

# Submilli

A code-execution runtime with a [semantic permission model](https://submilli.ai/docs/blueprints/#semantic-permission-model), for business agents that
generate code. For example, a support agent could issue a refund of up to $500 for platinum clients and up to $100 for all other customer tiers.

The developer could try to add that rule as a safeguard to the prompt, but due to the nature of models, it will likely only work *some* of the time. By using the Submilli Runtime to execute the agent generated code, the owner of that agentic workflow can define these guardrails in advance, and they will be enforced by the runtime, outside the model's control.

[Docs](https://submilli.ai/docs/) ·
[Set up with your agent](https://submilli.ai/docs/quickstart/#agent-setup) ·
[Quickstart](https://submilli.ai/docs/quickstart) ·
[Roadmap](ROADMAP.md) ·
[Website](https://submilli.ai)

[![CI](https://github.com/submilli/submilli-runtime/actions/workflows/ci.yml/badge.svg)](https://github.com/submilli/submilli-runtime/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/submilli/submilli-runtime?include_prereleases&label=release)](https://github.com/submilli/submilli-runtime/releases)
[![Container image](https://img.shields.io/badge/container-ghcr.io-blue)](https://github.com/submilli/submilli-runtime/pkgs/container/submilli-runtime)
[![Helm chart](https://img.shields.io/badge/dynamic/yaml?url=https%3A%2F%2Fraw.githubusercontent.com%2Fsubmilli%2Fsubmilli-runtime%2Fmain%2Fcharts%2Fsubmilli%2FChart.yaml&query=%24.version&label=helm%20chart&logo=helm&color=0F1689)](https://github.com/submilli/submilli-runtime/pkgs/container/charts%2Fsubmilli)
[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
[![Docs](https://img.shields.io/badge/docs-submilli.ai-informational)](https://submilli.ai/docs/)

## Demo

https://github.com/user-attachments/assets/8dff6714-b8af-41bd-9d18-b57e7796ae02

A support agent creates a replacement with $18 shipping. A $42 replacement is blocked until the developer raises the Blueprint limit from $25 to $50.

---

Code mode and programmatic tool calling let agents write code instead of calling
tools one by one. You can read more about it [here](https://submilli.ai/docs/why/#video-code-execution-introduction).

Submilli is the runtime for those agents. The agent submits TypeScript code, and
Submilli executes it in WebAssembly for isolation. Programs reach the outside
world through Packages, not `node:http` or `node:fs`.

Before a program calls the outside world, Submilli checks the Blueprint's
permissions. Package authors define operations and fields. You set rules such as
"Allow a refund up to $500, only for customer 123". Submilli Packages are built
for agents with [semantic permissions](https://submilli.ai/docs/blueprints/#semantic-permission-model).
We don't use npm packages, and while we support MCP servers, Packages are the
native way to work with Submilli.

## What a rule looks like

Blueprints are one of Submilli's main building blocks, together with
Packages. A Blueprint defines the environment the agent's code runs in. You
write it in YAML.

The permissions block in a Blueprint defines what the code can do, and you
fill it by adding capabilities. Package authors publish the capabilities the package supports, and you
grant them (or some of them) to the agent by declaring them in the Blueprint. 

You may also define variables for a Blueprint. Now you control not only the
agent's capabilities, but also the context it can use them in. In the example
below, we allow the code to access billing operations, but only for a specific customer (that is bound to the runtime by the host application), and to issue credits of up to $500. If the agent tries a different customer, or a higher amount, the operation fails.

```yaml
variables:
  customerId:
    required: true

permissions:
  main:
  - capability: pied-piper.example/charges.list
    filter: customerId == ${vars.customerId}
    action: allow
  - capability: pied-piper.example/credits.apply
    filter: customerId == ${vars.customerId} and amount <= 50000  # cents
    action: allow
```

## Install

macOS and Linux:

```sh
curl -fsSL https://submilli.ai/install.sh | sh
```

Windows (PowerShell):

```powershell
irm https://submilli.ai/install.ps1 | iex
```

This installs the `submilli` CLI and `submilli-server`. To run the server in
production, use [Docker Compose](https://submilli.ai/docs/server/deploy-with-compose),
the [Helm chart](https://submilli.ai/docs/server/deploy-on-kubernetes), or
[systemd](https://submilli.ai/docs/server/deploy-on-linux).

For repeatable installations, [pin and verify a release](https://submilli.ai/docs/install/#pin-and-verify-a-release)
instead of resolving the latest release each time.

## Connect your agent

Submilli keeps your harness. Your agent gets tools to run programs, over MCP
or HTTP. There are tutorials for
[LangChain Deep Agents](https://submilli.ai/docs/tutorials/connect-deepagents),
[Mastra](https://submilli.ai/docs/tutorials/connect-mastra),
the [OpenAI Agents SDK](https://submilli.ai/docs/tutorials/connect-openai-agents),
the [Claude Agent SDK](https://submilli.ai/docs/tutorials/connect-claude-agent-sdk),
and [plain HTTP](https://submilli.ai/docs/tutorials/use-the-http-api).

## Features

- [Blueprints](https://submilli.ai/docs/blueprints) with rules on an operation's
  arguments, bound per session, and everything denied by default.
- [Packages](https://submilli.ai/docs/packages) that wrap your APIs and hold the
  credentials, so generated code never sees a secret. Curated Packages for
  GitHub, Slack, Gmail, Google Drive and Calendar, Linear, Notion, Sentry, and
  web search are [included](packages/README.md).
- [Limits](https://submilli.ai/docs/server/set-limits) on memory, time,
  stack depth, model tokens and more. A failing run ends alone, and the rest of the
  server keeps serving.
- [Durable execution](https://submilli.ai/docs/reference/run-recovery): agent runs survive server crashes and restarts, and finished steps are not repeated. Off by default.
- An [audit trail](https://submilli.ai/docs/reference/audit-trail) of every
  refusal, run, session, and admin change.
- MCP servers as Packages, with rules on their tools.
- Checks for Package authors: `--deny-warnings` in CI and an
  [agent security review](https://submilli.ai/docs/packages/review-package-security).
- HTTPS, API tokens with admin and user roles, and an encrypted secret store.

Missing an integration? [Request a curated Package](https://github.com/submilli/submilli-runtime/issues/new?template=curated-package.yml).

## Status

Submilli is young and moving quickly. Releases are on the
[releases page](https://github.com/submilli/submilli-runtime/releases).
Breaking changes are called out in the release notes, and a Blueprint that
uses a removed feature fails to load with a message that says what to write
instead.

Our short term roadmap is published [here](https://github.com/submilli/submilli-runtime/blob/main/ROADMAP.md). If you have ideas, suggestions, requests or questions, we'd love to chat.

Submilli is open source. If you’re thinking of using it, we’d love to talk to you! Contact us at [hello@submilli.ai](mailto:hello@submilli.ai).

## Repository

| Path | What it holds |
| --- | --- |
| `crates/` | The compiler, runtime, CLI, and server, in Rust |
| `packages/` | The curated Packages |
| `charts/` | The Helm chart |
| `docs/`, `docs-site/` | The book at [submilli.ai/docs](https://submilli.ai/docs/) |
| `skills/` | The skill that teaches coding assistants to write Blueprints and Packages |
| `examples/` | The quickstart and harness examples |

## Contributing

Read [CONTRIBUTING.md](CONTRIBUTING.md) first. Contributions need the
[CLA](CLA.md). Report security issues as described in
[SECURITY.md](SECURITY.md), not in public issues.

## License

[Apache License 2.0](LICENSE).