Letta

https://docs.letta.com/
Admin
Letta is a platform for building and deploying stateful AI agents, offering an Agent Development...
Tokens:1,179,358
Snippets:7,427
Trust Score:9.1
Update:1 day ago
Show doc for...
Tokens:
Raw
### Install Letta CLI and log in

Source: https://docs.letta.com/platform/computers/byom

Install the Letta CLI globally via npm and start the CLI.

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

--------------------------------

### Example output (local)

Source: https://docs.letta.com/agent-sdk/quickstart

Example output from the local quickstart, showing agent ID, conversation ID, and an engineering onboarding memo with architecture, workflows, and gotchas.

```text
Agent ID: agent-abc123
Conversation ID: conv-abc123
## Engineering onboarding memo
- Architecture: ...
- Workflows: ...
- Gotchas: ...

```

--------------------------------

### Example output (managed cloud)

Source: https://docs.letta.com/agent-sdk/quickstart

Example output from the managed cloud quickstart, showing agent ID, conversation ID, and a brief with risks and follow-ups.

```text
Agent ID: agent-abc123
Conversation ID: conv-abc123
## SDK release brief
- Current state: ...
- Risks: ...
- Follow-ups: ...

```

--------------------------------

### Example output from quickstart

Source: https://docs.letta.com/agent-sdk/quickstart

Shows the expected output: agent ID, conversation ID, and a morning handoff report with recent changes, blockers, and recommended actions.

```text
Agent ID: agent-abc123
Conversation ID: conv-abc123
## Morning handoff
- Recent changes: ...
- Blockers: ...
- Recommended actions: ...
```

--------------------------------

### Start server with channel runtime auto-install

Source: https://docs.letta.com/self-hosting/channels

Starts the Letta server with the local backend and Telegram channel, automatically installing channel runtimes via the --install-channel-runtimes flag. Requires pre-written config files in ~/.letta/channels/<channel>/.

```bash
letta server --backend local --channels telegram --install-channel-runtimes
```

--------------------------------

### Example .env.local contents

Source: https://docs.letta.com/agent-sdk/demo-apps/react-chat

Shows the environment variables required by the server routes after running the setup script.

```bash
LETTA_API_KEY=your-key-here
LETTA_CHAT_AGENT_ID=agent-...
LETTA_AUTO_APPROVE_TOOLS=web_search,fetch_webpage
```

--------------------------------

### Install channel runtime dependencies with letta channels install

Source: https://docs.letta.com/self-hosting/channels/custom

Install runtime packages declared by your plugin before starting the server. Use `letta channels install <channel-name>` to install dependencies for a specific channel.

```bash
letta channels install matrix-community
```

--------------------------------

### Install channel runtimes on server start with --install-channel-runtimes

Source: https://docs.letta.com/self-hosting/channels/custom

For headless deployments, install runtimes as the server starts using the `--install-channel-runtimes` flag. Runtime dependencies should resolve from the channel runtime directory, not from parent project or development `node_modules` folders.

```bash
letta server --backend local --channels matrix-community --install-channel-runtimes
```

--------------------------------

### setup_script field example

Source: https://docs.letta.com/v1-sdk/evals/concepts/suites

Specifies the path to a Python script with a setup function to run before evaluation. Format is script.py:function_name.

```yaml
setup_script: setup.py:prepare_environment # script.py:function_name
```

--------------------------------

### SSH in and install Letta on droplet

Source: https://docs.letta.com/platform/computers/byom

SSH into the droplet, install Node.js 20, build tools, and Letta Code, then start the server.

```bash
ssh root@<droplet-ip>

# Install Node.js 20 + build tools
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt-get install -y nodejs python3 make g++

# Install Letta Code
npm install -g @letta-ai/letta-code

# Start the server
letta server --env-name "cloud"
```

--------------------------------

### Run quickstart.ts with tsx

Source: https://docs.letta.com/agent-sdk/quickstart

Runs the TypeScript quickstart file using npx tsx. Used for both managed cloud and local examples.

```bash
npx tsx quickstart.ts

```

--------------------------------

### Start a local Letta App Server

Source: https://docs.letta.com/agent-sdk/demo-apps/mobile

