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. The query goes to the language server as is, so the matching rules are those of the server for the language.

• 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. Each file is read once, when it is opened, and later changes on disk are not sent to the server.

• 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. Positions are zero-based, and character offsets count UTF-16 code units within the line.

• 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. Daytona does not install language servers, so the server binary must be in the sandbox image and on its path.

• 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. The TypeScript server also covers JavaScript.

Workflow

Follow this order when using LSP in a sandbox:

1. Start a server for a language ID and a project path
2. Open a file on the server before requesting its completions or symbols
3. Request completions, document symbols, or workspace symbols from the server
4. Close the file when you finish with it
5. Stop 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"
    )
)

# Write a file for the examples on this page
sandbox.fs.write_text(
    "/workspace/project/main.py",
    "class MyClass:\n    def method_one(self):\n        return 1\n\nMyClass().\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. A sandbox runs at most 16 language servers at once.

# 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": 4, "character": 10},
)
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.

from daytona.v2 import LspCompletionContext

completions = server.completions(
    "file:///workspace/project/main.py",
    {"line": 4, "character": 10},
    context=LspCompletionContext(trigger_kind=2, trigger_character="."),
)

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.open_document("file:///workspace/project/main.py")

Close file

# Notify server that a file is closed
server.close_document("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.

# pylsp does not support workspace symbols: start a typescript server, in a sandbox
# whose image ships typescript-language-server as in the TypeScript tab of Create LSP servers
ts_server = sandbox.lsp.start("typescript", "/workspace/project")
ts_server.open_document("file:///workspace/project/main.ts")
symbols = ts_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.

Errors

The SDKs raise these errors with the codes in the following table, and the Toolbox API returns them in the code field. An error that the language server returns for a request reaches you as BAD_REQUEST, with the server's message after the name of the LSP method.

Permissions

Language server access runs through the toolbox of a sandbox. Access is governed by one project permission, which you can grant to an organization role or an API key.

A sandbox access token with the toolbox:lsp operation grants the same access to a single sandbox, without an API key. The sandbox read permission alone does not grant toolbox access.