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

The Letta Agent SDK supports managed cloud, local, and self-hosted deployment patterns. Configure your SDK client with the backend that matches where the agent runs.

## Constellation (managed cloud)

Use `backend: "cloud"` to create and run agents on Constellation.

```
import { LettaCodeClient } from "@letta-ai/letta-code-sdk";


const client = new LettaCodeClient({
  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 stay with the Constellation agent.

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 LettaCodeClient({
  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.

### Self-hosted remotes

Use a remote environment when you want Constellation agent state but tool execution on a machine you control.

```
const client = new LettaCodeClient({
  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. For setup, see [Remote environments](/letta-code/remote/index.md).

## Local device

Use `backend: "local"` to run on the current machine. The Agent SDK package includes Letta Code and starts it as an SDK-owned app-server subprocess.

```
const client = new LettaCodeClient({ 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",
});
```

Local sessions use local filesystem paths and local Letta Code state.

## Remote (self-hosted) app server

Use `backend: "remote"` when you run your own Letta Code app-server and want the SDK to connect to it.

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

This is fully self-hosted: agent state and tool execution live wherever the app-server runs. It does not connect to web/mobile clients and will not be visible in the desktop app or CLI unless those clients are running on, or explicitly connected to, the app-server machine.

For lower-level app-server details, see [App Server](/letta-code/app-server/index.md).