Language Server Protocol

Language Server Protocol (LSP) support is available through LSP server instances created from a sandbox. A language server runs inside the sandbox and analyzes the project's code, so your application gets IDE-grade code intelligence for code that never leaves the sandbox.

An LSP server covers code completions, file open and close notifications, document symbols, and project-wide symbol search. Each server instance is scoped to one language and one project directory. Python and TypeScript are the supported language IDs; the matching server binary (pylsp or typescript-language-server) must be installed in the sandbox image, otherwise starting the server fails with an LSP server unavailable error.

Use cases

LSP servers are used when an application needs code intelligence for code that stays in a sandbox.

• Coding agents: an agent searches workspace symbols to find where a function or class is defined before it edits code. Each match carries the file URI and the line range, so the agent opens the right file at the right line.
• Browser-based editors: an editor in a web application shows completions and an outline of the open file. The language server computes both in the sandbox, next to the code.
• Code navigation: document symbols list the functions, classes, and variables of a file, with their kind and position. An application builds an outline or jumps to a definition from the list.
• Completions for generated code: an agent or an editor requests completions at a position to fill in names that exist in the project. A trigger character, such as a dot, tells the server how the completion started.
• Signatures and documentation: completion items carry details such as a type signature and documentation. An agent reads how to call a function before it writes the call.
• Repository overviews: an agent lists the document symbols of each file to learn the structure of an unfamiliar project, without reading every file in full.
• Code that stays in the sandbox: the language server reads files from the sandbox filesystem. Your application gets code intelligence without copying the source code out of the sandbox.
• Projects with several languages: each server covers one language and one project directory. A sandbox runs a Python server for one directory and a TypeScript server for another.

Workflow

Follow this order when using LSP in a sandbox:

1. Call sandbox.lsp.start() with a language ID and project path to get its server
2. Call didOpen() on a file before requesting its completions or symbols
3. Use completions, document symbols, or workspace symbols on the server
4. Call didClose() when you finish with a file
5. Call stop() on the server when it is no longer needed

Create LSP servers

Create a sandbox whose image includes the language server, then start the server for a project directory. Daytona does not install language servers: the binary must be in the image and on its path. Create the project directory in the image or before starting the server.

from daytona import Daytona
from daytona.v2 import ImageBuilder

# Create a sandbox from an image that ships pylsp
daytona = Daytona()
sandbox = daytona.v2.create_from_build(
    ImageBuilder.from_dockerfile(
        "FROM python:3.12-slim\n"
        "RUN pip install --no-cache-dir python-lsp-server\n"
        "RUN mkdir -p /workspace/project\n"
    )
)

# Start the Python language server for the project
server = sandbox.lsp.start("python", "/workspace/project")

Start LSP servers

Start a language server for a language and a project directory. Starting a server for a language and directory that already has a running server reuses that server. The other operations never start a server implicitly; until the server is started, they fail with a not started error.

server = sandbox.lsp.start("python", "/workspace/project")
# Now ready for LSP operations

Stop LSP servers

Stop a language server. Stopping sends the server a shutdown request and ends its process, which frees one of the sandbox's server slots.

# When done with LSP features
server.stop()

Code completions

Get completion candidates at a position in an open file, computed from the content sent when the file was opened. Character offsets count UTF-16 code units within the line.

completions = server.completions(
    "file:///workspace/project/main.py",
    {"line": 10, "character": 15},
)
for item in completions.items:
    print(f"Completion: {item.label}")

Completion context

Pass a completion context to tell the language server how the completion was triggered. The trigger kind is the completion trigger kind number from the Language Server Protocol specification. Set the trigger character when a typed character, such as a dot, opened the completion. Without a context, the server receives none.

completions = server.completions(
    "file:///workspace/project/main.py",
    {"line": 10, "character": 15},
    context={"triggerKind": 2, "triggerCharacter": "."},
)

Completion item fields

File notifications

Open file

Open a file on the language server. The file's content is read from the sandbox filesystem and sent to the server, which works from it: later changes on disk are not sent.

# Notify server that a file is open
server.did_open("file:///workspace/project/main.py")

Close file

# Notify server that a file is closed
server.did_close("file:///workspace/project/main.py")

Document symbols

symbols = server.document_symbols("file:///workspace/project/main.py")
for symbol in symbols:
    print(f"Symbol: {symbol.name}, Kind: {symbol.kind}")

Workspace symbols

Search the project for symbols that match a query string. The query is passed to the language server as is, so the matching rules are those of the server for the language.

symbols = server.workspace_symbols("MyClass")
for symbol in symbols:
    print(f"Found: {symbol.name} in {symbol.location.uri}")

Symbol fields

Document symbols and workspace symbols return the same flat symbol shape. Hierarchical document symbol answers from the language server are reduced to the same three fields: nested children are dropped, and a symbol without a location gets an empty URI and a zero range.