# `Beamlet`
[🔗](https://github.com/aaronrussell/beamlet/blob/v0.1.0/lib/beamlet.ex#L1)

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](getting-started.md) 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 {: .warning}
>
> 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.

# `option`

```elixir
@type option() :: {:only, :system}
```

Options accepted by `start_link/1`.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `start_link`

```elixir
@spec start_link([option()]) :: Supervisor.on_start()
```

Starts a beamlet, supervising everything it needs to run.

## Options

* `:only` - `:system` starts just the policies and the beamlet's
  own database, with nothing an agent reaches.

---

*Consult [api-reference.md](api-reference.md) for complete listing*