Self-hosting

Letta agents can run entirely on infrastructure you control, in two shapes:

• Local runtime: The CLI and desktop app run agents directly on your machine—all agent state, including messages, memory, and provider connections, stays on-device. No server process is involved.
• Self-hosted App Server: Run the Letta App Server to host agents on a central, always-on server. The server connects your agents to messaging channels like Slack, Telegram, and WhatsApp, and exposes them to your own client applications through the Agent SDK.

Limitations of self-hosting: Self-hosted agents can only execute actions on the machine where they are stored—the local device, or the machine running the App Server (unless provided custom tools). They cannot be accessed through chat.letta.com and are not automatically backed up. Back up your state manually if you need to preserve or move it.

Setup

App Server

1. Install the Letta CLI

   Run the following command to install the Letta CLI via your terminal (requires Node.js version 22.19+):

   npm install -g @letta-ai/letta-code

2. Connect model providers

   Connect the model providers you want your agents to use, for example a locally running Ollama server:

   letta --backend local connect ollama

   You can also connect external API keys or other local inference servers:

   letta --backend local connect anthropic --api-key "$ANTHROPIC_API_KEY"
   letta --backend local connect lmstudio --base-url http://127.0.0.1:1234/v1

   See Models for the full list of supported providers.

3. Run the Letta server

   Start the App Server with the local backend:

   letta server --backend local --listen ws://127.0.0.1:4500

   The process prints the base URL and channel URLs at startup. See the App Server quickstart for authentication and configuration options.

4. Add channels (optional)

   To make your agents reachable through messaging platforms, start the server with one or more channels:

   letta server --channels slack

   See the channel-specific guides for setup instructions, e.g. Slack, Telegram, or Discord.

5. Connect via the SDK (optional)

   Connect to the running server from your application with the Letta Agent SDK’s remote backend:

   import { LettaAgentClient } from "@letta-ai/letta-agent-sdk";
   
   const client = new LettaAgentClient({
     backend: "remote",
     url: "http://127.0.0.1:4500",
   });

   See the Agent SDK section below for a full example.

CLI

1. Install the Letta CLI

   Run the following command to install the Letta CLI via your terminal (requires Node.js version 22.19+):

   npm install -g @letta-ai/letta-code

   To launch the Letta CLI, run:

   letta

   If you’re running the Letta CLI interactively for the first time, a Tutor agent will be auto-created for you.

2. Connect to LLM providers

   Use /connect to connect external API keys, coding plans, and local inference servers.

3. Navigate to your project

   cd your-project
   letta

Desktop App

1. Download and install the Letta app

   Download for macOS

   Available for MacOS, Windows and Linux

2. Open the Letta app and connect models

   Launch the app and select “Skip login” (this will store agents locally).

   Click “Connect model providers” in the bottom-left menu to add external API keys, coding plans, or locally running model endpoints.

Model inference is a separate choice. If you connect a remote model provider, prompts still go to that provider. To keep inference local too, connect a local provider such as Ollama, LM Studio, or llama.cpp. See Local models for both local and cloud-hosted setup options.

Agent SDK

The Letta Agent SDK supports two backends for self-hosted setups:

• Local backend (backend: "local"): The SDK starts App Server automatically as a subprocess on the current machine. Agent state and the execution environment stay on the machine running your code. Use this for development or single-machine deployments—no separate server process to manage.
• Remote backend (backend: "remote"): The SDK connects to an App Server you run as a separate service (letta server --listen). Agent state and the execution environment live on the App Server machine, so multiple clients can share the same agents and the server can run on different infrastructure than your application.

Local backend

import { LettaAgentClient } from "@letta-ai/letta-agent-sdk";

const client = new LettaAgentClient({ backend: "local" });

const agentId = await client.createAgent({
  persona: "You are Patch, a resident engineering teammate for this repository.",
});

await using session = client.createSession(agentId, {
  cwd: process.cwd(),
});

await session.send("Inspect this repository and write an onboarding memo.");

