Deploying your agents

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 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:

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.