---
title: Local setup | Letta Docs
description: Configuring the local stateful agent backend
---

Local mode runs an embedded Letta-compatible backend inside Letta Code. Agents, conversations, memory, and provider connections are stored on your machine.

Local mode controls where Letta Code stores agent state. It does not make model inference local by itself. If you connect a remote provider like OpenAI, Anthropic, Gemini, OpenRouter, Bedrock, or ChatGPT/Codex, prompts still go to that provider. For a fully local loop, connect a local inference provider like Ollama, LM Studio, or llama.cpp.

## Connect model providers

Use `/connect` inside the interactive session to add providers to the local backend:

```
> /connect
```

You can also connect providers from the shell:

```
letta --backend local connect anthropic --api-key "$ANTHROPIC_API_KEY"
letta --backend local connect ollama
letta --backend local connect lmstudio
letta --backend local connect llama-cpp
letta --backend local connect chatgpt
```

These are common examples, not the full provider list. See [Providers](/letta-code/providers/index.md) for the broader provider reference.

For local OpenAI-compatible servers, pass a base URL:

```
letta --backend local connect lmstudio --base-url http://127.0.0.1:1234/v1
letta --backend local connect llama-cpp --base-url http://localhost:8080/v1
```

For slow local inference servers, configure a provider-level timeout:

```
letta --backend local connect lmstudio --base-url http://127.0.0.1:1234/v1 --timeout 600s
```

Timeouts are stored per local provider in milliseconds. Pass `--no-timeout` or `--timeout false` to disable the provider timeout.

## Where local state is stored

By default, local backend state is stored in:

```
~/.letta/lc-local-backend
```

Local agent memory is stored as a git repository 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.

## Run local mode headlessly

Headless mode also supports the local backend:

```
letta --backend local -p "summarize this repository"
```

Use this for local scripts or one-off automation that should use local agent state.

## Troubleshooting

### My prompts are still going to a remote provider

Local mode stores state locally, but inference follows the model provider you selected. Switch to an Ollama, LM Studio, or llama.cpp model for local inference.

### 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 backend 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
```