> For the complete documentation index, see [llms.txt](https://weavescope.gitbook.io/beam_weaver/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://weavescope.gitbook.io/beam_weaver/operations/going_to_production.md).

# Going To Production

BeamWeaver does not provide a hosted deployment platform, `langgraph.json`, or managed agent server. Production is your Elixir application: OTP supervision, releases, config, database migrations, schedulers, telemetry, and whatever HTTP or job boundary invokes your agents and graphs.

Use this page as a checklist and routing guide. The implementation details live in the linked topic pages so this guide stays small and avoids duplicating memory, sandbox, persistence, guardrail, and streaming docs.

## Production Contract

Every production invocation should separate conversation identity from trusted run context:

```elixir
config = %{"configurable" => %{"thread_id" => "thread-123"}}

context = %{
  user_id: "user-123",
  org_id: "org-456",
  permissions: ["support:read"],
  request_id: "req-789"
}

MyApp.SupportAgent.invoke(input, config: config, context: context)
```

`thread_id` scopes checkpointed conversation state. Reuse it for follow-up turns in the same conversation and generate a new one for a separate thread.

`context` carries per-run facts supplied by your application boundary: user ID, tenant, permissions, feature flags, locale, request IDs, and credential handles. Do not let the model choose ownership values. Derive them from authenticated request/session state and pass them through `context:` or `server_info:`.

## Identity And Tenancy

BeamWeaver has no built-in user system. Your application should authenticate the request, authorize access, and pass only trusted identity into BeamWeaver.

| Scope        | Use                                                                                     |
| ------------ | --------------------------------------------------------------------------------------- |
| Thread       | Conversation history, checkpoints, scratch files, and resumable interrupts.             |
| User         | Private memory, private files, and per-user tools or credentials.                       |
| Agent        | Shared configuration for one agent module or assistant-like deployment.                 |
| Organization | Shared policies, compliance rules, and organization knowledge. Prefer read-only access. |

For memory and filesystem namespaces, derive scope from trusted runtime context: `user_id`, `org_id`, agent name, or assistant ID from your own service layer.

See [Runtime](/beam_weaver/core-components/runtime.md), [Persistence](/beam_weaver/capabilities/persistence.md), [Memory](/beam_weaver/capabilities/memory.md), and [Filesystem](/beam_weaver/capabilities/filesystem.md).

## Deployment Shape

Run BeamWeaver like any other OTP application:

* start agents, queues, stores, and telemetry subscribers under supervision;
* use releases and runtime config for provider keys and endpoint URLs;
* run Ecto migrations for checkpoint, memory, and queue tables;
* use Oban, Quantum, Kubernetes CronJobs, or another scheduler for background consolidation and maintenance work;
* expose your own HTTP, Phoenix Channel, LiveView, or job interface around `invoke/3`, `stream_events/3`, and resume APIs.

Do not rely on LangGraph Platform conventions such as `langgraph.json`, hosted thread APIs, or automatic deployment infrastructure. Integrate those as external services only where your application explicitly chooses to.

## Checklist

| Concern            | Production decision                                                                        | BeamWeaver docs                                                                                                                                                                      |
| ------------------ | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Conversation state | Use a checkpointer and stable `thread_id`.                                                 | [Persistence](/beam_weaver/capabilities/persistence.md), [Short-Term Memory](/beam_weaver/core-components/short_term_memory.md)                                                      |
| Durable execution  | Pick durable adapters and node boundaries; set timeouts and recursion limits.              | [Durable Execution](/beam_weaver/capabilities/durable_execution.md), [Fault Tolerance](/beam_weaver/capabilities/fault_tolerance.md)                                                 |
| Human review       | Use checkpointed HITL for sensitive tools and resumable approvals.                         | [Human-In-The-Loop](/beam_weaver/core-components/human_in_the_loop.md)                                                                                                               |
| Long-term memory   | Scope by user, agent, or org; make shared policy memory read-only.                         | [Memory](/beam_weaver/capabilities/memory.md), [Long-Term Memory](/beam_weaver/core-components/long_term_memory.md)                                                                  |
| Files              | Pick local, store-backed, composite, or sandbox-backed filesystems.                        | [Filesystem](/beam_weaver/capabilities/filesystem.md), [Permissions](/beam_weaver/capabilities/permissions.md)                                                                       |
| Code execution     | Use sandbox adapters for untrusted command execution; keep secrets outside sandboxes.      | [Sandboxes](/beam_weaver/capabilities/sandboxes.md)                                                                                                                                  |
| Skills             | Load only the skill sources each agent or subagent should see.                             | [Skills](/beam_weaver/capabilities/skills.md), [Subagents](/beam_weaver/capabilities/subagents.md)                                                                                   |
| Model usage        | Set model timeouts, retry/fallback policy, and provider limits.                            | [Models](/beam_weaver/core-components/models.md), [Fault Tolerance](/beam_weaver/capabilities/fault_tolerance.md), [Rate Limiting](/beam_weaver/operations/rate_limiting.md)         |
| Tool usage         | Restrict tools, add HITL where needed, and limit or retry external API tools deliberately. | [Tools](/beam_weaver/core-components/tools.md), [Guardrails](/beam_weaver/core-components/guardrails.md), [Prebuilt Middleware](/beam_weaver/core-components/prebuilt_middleware.md) |
| Sensitive data     | Redact tracing data and avoid putting credentials in model-visible state.                  | [Tracing](/beam_weaver/operations/tracing.md), [Guardrails](/beam_weaver/core-components/guardrails.md), [Sandboxes](/beam_weaver/capabilities/sandboxes.md)                         |
| Streaming UI       | Consume one event stream and route typed envelopes to your UI or transport.                | [Event Streaming](/beam_weaver/capabilities/event_streaming.md)                                                                                                                      |
| Observability      | Attach telemetry, export traces intentionally, and monitor exporter queues.                | [Tracing](/beam_weaver/operations/tracing.md)                                                                                                                                        |
| Tests              | Run integration tests for the adapters and workflows you deploy.                           | [Replay](/beam_weaver/operations/replay.md)                                                                                                                                          |

## Invocation Patterns

For request/response APIs, call `invoke/3` from a supervised request handler or job process:

```elixir
case MyApp.SupportAgent.invoke(input, config: config, context: context) do
  {:ok, state} -> {:ok, state}
  {:interrupted, interrupt} -> {:needs_review, interrupt}
  {:error, error} -> {:error, error}
end
```

For live UIs, call `stream_events/3` and forward typed envelopes through your transport:

```elixir
{:ok, events} =
  MyApp.SupportAgent.stream_events(input,
    config: config,
    context: context,
    live: true
  )

Enum.each(events, fn envelope ->
  MyAppWeb.AgentChannel.push_event(socket, envelope)
end)
```

Consume a live stream once. If multiple UI components need the same updates, fan out from one process through PubSub, channels, LiveView assigns, or your own projection state.

## Secrets

Keep provider API keys, OAuth tokens, database credentials, and customer secrets outside model-visible state. Prefer host-side tools that perform authenticated work without exposing the credential to the model or sandbox.

For sandboxed code execution:

* do not upload secrets as files;
* do not inject broad environment variables into the sandbox;
* restrict network access where possible;
* treat sandbox outputs as untrusted input;
* implement credential proxying or host-side tools when sandbox code must call authenticated APIs.

See [Sandboxes](/beam_weaver/capabilities/sandboxes.md), [Tools](/beam_weaver/core-components/tools.md), and [Guardrails](/beam_weaver/core-components/guardrails.md).

## Background Work

Use normal Elixir scheduling and jobs for production maintenance:

* memory consolidation across recent conversations;
* trace export queue flushing and dead-letter handling;
* checkpoint pruning and retention;
* sandbox cleanup by thread or agent scope;
* index refresh and retrieval ingestion;
* eval or conformance jobs against production-like adapters.

These are application jobs, not BeamWeaver-specific hosted cron features. Use Oban or your existing scheduler and invoke BeamWeaver agents, graphs, memory stores, and checkpoint APIs from those jobs.

## Related Guides

* [Runtime](/beam_weaver/core-components/runtime.md)
* [Persistence](/beam_weaver/capabilities/persistence.md)
* [Memory](/beam_weaver/capabilities/memory.md)
* [Filesystem](/beam_weaver/capabilities/filesystem.md)
* [Permissions](/beam_weaver/capabilities/permissions.md)
* [Sandboxes](/beam_weaver/capabilities/sandboxes.md)
* [Human-In-The-Loop](/beam_weaver/core-components/human_in_the_loop.md)
* [Fault Tolerance](/beam_weaver/capabilities/fault_tolerance.md)
* [Guardrails](/beam_weaver/core-components/guardrails.md)
* [Event Streaming](/beam_weaver/capabilities/event_streaming.md)
* [Tracing](/beam_weaver/operations/tracing.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://weavescope.gitbook.io/beam_weaver/operations/going_to_production.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.