---
title: Deploying your agents | Letta Docs
description: Deployment patterns and client setup options for the Letta Agent SDK
---

The Letta Agent SDK is the recommended application interface across managed, local, and self-hosted deployments. The selected backend determines which underlying API or runtime transport the SDK manages for you.

| Goal                                                       | SDK configuration                     | Execution environment       | Where agent state lives              |
| ---------------------------------------------------------- | ------------------------------------- | --------------------------- | ------------------------------------ |
| Fully managed agent and execution environment              | `backend: "cloud"`                    | Managed sandbox             | Letta Cloud                          |
| Bring your own machine                                     | `backend: "cloud"` with `environment` | Selected remote environment | Letta Cloud                          |
| Keep agent state and the execution environment fully local | `backend: "local"`                    | Current machine             | Current machine                      |
| Connect to a runtime you operate                           | `backend: "remote"`                   | App Server machine          | Determined by the App Server backend |

## Letta Cloud

Use `backend: "cloud"` to host agents in Letta Cloud and run tools in managed cloud environments.

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


const client = new LettaAgentClient({
  backend: "cloud",
  apiKey: process.env.LETTA_API_KEY,
});


const agentId = await client.createAgent({
  persona:
    "You are a digital operations partner who can research, write reports, coordinate tasks, and remember durable context.",
});


await using session = client.resumeSession(agentId);
```

### Managed sandboxes

If you do not pass an `environment`, the SDK creates a managed sandbox for the session. The sandbox is where tools run; the agent’s memory and conversation state remain hosted in Letta Cloud.

By default, the SDK waits for the sandbox to come online, refreshes it while the session is active, and terminates it when the session closes.

Configure those options on the client:

```
const client = new LettaAgentClient({
  backend: "cloud",
  apiKey: process.env.LETTA_API_KEY,
  sandbox: {
    ttlMinutes: 5,
    readyTimeoutMs: 120_000,
    readyPollIntervalMs: 1_000,
    refreshIntervalMs: 240_000,
    terminateOnClose: true,
  },
});
```

`ttlMinutes` controls the requested sandbox TTL on refresh. `readyTimeoutMs` and `readyPollIntervalMs` control startup waiting. `refreshIntervalMs` controls background refresh while the session is open. `terminateOnClose` defaults to `true`; set it to `false` if multiple SDK sessions may share the same agent and you want TTL cleanup instead.

If you pass `cwd`, use a path inside the sandbox. Local paths like `process.cwd()` are not mounted into managed sandboxes automatically.

### Bring your own machine

Use a [remote environment](/platform/computers/byom/index.md) to provide an agent hosted in Letta Cloud with an execution environment on a machine you control. The machine connects outward to Letta Cloud and remains available to its hosted clients.

```
const client = new LettaAgentClient({
  backend: "cloud",
  apiKey: process.env.LETTA_API_KEY,
  environment: { name: "work-laptop" },
});
```

You can also select the environment per session:

```
await using session = client.resumeSession(agentId, {
  environment: { deviceId: "device-..." },
  cwd: "/workspace/project",
});
```

`environment` and `sandbox` are mutually exclusive. Use `environment` when you choose the runtime; omit it when the SDK should create a managed sandbox.

## Local App Server

Use `backend: "local"` for a fully local deployment. The Agent SDK package includes Letta Code and starts an SDK-owned App Server subprocess on the current machine.

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


const agentId = await client.createAgent({
  persona:
    "You are a resident engineering teammate for this repository. You inspect files, learn conventions, and keep durable memory of important patterns.",
});


await using session = client.resumeSession(agentId, {
  cwd: "/Users/me/project",
});
```

Agent state, filesystem access, and tool execution remain on the current machine. The SDK owns the App Server lifecycle, so your application does not need to start or connect to the server manually.

## Self-hosted App Server

Use `backend: "remote"` when the agent runtime should run on a machine you operate separately from your application.

For a fully self-hosted runtime, start App Server with the local backend:

Terminal window

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

Then connect the SDK:

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

With `--backend local`, agent state and the execution environment remain on the App Server machine. App Server can also run with `--backend cloud`; in that configuration, agent state is hosted in Letta Cloud while the execution environment remains on the App Server machine.

Unlike a remote environment, App Server accepts a direct connection from your application. It does not register itself as a selectable environment in Letta Cloud’s hosted clients.

For startup, authentication, and lower-level protocol details, see [App Server](/platform/app-server/index.md).