Remote environments

Server mode makes your Letta Code agent always-on and accessible from anywhere. Run letta server on your machine and then interact with your agent from chat.letta.com, another computer, or your phone — while the agent continues to execute tools (file edits, shell commands, etc.) on your local machine.

This decouples where you interact with the agent from where the agent acts.

Quick start

letta server

On first run, you’ll be prompted to name your environment (defaults to your hostname). The CLI opens a persistent connection and waits for instructions.

You can also specify the name directly:

letta server --env-name "work-laptop"

How it works

Architecture

flowchart LR
    subgraph Clients["Any client"]
        Chat["chat.letta.com"]
        SDK["SDK / API"]
        Terminal["Another terminal"]
    end

    subgraph Local["Your machine"]
        CLI["letta server"]
        Tools["Tools (Bash, Read, Write, Edit, ...)"]
    end

    Clients -->|"Send message"| CLI
    CLI --> Tools
    CLI -->|"Stream responses"| Clients

1. You start letta server on your machine — the agent runs locally and registers itself so other clients can reach it
2. From any client (chat.letta.com, SDK, another terminal), you send a message to the agent
3. The agent executes tools on your machine (Bash, Read, Write, Edit, etc.)
4. Responses stream back to whatever client you’re using

Connection lifecycle

The connection is designed to be resilient:

• Heartbeat: Ping every 30 seconds to keep the connection alive
• Auto-reconnect: On unexpected disconnect, exponential backoff retry (1s → 30s max, 5 minutes total)
• Auto re-registration: If the connection expires, the CLI automatically re-registers and reconnects
• State recovery: On reconnect, the agent syncs its full state (permission mode, active runs, pending approvals, queue state)

Interactive approvals

Server mode supports the same approval workflow you get in interactive mode. When the agent wants to use a tool that requires permission, the approval request is shown in whatever client you’re connected with:

Agent wants to call Write on /etc/config
  → Approval request shown in [chat.letta.com](https://chat.letta.com)
  → You approve or deny
  → Agent continues execution

You can also modify tool arguments before approving — edits flow back through the same channel.

Multi-environment execution

You can run letta server on multiple machines simultaneously with the same agent. Each environment gets a unique connection:

On your laptop

letta server --env-name "laptop"

On a staging server

letta server --env-name "staging-server"

In a dev container

letta server --env-name "devcontainer"

This enables workflows where your agent reads code on your laptop, runs tests on a staging server, and deploys to production — all in one conversation.

Message queuing

When multiple messages arrive while the agent is busy processing a turn:

• Messages are queued and processed sequentially
• Consecutive user messages are coalesced (merged into a single turn)
• Queue state is visible in real-time from chat.letta.com

Session logging

Every server session writes a persistent log to ~/.letta/logs/remote/:

[14:17:03.221] → send (protocol)  {"type":"ping"}
[14:17:03.445] ← recv  (control)  {"type":"message","content":"..."}
[14:17:05.112] → send (protocol)  {"type":"run_started","run_id":"..."}

• Logs are always written (not gated behind --debug)
• The last 10 log files are kept; older ones are automatically pruned
• Useful for debugging connection issues or auditing operations

What this enables

Work from any device: Start letta server on your dev machine, then interact with your agent from chat.letta.com on your tablet, phone, or a different computer. The agent works on your machine while you direct it from anywhere.

Always-on agents: The server runs indefinitely. Even if you close chat.letta.com, the agent keeps running and can resume immediately when you reconnect.

Collaborative workflows: A teammate can interact with your agent on chat.letta.com and approve/deny file writes without needing terminal access to your machine.

Cross-environment orchestration: Run the agent across multiple machines. It can read code on your laptop, run tests on a staging server, and deploy from a third — all in one conversation.

Configuration

Saved settings

Setting	Location	Description
deviceId	~/.letta/settings.json	Stable UUID, generated once
listenerEnvName	.letta/settings.local.json (per-project)	Saved environment name

Session logs

Path	Description
~/.letta/logs/remote/{timestamp}.log	Per-session transport log