# Java SDK Reference

The Daytona Java SDK provides a robust interface for programmatically interacting with Daytona Sandboxes. It targets Java 11+ and uses OkHttp and Jackson.

## Installation

### Gradle
Add the Daytona SDK dependency to your `build.gradle.kts`:

```
dependencies {
    implementation("io.daytona:sdk:x.y.z")
}
```

### Maven
Add the Daytona SDK dependency to your `pom.xml`:

```
<dependency>
  <groupId>io.daytona</groupId>
  <artifactId>sdk</artifactId>
  <version>x.y.z</version>
</dependency>
```

## Getting Started

### Create a Sandbox
Create a Daytona Sandbox to run your code securely in an isolated environment. The following snippet is an example “Hello World” program that runs securely inside a Daytona Sandbox.

```
import io.daytona.sdk.Daytona;
import io.daytona.sdk.Sandbox;
import io.daytona.sdk.model.ExecuteResponse;

public class Main {
    public static void main(String[] args) {
        // Initialize the SDK (uses environment variables by default)
        try (Daytona daytona = new Daytona()) {
            // Create a new sandbox
            Sandbox sandbox = daytona.create();
            // Execute a command
            ExecuteResponse response = sandbox.getProcess().executeCommand("echo 'Hello, World!'");
            System.out.println(response.getResult());
            // Clean up
            sandbox.delete();
        }
    }
}
```

## Configuration
The Daytona SDK can be configured using environment variables or by passing a configuration object:

```java
// Using environment variables (DAYTONA_API_KEY, DAYTONA_API_URL, DAYTONA_TARGET)
Daytona daytona = new Daytona();
```

```java
// Using explicit configuration
DaytonaConfig config = new DaytonaConfig.Builder()
    .apiKey("YOUR_API_KEY")
    .apiUrl("YOUR_API_URL")
    .target("us")
    .build();
Daytona daytona = new Daytona(config);
```

For more information on configuring the Daytona SDK, see [API keys](/content/docs/en/api-keys#authentication/index.html).

## Real-time state updates
Starting with SDK version **0.198.0**, the SDK streams sandbox state changes over a WebSocket (Socket.IO) connection by default. Sandbox lifecycle operations that wait on a state change (start, stop, pause, resize, snapshot, delete with `wait`) complete as soon as the server pushes the new state, instead of waiting for the next polling interval.

Each `Daytona` client opens a single WebSocket connection shared by all of its sandboxes. A sparse polling safety net runs alongside the event stream, so a missed event never hangs a waiting operation.

The WebSocket handshake carries `source` and `sdkVersion` query parameters, equivalent to the `X-Daytona-Source` and `X-Daytona-SDK-Version` REST headers. The SDK collects no client-side telemetry.

### Polling fallback
If the WebSocket connection cannot be established, for example when a proxy, firewall, or network policy blocks it, the SDK falls back to polling automatically. Connection setup runs in the background and never throws, so no error handling is required.

### Opt out of event streaming
In polling-only mode the SDK never opens a WebSocket connection. Sandbox state is observed exclusively by polling the REST API, with the same cadence as SDK versions before event streaming. To opt out, set the `DAYTONA_USE_DEPRECATED_POLLING` environment variable:

```
export DAYTONA_USE_DEPRECATED_POLLING=true
```

Or set `useDeprecatedPolling` on the configuration builder. The explicit configuration option always takes precedence over the environment variable; the environment variable applies only when the option is unset.

```
DaytonaConfig config = new DaytonaConfig.Builder()
    .useDeprecatedPolling(true)
    .build();
Daytona daytona = new Daytona(config);
```

See the [`DaytonaConfig` reference](/content/docs/en/java-sdk/config/index.html) for details.

## Reference
The Java SDK reference documents the following modules:
- [CodeInterpreter](/content/docs/en/java-sdk/code-interpreter/index.html)
- [ComputerUse](/content/docs/en/java-sdk/computer-use/index.html)
- [Daytona](/content/docs/en/java-sdk/daytona/index.html)
- [DaytonaConfig](/content/docs/en/java-sdk/config/index.html)
- [Errors](/content/docs/en/java-sdk/errors/index.html)
- [FileSystem](/content/docs/en/java-sdk/file-system/index.html)
- [Git](/content/docs/en/java-sdk/git/index.html)
- [Image](/content/docs/en/java-sdk/image/index.html)
- [LspServer](/content/docs/en/java-sdk/lsp-server/index.html)
- [Process](/content/docs/en/java-sdk/process/index.html)
- [Pty](/content/docs/en/java-sdk/pty/index.html)
- [PtyHandle](/content/docs/en/java-sdk/pty-handle/index.html)
- [Sandbox](/content/docs/en/java-sdk/sandbox/index.html)
- [SecretService](/content/docs/en/java-sdk/secret-service/index.html)
- [SnapshotService](/content/docs/en/java-sdk/snapshot/index.html)
- [VolumeService](/content/docs/en/java-sdk/volume-service/index.html)