Cloud repositories

Cloud repositories let your application upload text files to the Letta Developer Platform and make them available to Letta Agent during a Cloud session. Use them for app-provided input files or shared working context that an agent should inspect or update.

Repository APIs and repository session resources require a LettaAgentClient configured with backend: "cloud". Local and remote backends reject non-empty repository resources.

A Cloud repository is a Letta-hosted, git-backed collection of text files. It is not a GitHub repository or a directory on the machine running your application. When you attach one to a session, Letta Code syncs it into the Cloud runtime so the agent can inspect it with its file and shell tools.

Create and attach a repository

Create a repository, add files, and pass its ID in the session’s resources option:

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

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

const repository = await client.repositories.create({
  name: "launch-inputs",
});

await client.repositories.files.create(repository.id, {
  path: "brief.md",
  content: "# Launch brief\n\nTarget date: September 15\n",
});

const agentId = await client.createAgent({
  model: "anthropic/claude-opus-4-8",
  persona:
    "You are a product operations partner who turns source material into concise, actionable plans.",
});

await using session = client.createSession(agentId, {
  resources: [
    {
      type: "repository",
      repositoryId: repository.id,
    },
  ],
});

await session.send(
  "Read the launch brief, identify missing decisions, and write an action plan.",
);

for await (const message of session.stream()) {
  if (message.type === "assistant") console.log(message.content);
}

client.createSession() and client.resumeSession() initialize lazily. During initialization, the SDK checks which repositories are already linked to the agent, attaches missing repositories, waits for each attachment to become visible, and then starts the Cloud runtime.

Manage files

File helpers are available under client.repositories.files:

Method	Description
list(repositoryId, params?)	List files and directories at the current or a given ref
create(repositoryId, params)	Create a text file
read(repositoryId, params)	Read a text file at the current or a given ref
update(repositoryId, params)	Replace content, rename a file, or both
delete(repositoryId, params)	Delete a file

Use a content hash precondition when an update should fail rather than overwrite a file that changed after you read it:

const current = await client.repositories.files.read(repository.id, {
  path: "brief.md",
});

const updated = await client.repositories.files.update(repository.id, {
  path: current.path,
  content: `${current.content}\nOwner: Product Operations\n`,
  precondition: {
    contentSha256: current.contentSha256,
  },
});

console.log(updated.commitSha);

To rename a file, pass newPath to update():

await client.repositories.files.update(repository.id, {
  path: "brief.md",
  newPath: "planning/brief.md",
});

Read version history

Each file mutation creates a commit. Use client.repositories.versions to list commits and read a file at a particular commit:

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);

files.list() and files.read() also accept ref when you need a consistent historical snapshot.

Session lifecycle

Repository resources are links between a hosted repository and an agent. The SDK manages those links for the lifetime of a session:

• Duplicate repository IDs in one resources array are deduplicated.
• A repository already linked to the agent is not linked again or detached by the SDK.
• If session initialization fails, the SDK attempts to remove links it created.
• When the session closes, the SDK attempts to remove only links it created.

Session cleanup is asynchronous. Abrupt process termination or a network failure can leave a repository linked to the agent. Repository links are agent-scoped, and concurrent SDK sessions are not reference-counted. If multiple sessions use the same agent and temporary repository, one session can remove the link while another is still running.

The SDK does not currently expose explicit persistent attach or detach methods. Use resources when the attachment should follow the SDK session lifecycle.

Permissions and limits

Capability	Current behavior
Attachment permissions	New SDK-managed links use the platform default, currently read_write
Existing links	Keep their existing permissions
Content	UTF-8 text passed as a JavaScript string
File size	Up to 10 MiB per file
File count	Up to 2,000 files per repository
Upload API	Creates or updates one file per request; no bulk directory helper
Repository names	Unique, up to 64 letters, numbers, dots, underscores, or hyphens
Delete behavior	client.repositories.delete() soft-deletes the repository

The RepositoryResource type does not currently expose a permission setting. Because a newly attached repository defaults to read_write, an agent can modify and commit files in it. The Agent SDK cannot create a read-only attachment today; an existing read-only link keeps its current permissions.

See the SDK reference for all repository methods and types.