Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.litellm-agent-platform.ai/llms.txt

Use this file to discover all available pages before exploring further.

The lap CLI gives you a local terminal that connects directly to a running sandbox pod. Once attached, your terminal becomes the sandbox’s PTY — real Claude Code, real ANSI rendering, streamed over a WebSocket from the cluster. The experience feels like ssh: your iTerm, tmux, or Wezterm setup stays exactly where it is.

​
Prerequisites

  • Node 18 or newer on your local machine
  • A running LiteLLM Agent Platform deployment with at least one agent on the claude-code harness
  • The platform’s base URL and master key

​
Install from source

1

Clone the repository and install dependencies

git clone https://github.com/BerriAI/litellm-agent-platform.git
cd litellm-agent-platform/cli
npm install
chmod +x bin/lap.mjs
2

Add the binary to your PATH

The easiest option is a user-owned directory that requires no sudo:
mkdir -p ~/.local/bin
ln -sf "$PWD/bin/lap.mjs" ~/.local/bin/lap
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && exec zsh
If you prefer /usr/local/bin, use sudo:
sudo ln -sf "$PWD/bin/lap.mjs" /usr/local/bin/lap

​
Authenticate

Run lap login once to save your credentials: 
lap login
#   Agent platform URL: https://lap.acme.dev
#   Master key:         ••••••••••••••••
#   ✓ saved to ~/.lap/config.json
The config file is written with mode 0600. To remove it, run lap logout.

​
Open a sandbox

lap <agent-name>          # open by name
lap --agent <name>        # flag form, same effect
lap agents                # list agents available on the platform
lap config                # show the current saved config
lap logout                # delete ~/.lap/config.json
The agent name accepts either a human-readable name or a UUID. For example: 
lap claude-code-cli1

​
What happens when you open a sandbox

When you run lap <agent-name>, the CLI performs these steps in order:
1

Resolve the agent name

GET /api/v1/managed_agents/agents looks up the name and returns the agent ID.
2

Create a session

POST /agents/:id/session creates a new sandbox session and returns a session ID.
3

Poll until ready

GET /sessions/:id is polled until status equals ready.
4

Read connection details

sandbox_url and tty_token are read from the session response.
5

Open the WebSocket

The CLI connects to ws://<sandbox_url>/tty and sends the tty_token as an Authorization: Bearer <token> header on the WebSocket upgrade handshake. Using a header rather than a query parameter keeps the token out of access logs that record the request line.
6

Enter raw terminal mode

The local terminal switches to raw mode and pipes bytes in both directions. SIGWINCH is forwarded so the remote PTY tracks your window size automatically.

​
What’s running in the sandbox

  • The actual claude CLI running under node-pty
  • Working tree at /work/repo, optionally cloned at boot from REPO_URL
  • Stub credentials in the pod’s environment — the vault sidecar swaps them for real values on every outbound TLS connection, so the agent process cannot read the real tokens even with echo $GITHUB_TOKEN
GITHUB_TOKEN=stub_github_a8f1
LITELLM_API_KEY=stub_litellm_bb20

​
Detach and reconnect

Press Ctrl-D to detach from the sandbox. The remote session stays alive — the platform reaps it after 24 hours of message inactivity. To reconnect, run lap <agent-name> again.
A dedicated lap attach <session-id> command for reconnecting to a specific session is planned but not yet available.

​
Environment variable overrides

VariablePurpose
LAP_TTY_TOKENOverride the bearer token (normally read from session.tty_token)
LAP_TTY_FALLBACKFallback WebSocket URL when sandbox_url is an in-cluster DNS name your laptop cannot reach

​
Troubleshooting

SymptomLikely causeFix
✗ no agent named '…'Wrong agent nameRun lap config to confirm which platform you’re authenticated against; check agent names in the platform UI
✗ session create failed: 401Master key is incorrectRe-run lap login
✗ session is in-cluster — no LAP_TTY_FALLBACK setPlatform is deployed in-cluster and has not exposed a public WebSocket URLExport LAP_TTY_FALLBACK=ws://host:port/tty (provided by your platform operator) or contact your platform administrator
[ws closed] immediately after attachHarness pod was reaped or bearer token is wrongCheck lap config, then restart the session
Upgrade rejected with 401 from the harnesstty_token is missing or the harness authentication token is misconfiguredContact your platform administrator to verify the harness authentication token is correctly set on the platform