Skip to main content

​
Add Dependencies

Add the Cloud API to your build configuration. The version is fetched automatically from our Maven repository.

​
Plugin Setup

Add the SimpleCloud API plugin as a dependency in your plugin descriptor: 
name: my-plugin
version: 1.0.0
main: com.example.MyPlugin
depend: [simplecloud-api]
Don’t shade the Cloud API into your plugin. Depend on the simplecloud-api plugin instead.

​
Initialize the API

​
Default Configuration

When running inside a SimpleCloud server, the API auto-configures from environment variables: 
import app.simplecloud.api.CloudApi;

public class MyPlugin extends JavaPlugin {
    private CloudApi api;

    @Override
    public void onEnable() {
        api = CloudApi.create();
    }
}

​
Custom Configuration

For standalone applications or custom setups, provide configuration options: 
CloudApi api = CloudApi.create(CloudApiOptions.builder()
    .networkId("your-network-id")
    .networkSecret("your-secret")
    .controllerUrl("https://controller.platform.simplecloud.app")
    .natsUrl("nats://platform.simplecloud.app:4222")
    .build());

​
Environment Variables

The API reads these environment variables by default:
VariableDefaultDescription
SIMPLECLOUD_NETWORK_ID"default"Your network identifier
SIMPLECLOUD_NETWORK_SECRET""Authentication secret
SIMPLECLOUD_CONTROLLER_URL"https://controller.platform.simplecloud.app"Controller API endpoint
SIMPLECLOUD_NATS_URL"nats://platform.simplecloud.app:4222"NATS server for events
Inside SimpleCloud servers, these variables are set automatically. You only need to configure them for standalone applications or external services.

​
Best Practices

Create one CloudApi instance and reuse it. Use dependency injection if your framework supports it.
// Good - single instance
private final CloudApi api = CloudApi.create();

// Avoid - multiple instances
public void doSomething() {
    CloudApi api = CloudApi.create(); // Don't do this
}
All API methods return CompletableFuture. Don’t block on the main thread.
// Good - async handling
api.server().getAllServers().thenAccept(servers -> {
    // Process servers
});

// Avoid - blocking
List<Server> servers = api.server().getAllServers().join(); // Don't block!
Subscriptions implement AutoCloseable. Close them when done.
Subscription sub = api.event().server().onStarted(event -> { ... });

// When shutting down
sub.close();