Install the Letta code package, generate a WebSocket token, and start a Letta App Server with WebSocket authentication. Enter ws://<your-machine>:4610 and the token in the app. Use TLS or a private network when the server is available beyond your local network.

```bash
npm install -g @letta-ai/letta-code
openssl rand -hex 24 > /tmp/ws-token
letta server --listen ws://0.0.0.0:4610 \
  --ws-auth capability-token \
  --ws-token-file /tmp/ws-token
```

--------------------------------

### Install recommended mods

Source: https://docs.letta.com/quickstart

Commands to install recommended mods: image-understanding, memfs-search, and plan-mode. Run /reload after installing to activate a mod.

```bash
letta install npm:@letta-ai/image-understanding   # vision for text-only models
letta install npm:@letta-ai/memfs-search          # keyword + optional semantic memory search
letta install npm:@letta-ai/plan-mode             # plan-before-execute workflow
```

--------------------------------

### 200 response example for get environment connection

Source: https://docs.letta.com/api/resources/environments/methods/retrieve

Example of a successful response from the Get Environment Connection endpoint. The response includes connection metadata, device information, and configuration details.

```json
{
  "id": "id",
  "connectedAt": 0,
  "connectionId": "connectionId",
  "connectionName": "connectionName",
  "deviceId": "deviceId",
  "firstSeenAt": 0,
  "lastHeartbeat": 0,
  "lastSeenAt": 0,
  "organizationId": "organizationId",
  "podId": "podId",
  "apiKeyOwner": "apiKeyOwner",
  "currentMode": "default",
  "metadata": {
    "gitBranch": "gitBranch",
    "lettaCodeVersion": "lettaCodeVersion",
    "nodeVersion": "nodeVersion",
    "os": "os",
    "self_update": {
      "supported": true,
      "writable": true,
      "install_path": "install_path",
      "manual_command": "manual_command",
      "reason": "reason"
    },
    "supported_commands": [
      "string"
    ],
    "workingDirectory": "workingDirectory"
  },
  "userId": "userId"
}
```

--------------------------------

### Create and run Python quickstart (quickstart.py)

Source: https://docs.letta.com/v1-sdk

Creates a stateful agent with memory blocks, sends a message, and prints the response. Save as quickstart.py and run with python.

```python
from letta_client import Letta
import os

client = Letta(api_key=os.getenv("LETTA_API_KEY"))

# Create a stateful agent
agent = client.agents.create(
    model="openai/gpt-4.1",
    memory_blocks=[
        {
            "label": "human",
            "value": "Name: Timber. Status: dog. Occupation: building Letta, infrastructure to democratize self-improving superintelligence"
        },
        {
            "label": "persona",
            "value": "I am a self-improving superintelligence. Timber is my best friend and collaborator."
        }
    ]
)

print(f"Agent created with ID: {agent.id}")

# Send a message
response = client.agents.messages.create(
    agent_id=agent.id,
    input="What do you know about me?"
)

for message in response.messages:
    print(message)
```

```bash
python quickstart.py
```

```bash
Agent created with ID: agent-abc123
ReasoningMessage(reasoning="Timber is asking what I know. I should reference my memory blocks.")
AssistantMessage(content="I know you're Timber, a dog who's building Letta!")
```

--------------------------------

### Install channel runtime separately

Source: https://docs.letta.com/self-hosting/channels

Installs the Telegram channel runtime separately using the `letta channels install` command. Use this when you prefer to install runtimes independently of starting the server.

```bash
letta channels install telegram
```

--------------------------------

### Navigate to project and launch CLI

Source: https://docs.letta.com/platform/cli

Change to your project directory and start the Letta CLI.

```bash
cd your-project
letta
```

--------------------------------

### Example of invoking a skill

Source: https://docs.letta.com/configuration/skills

Example command that invokes the 'acquiring-skills' skill with instructions to find and install a browser testing skill.

```plaintext
/acquiring-skills find and install a skill for browser testing
```

--------------------------------

### Create and run TypeScript quickstart (quickstart.ts)

Source: https://docs.letta.com/v1-sdk

Creates a stateful agent with memory blocks, sends a message, and prints the response. Save as quickstart.ts and run with npx tsx.

