# Submilli documentation

> Submilli runs the programs your agent writes, under rules you set.

Fetch the relevant Markdown chapters below. For the entire book in one fetch, use
[the complete documentation](https://submilli.ai/docs/llms-full.txt).

## Chapters

- [Submilli documentation](https://submilli.ai/docs/index.md): The runtime for the code your agent writes — under rules you set.
- [Why Submilli](https://submilli.ai/docs/why.md): Why a program an agent writes needs rules about what it may do, and why isolation alone can't enforce them.
- [Install](https://submilli.ai/docs/install.md): Install the Submilli CLI and server, and the skill for your coding assistant, and check that each works.
- [Quickstart](https://submilli.ai/docs/quickstart.md): Write a Blueprint, the Package it governs, and an application that runs an agent's program on the server, and watch one rule refuse one call.
- [Blueprints](https://submilli.ai/docs/blueprints.md): The Blueprint in full: default deny, rules per caller, the variable the application binds, secrets, files, and models, and what no rule can grant.
- [Packages](https://submilli.ai/docs/packages.md): What a Package is in Submilli: a library built for agents, where every operation asks the Blueprint before it acts; how a program uses one, and the tools for building one.
- [The server](https://submilli.ai/docs/server.md): What submilli-server is and why it is built the way it is: an isolated WebAssembly instance per run instead of a microVM, and what it does with a program.
- [Your application](https://submilli.ai/docs/application.md): How the application or agent framework connects: it opens a session under a Blueprint, binds the variables, and hands the agent its tools; what the agent gets back.
- [Start a Blueprint](https://submilli.ai/docs/blueprints/start-a-blueprint.md): How to create a Blueprint with the CLI: start from nothing allowed, check the file, add a Package, grant operations, declare secrets and variables, test it, and register it on a server.
- [HTTP and credentials](https://submilli.ai/docs/blueprints/http-and-credentials.md): How to let programs call an HTTP endpoint that has no Package, give that endpoint a credential the program never sees, and prove it arrived.
- [Keep files and state](https://submilli.ai/docs/blueprints/keep-files-and-state.md): How to give the programs in one session a filesystem and a key-value store that last between them: choose the filesystem, grant its operations, run a program, cap the files, grant session state.
- [Allow Git](https://submilli.ai/docs/blueprints/allow-git.md): How to let a program clone a repository, find and change what it needs, and commit: set the identity and its token, grant the Git and file operations, and run it.
- [Allow model calls](https://submilli.ai/docs/blueprints/allow-model-calls.md): How to let a program call a model through submilli:llm: declare the provider's key, list the models, grant the capability, run a program, and register it on a server.
- [Add an MCP server](https://submilli.ai/docs/blueprints/add-an-mcp-server.md): How to make an MCP server importable as a Package: declare it, allow the tools the task needs, give it a credential or log in, register it on a server, and handle a server that can't be reached.
- [Start a project](https://submilli.ai/docs/packages/start-a-project.md): How to create a Package project with submilli build: scaffold it, fill in submilli.toml, check that it builds, add a second Package, and open it in your editor.
- [Export a function](https://submilli.ai/docs/packages/export-a-function.md): How to export a function a Blueprint can allow, filter, or deny: declare it with a @capability tag, enforce it with check, design the payload, call the service with a key the program never sees, and build it.
- [Document the Package](https://submilli.ai/docs/packages/document-the-package.md): How to document a Package for its two readers: the doc comments and docs/readme.md the model reads, with examples the build compiles, and the readme the person who installs and grants it reads.
- [Add a dependency](https://submilli.ai/docs/packages/add-a-dependency.md): How to make a Package import another, from the same project, your local store, or a GitHub repository, and what the dependency adds to what the Package requires and to the Blueprint.
- [Write tests](https://submilli.ai/docs/packages/write-tests.md): How to test a Package with submilli build test: a test file and its helpers, labels and failures, a live test run with the key or skipped, and what Package tests don't prove.
- [Publish a Package](https://submilli.ai/docs/packages/publish-a-package.md): How to publish a Package: install it into your local store, see what programs see, add it to a Blueprint and run a program under it, make it installable from your repository, and put it on a server.
- [Review a Package's security](https://submilli.ai/docs/packages/review-package-security.md): How to have a coding agent review a Package's authorization: run the review locally with Codex or Claude Code, read and keep its report, require it in CI, and make deployment wait for it.
- [Run the server](https://submilli.ai/docs/server/run-the-server.md): How to run submilli-server for an application: start it, configure its admin and user credentials, keep the server private, put its state on a persistent disk, turn on the secret store, and keep its audit trail.
- [Connect the CLI](https://submilli.ai/docs/server/connect-the-cli.md): How to point the submilli server commands at a server: its token from a file, its address, the first check, trusting its HTTPS certificate, keeping both in your shell, switching between servers by name, and which commands need the admin token.
- [Register a Blueprint](https://submilli.ai/docs/server/register-a-blueprint.md): How to put a Blueprint on a server: install its Packages and store its secrets first, register it, prove it with a program, and update or remove it later, knowing what registration checks and what remove costs.
- [Set limits](https://submilli.ai/docs/server/set-limits.md): How to set the server's limits: bound CPU work with fuel, keep a time limit as the backstop for your callers, size memory and the container, bound recursion, cap model spending and session state, and read what a program sees when it passes one.
- [Deploy on Linux](https://submilli.ai/docs/server/deploy-on-linux.md): How to run the server on a Linux machine of its own under systemd: the binaries for the system, a user and directories of its own, the config and token files under /etc/submilli, the unit, HTTPS, upgrades, and backups.
- [Deploy with Compose](https://submilli.ai/docs/server/deploy-with-compose.md): How to run the server as a container beside your application with the published compose file: a port only the host's loopback and your application's container can reach, state on a volume, the store key as a file, HTTPS, and upgrades by release.
- [Deploy on Kubernetes](https://submilli.ai/docs/server/deploy-on-kubernetes.md): How to install the server in your cluster with the Helm chart: generated tokens, a network policy that admits only your application, HTTPS, the encrypted secret store and its key, Blueprints registered through the API, memory sizing, storage, and upgrades.
- [Install private Packages on a server](https://submilli.ai/docs/server/install-private-packages.md): How to let a server install Packages from private GitHub repositories: create a token that can read them and give it to the server, under a process, Compose, or the Helm chart.
- [Mount a shared volume](https://submilli.ai/docs/server/mount-a-shared-volume.md): How to give programs a directory that outlives sessions and is shared across Blueprints: declare a named volume on the server, mount it in a Blueprint read-only or read-write, use it from a program, and know where its files live.
- [Connect a harness](https://submilli.ai/docs/tutorials/connect-a-harness.md): Set up the server and the research Blueprint the five harness tutorials share, prove it with one program, and know the three things a harness decides when it opens a session.
- [Craft a Blueprint](https://submilli.ai/docs/tutorials/craft-a-blueprint.md): Have your coding assistant write and test a Blueprint: a curated Package granted narrowly, a credential the program never sees, a tool server with only the tools the task needs; then put it on a server and prove it as two users. What a good result looks like, and what to ask for next.
- [Build a Package](https://submilli.ai/docs/tutorials/build-a-package.md): Have your coding assistant build a read-only Package over a real API: the Package, its readme, tests, a Blueprint, and a verifier's review, tested against the live service; then tests for a Package on a machine without the key. What a good result looks like.
- [Connect Mastra](https://submilli.ai/docs/tutorials/connect-mastra.md): Run the research agent on Mastra: its programs executed on the server as the signed-in user, then one real conversation watched end to end.
- [Connect deepagents](https://submilli.ai/docs/tutorials/connect-deepagents.md): Run the research agent on LangChain deepagents: one session held open for the run, the framework's own file tools denied so notes go through Submilli, then a real conversation.
- [Connect OpenAI Agents](https://submilli.ai/docs/tutorials/connect-openai-agents.md): Run the research agent on the OpenAI Agents SDK: the connection scope is the session, then a real conversation.
- [Connect Claude Agent SDK](https://submilli.ai/docs/tutorials/connect-claude-agent-sdk.md): Run the research agent on the Claude Agent SDK with every action going through Submilli: the SDK's own tools removed, only this server's tools allowed, then a real conversation.
- [Use the HTTP API](https://submilli.ai/docs/tutorials/use-the-http-api.md): Run the research agent on the Vercel AI SDK with no MCP client: the tools built by hand on the server's HTTP API, the Blueprint and variables fixed in your code, then a real conversation.
- [Diagnose a denial](https://submilli.ai/docs/tutorials/diagnose-a-denial.md): Take one PermissionDeniedError from message to cause to fix: read it, find the rule that decided, reproduce it under another binding, meet the denial that comes from a missing field, and decide whether the rule or the program is wrong.
- [Verify a Package in CI](https://submilli.ai/docs/tutorials/verify-a-package-in-ci.md): Build a GitHub Actions job that fails a pull request when a Package's tests fail, with the tests that call the service run from the repository's secrets and skipped where there are none, and an agent's security review beside them.
- [Manage Blueprints in Git](https://submilli.ai/docs/tutorials/manage-blueprints-in-git.md): Keep the Blueprints in a repository: on every pull request, lint them and test each one as two sessions, one it must allow and one it must refuse; on every merge to main or every release, register them on the server, with the Packages pinned in the same commit and a rollback that is a revert.
- [Add the GitHub MCP server](https://submilli.ai/docs/tutorials/add-the-github-mcp-server.md): Give an agent GitHub through GitHub's hosted MCP server: declare it in a Blueprint, register an OAuth application and log in once, allow a tool and call it, run it on a server, and know where a per-user token belongs instead.
- [Blueprint file](https://submilli.ai/docs/reference/blueprint-file.md): Every top-level key and field of a Blueprint file: types, defaults, allowed values, where variables and secrets may be referenced, and the errors that refuse a file at lint and at registration.
- [Filter language](https://submilli.ai/docs/reference/filter-language.md): The language of a permission rule's filter: comparisons, operators, glob and regex patterns, combining conditions, literals, field names, variables, how a filter is evaluated, and the errors a malformed one gives.
- [CLI](https://submilli.ai/docs/reference/cli.md): The submilli command tree: what each command does and where it runs, exit codes, environment variables, the state directory, Package installation and its errors, the GitHub token, and the help text of every command.
- [Language](https://submilli.ai/docs/reference/language.md): The TypeScript Submilli programs are written in: the shape of a program, the stricter checks Submilli makes and why, and how to look declarations up.
- [Built-ins](https://submilli.ai/docs/reference/built-ins.md): The globals every Submilli program has without an import: types, error classes, namespaces, and global functions, with each one's members.
- [Standard library](https://submilli.ai/docs/reference/standard-library.md): Every submilli: module: what gates it, who may import it, the rules its functions share, Git's operations and limits, and each module's functions and types.
- [Curated Packages](https://submilli.ai/docs/reference/curated-packages.md): The Packages Submilli maintains for common services: each Package, what it is for, the secret it reads, the hosts it reaches, its readme, and the commands that install it and grant one of its capabilities.
- [Errors and limits](https://submilli.ai/docs/reference/errors-and-limits.md): Every limit on a program's run with its default, scope, and what a program sees when it passes it; the fixed limits inside the standard library; and the catalog of errors a program and its caller can get.
- [Server settings](https://submilli.ai/docs/reference/server-settings.md): Every submilli-server setting with its config-file key, flag, and SUBMILLI_* variable, the precedence between them, and the tokens, directories, secret store, volumes, outbound network block, limits, telemetry, health, logs, audit trail, and shutdown they control.
- [Audit trail](https://submilli.ai/docs/reference/audit-trail.md): Every record submilli-server writes to its audit trail: the fields all records share, and the decision, execution, session, admin, auth, and server records with their events and fields.
- [Package manifest](https://submilli.ai/docs/reference/package-manifest.md): A Package project: its layout, every key of submilli.toml and the dependency forms, submilli.lock, the doc-comment tags the build reads, the derived capabilities.yaml, docs/readme.md, and the test API of submilli build test.
- [Security review](https://submilli.ai/docs/reference/security-review.md): Agent selection, authentication, review scope, report fields, limits, and exit codes for Package security reviews.
- [MCP servers](https://submilli.ai/docs/reference/mcp-servers.md): The Blueprint's mcp block, discovery, how tools become functions, output schemas, results, failure messages, OAuth, limits, and the local and server commands.
- [HTTP API](https://submilli.ai/docs/reference/http-api.md): The endpoints a harness calls to run programs over HTTP: sessions and their execute, rebind, last-run, and delete; the execute result; the prompt, Package, and built-in descriptions; and one-off runs.
- [Permissions](https://submilli.ai/docs/reference/permissions.md): How a call is decided, callers, actions, the refusals no rule changes, the capabilities and their fields, the errors when a Blueprint is read, and the denials at run time.
- [Why agents execute code — transcript](https://submilli.ai/docs/videos/code-execution-introduction.md): The complete narration of the code-execution introduction.
- [Videos](https://submilli.ai/docs/videos.md): Videos about code execution and Submilli, with captions and transcripts.