Beamlet (Beamlet v0.1.0)

Beamlet is an Elixir server that your AI agent builds from the inside.

An agent connects over MCP and works on your beamlet, a running Elixir application. It defines modules, runs code, and builds APIs and live dashboards on it. Most people run Beamlet as a standalone server, and Getting started is the place to start.

This module is what starts a beamlet, in the standalone server or inside your own app.

Running a beamlet in your app

Your app is inside the boundary

Agent code runs in the same VM as your application. Policies are guardrails, not containment. Anyone holding a token can reach whatever your application can: its modules, its processes and its data. Embed a beamlet only where you would trust every token holder with the whole app.

Add Beamlet to your supervision tree, before your endpoint, so the beamlet is ready by the first request:

children = [
  Beamlet,
  MyAppWeb.Endpoint
]

Give it a data dir and name your endpoint:

config :beamlet,
  data_dir: "/var/lib/my_app/beamlet",
  web: [endpoint: MyAppWeb.Endpoint]

Then forward to Beamlet.Router as the last route in your router:

forward "/", Beamlet.Router

Your endpoint needs a few more things, two LiveView sockets among them. Beamlet.Router lists them all, and Beamlet.Config covers the other config keys.

The boot fails with a message saying what to fix when the data dir is missing, a policy is invalid, git is not installed or no endpoint is named. Only one beamlet runs per VM.

Summary

Types

option()

Options accepted by start_link/1.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

start_link(opts)

Starts a beamlet, supervising everything it needs to run.