```typescript
import Letta from "@letta-ai/letta-client";

async function main() {
  const client = new Letta({ apiKey: process.env.LETTA_API_KEY });

  // Create a stateful agent
  const agent = await client.agents.create({
    model: "openai/gpt-4.1",
    memory_blocks: [
      {
        label: "human",
        value:
          "Name: Timber. Status: dog. Occupation: building Letta, infrastructure to democratize self-improving superintelligence",
      },
      {
        label: "persona",
        value:
          "I am a self-improving superintelligence. Timber is my best friend and collaborator.",
      },
    ],
  });

  console.log("Agent created with ID:", agent.id);

  // Send a message
  const response = await client.agents.messages.create(agent.id, {
    input: "What do you know about me?",
  });

  for (const message of response.messages) {
    console.log(message);
  }
}

main().catch(console.error);
```

```bash
npx tsx quickstart.ts
```

```bash
Agent created with ID: agent-abc123
{ message_type: 'reasoning_message', reasoning: 'Timber is asking what I know...' }
{ message_type: 'assistant_message', content: "I know you're Timber, a dog who's building Letta!" }
```

--------------------------------

### Install Letta Agent SDK and tsx

Source: https://docs.letta.com/agent-sdk/quickstart

Installs the @letta-ai/letta-agent-sdk package and tsx for running TypeScript. Used in both managed cloud and local quickstarts.

```bash
npm install @letta-ai/letta-agent-sdk tsx

```

--------------------------------

### Clean local setup with temporary directory

Source: https://docs.letta.com/self-hosting

Sets LETTA_LOCAL_BACKEND_DIR to a temporary directory and launches Letta with the local backend and a new agent for testing.

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

--------------------------------

### Full example: tickets-controller.ts

Source: https://docs.letta.com/self-hosting/app-server/external-tools

Complete TypeScript example of an external tool controller for the Letta App Server. It connects to the server, registers a 'lookup_ticket' tool, starts a runtime, and sends a user message. The example includes a local lookupTicket function that returns mock ticket data.

```typescript
import WebSocket from "ws";
import { createAppServerClient } from "@letta-ai/letta-code/app-server-client";

const client = await createAppServerClient({
  url: "ws://127.0.0.1:4500",
  WebSocket,
}).connect();

client.onExternalToolCall(async (request) => {
  switch (request.tool_name) {
    case "lookup_ticket": {
      const id = String(request.input.id ?? "");
      const ticket = await lookupTicket(id);
      return {
        content: [{ type: "text", text: JSON.stringify(ticket) }],
      };
    }
    default:
      throw new Error(`Unknown external tool: ${request.tool_name}`);
  }
});

const started = await client.runtimeStart({
  agent_id: "agent-123",
  create_conversation: { body: {} },
  external_tools: [
    {
      tools: [
        {
          name: "lookup_ticket",
          description: "Fetch a support ticket by ID.",
          parameters: {
            type: "object",
            properties: {
              id: { type: "string" },
            },
            required: ["id"],
            additionalProperties: false,
          },
        },
      ],
    },
  ],
});

if (!started.success || !started.runtime) {
  throw new Error(started.error ?? "Failed to start runtime");
}

client.input({
  runtime: started.runtime,
  payload: {
    kind: "create_message",
    messages: [
      {
        role: "user",
        content: "Look up LET-123 and summarize the next action.",
        client_message_id: "request-123",
      },
    ],
  },
});

// Keep this connection open while the turn runs. Stream events and external
// tool requests arrive through it.

async function lookupTicket(id: string) {
  return {
    id,
    title: "Customer cannot connect Slack",
    status: "open",
    priority: "high",
  };
}
```

--------------------------------

### Run demo agent creation script

Source: https://docs.letta.com/agent-sdk/demo-apps/react-chat

Runs the setup script to create a demo agent and store its ID in .env.local.

```bash
node --env-file=.env.local scripts/create-agent.mjs
```

--------------------------------

### Start the service with Docker Compose

Source: https://docs.letta.com/self-hosting

Build and start the App Server with Docker Compose, then follow logs and check readiness. The Compose file exposes port 4500 and creates persistent volumes for /root/.letta and /workspace.

