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();

​
Troubleshooting

Symptom: Gradle/Maven can’t resolve app.simplecloud.api:api.Solution:
  1. Add both repositories:
    • https://repo.simplecloud.app/snapshots
    • https://buf.build/gen/maven
  2. Refresh: gradle --refresh-dependencies or mvn -U clean install
  3. Check network access to repository URLs
Symptom: Plugin fails with ClassNotFoundException for SimpleCloud classes.Cause: API shaded into JAR or plugin load order wrong.Solution:
  1. Don’t shade the API - use compileOnly scope
  2. Add simplecloud-api to plugin descriptor dependencies
  3. Verify SimpleCloud API plugin loads before yours
Symptom: CloudApi.create() throws exception.If connection refused:
  • Verify server runs inside SimpleCloud
  • Check environment variables are set
  • For standalone apps, verify controller/NATS URLs
If authentication failed:
  • Check SIMPLECLOUD_NETWORK_ID is correct
  • Check SIMPLECLOUD_NETWORK_SECRET matches
Symptom: Errors about incompatible API versions.Solution:
  1. Use compileOnly scope (not implementation)
  2. Check other plugins for bundled API versions
  3. Match API version to your SimpleCloud installation