Deploying your agents

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.

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.