```bash
docker compose up --build -d
docker compose logs -f
curl http://127.0.0.1:4500/readyz
```

--------------------------------

### Install letta-evals with uv

Source: https://docs.letta.com/v1-sdk/evals/getting-started

Alternative installation method using uv. Requires Python 3.11 or higher and a running Letta server.

```bash
uv pip install letta-evals
```

--------------------------------

### Start Letta CLI in project directory

Source: https://docs.letta.com/handbook/setup

Navigate to the project directory and start the Letta CLI. On first launch, it creates a local agent without requiring login.

```bash
cd /path/to/your/project
letta
```

--------------------------------

### Clone and run the mobile app

Source: https://docs.letta.com/agent-sdk/demo-apps/mobile

Clone the agent-sdk-mobile-app repository and start the iOS or Android build. Use bun install and bun run ios (or bun run android). You can also use npm install and equivalent npm scripts.

```bash
git clone https://github.com/letta-ai/agent-sdk-mobile-app.git
cd agent-sdk-mobile-app
bun install
bun run ios
# or: bun run android
```

--------------------------------

### Copy example environment file

Source: https://docs.letta.com/agent-sdk/demo-apps/react-chat

Copies the example environment file to .env.local for local configuration.

```bash
cp .env.example .env.local
```

--------------------------------

### Start Letta server with WhatsApp channel enabled

Source: https://docs.letta.com/self-hosting/channels/whatsapp

Starts the local backend server with the WhatsApp channel. On first start, prints a QR code to link the WhatsApp account. Session state is stored under ~/.letta/channels/whatsapp/auth/.

```bash
letta server --backend local --channels whatsapp
```

--------------------------------

### Start Letta App Server on a specific port

Source: https://docs.letta.com/reference/faq

Use this command to start the Letta App Server on a stable port. The server binds to 127.0.0.1 on the specified port, and the WebSocket endpoint is available at ws://127.0.0.1:4500/ws. Port 4500 is an example, not a fixed default.

```bash
letta server --listen ws://127.0.0.1:4500
```

--------------------------------

### Run quickstart.ts with environment variables

Source: https://docs.letta.com/agent-sdk/quickstart

Runs the quickstart TypeScript file with the App Server URL set to http://127.0.0.1:4500.

```bash
LETTA_APP_SERVER_URL='http://127.0.0.1:4500' npx tsx quickstart.ts
```

--------------------------------

### GET /v1/runs/{run_id}/stream

Source: https://docs.letta.com/v1-sdk/messages/long-running

Resumes streaming for a specific run, starting from a specified sequence ID. Returns a stream of chunks, including historical chunks and new ones as they become available.

```APIDOC
## GET /v1/runs/{run_id}/stream

### Description
Resumes streaming for a specific run, starting from a specified sequence ID. Returns a stream of chunks, including historical chunks and new ones as they become available.

### Method
GET

### Endpoint
https://api.letta.com/v1/runs/{run_id}/stream

### Parameters
#### Path Parameters
- **run_id** (string) - Required - The ID of the run to resume.

#### Request Body
- **starting_after** (integer) - Optional - Sequence ID to start streaming from. Use 0 to start from the beginning.
- **batch_size** (integer) - Optional - Number of historical chunks to fetch in larger batches.

### Request Example
{
  "starting_after": 0,
  "batch_size": 1000
}

### Response
#### Success Response (200)
- **chunk** (object) - A streamed chunk of data. Each historical chunk is streamed one at a time, followed by new chunks as they become available.

#### Response Example
(Stream of chunks)
```

--------------------------------

### List versions and read a file at a specific commit

Source: https://docs.letta.com/agent-sdk/repositories

Use client.repositories.versions.list() to get commit history for a file and client.repositories.versions.get() to read the file at a particular commit. The example lists up to 20 versions and reads the first one.

```javascript
const versions = await client.repositories.versions.list(repository.id, {
  path: "planning/brief.md",
  limit: 20,
});

const previous = await client.repositories.versions.get(
  repository.id,
  versions[0].sha,
  { path: "planning/brief.md" },
);

console.log(previous.content);
```
Tokens:
Raw