for await (const message of session.stream()) {
  if (message.type === "assistant") {
    console.log(message.content);
  }
}

Remote backend

Start an App Server on the machine that should hold agent state:

letta server --backend local --listen ws://127.0.0.1:4500

Then connect to it from your application:

import { LettaAgentClient } from "@letta-ai/letta-agent-sdk";

const client = new LettaAgentClient({
  backend: "remote",
  url: process.env.LETTA_APP_SERVER_URL ?? "http://127.0.0.1:4500",
  authToken: process.env.LETTA_APP_SERVER_TOKEN,
});

const agentId = await client.createAgent({
  persona: "You are Ops, a digital employee running in a shared workspace.",
});

await using session = client.createSession(agentId, {
  cwd: "/workspace/project",
});

await session.send("Prepare a morning handoff report for the workspace.");

for await (const message of session.stream()) {
  if (message.type === "assistant") {
    console.log(message.content);
  }
}

See the Agent SDK docs for full setup instructions and Deployment for production configurations.

Deployment

To make a self-hosted Letta server accessible to a client-side application, deploy App Server as a standalone service on infrastructure you control (a VM, container, or on-prem machine) and connect to it with the SDK’s remote backend.

1. Start App Server on the host machine

   Use the local backend so agent state stays on the server, and bind to a non-loopback address so other machines can reach it:

   letta server --backend local --listen ws://0.0.0.0:4500

   Installing the Letta CLI compiles native dependencies, so minimal Linux images and fresh VPSes need Python and a C++ toolchain first. On Debian/Ubuntu (including the node:22-slim Docker image), install them before npm install -g @letta-ai/letta-code:

   apt-get install -y python3 make g++

2. Configure authentication

   Non-loopback listeners should require WebSocket auth. Capability-token auth reads a token from a file and requires clients to send it as a bearer token:

   letta server \
     --backend local \
     --listen ws://0.0.0.0:4500 \
     --ws-auth capability-token \
     --ws-token-file /absolute/path/to/app-server-token

   You can also use signed bearer tokens with --ws-auth signed-bearer-token and --ws-shared-secret-file /absolute/path/to/secret.

3. Connect from your application

   Point the SDK at the server’s URL and pass the auth token:

   import { LettaAgentClient } from "@letta-ai/letta-agent-sdk";
   
   const client = new LettaAgentClient({
     backend: "remote",
     url: process.env.LETTA_APP_SERVER_URL, // e.g. "http://your-server:4500"
     authToken: process.env.LETTA_APP_SERVER_TOKEN,
   });

   Agent state and tool execution stay on the App Server machine; multiple clients can connect to the same server and share its agents.

App Server has filesystem and shell access on the machine where it runs. Never expose it directly to untrusted clients or embed its auth token in browser code—route client-side applications through your own backend, which holds the token and talks to App Server on their behalf.

For protocol details, lifecycle management, and lower-level integration options, see the App Server docs and Deployment.

Where local state is stored

By default, local state is stored in:

~/.letta/lc-local-backend

Each agent’s MemFS repository is stored under:

~/.letta/lc-local-backend/memfs/<agent-id>/memory

Use LETTA_LOCAL_BACKEND_DIR to isolate local state for a project or experiment:

export LETTA_LOCAL_BACKEND_DIR="$PWD/.letta-local"
letta --backend local --new-agent

Add .letta-local/ to .gitignore if you create it inside a repository.

Troubleshooting

My prompts are still going to a remote provider

Local setup stores agent state locally, but inference follows the model provider you selected. Switch to an Ollama, LM Studio, or llama.cpp model to run inference locally.

My local model does not appear in /model

Make sure the local inference server is running, then reconnect the provider:

letta --backend local connect ollama
letta --backend local connect lmstudio --base-url http://127.0.0.1:1234/v1

I want a clean local setup for testing

Set LETTA_LOCAL_BACKEND_DIR to a temporary directory before launching Letta Code:

export LETTA_LOCAL_BACKEND_DIR="$(mktemp -d)"
letta --backend local --new-agent