Package sh.createos.jenkins.sandbox

Class CreateOSApiClient

java.lang.Object

sh.createos.jenkins.sandbox.CreateOSApiClient

public class CreateOSApiClient
extends Object

HTTP client for the CreateOS Sandbox control plane API.

Uses Java's built-in HttpClient (no external dependencies). All responses follow JSend format: { "status": "success", "data": {...} }

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	CreateOSApiClient.ExecResult	Result from a CreateOS exec call.
static final record	CreateOSApiClient.SandboxSummary	Identity of one sandbox as the list endpoint reports it.

Constructor Summary

Constructors

Constructor	Description
CreateOSApiClient(String baseUrl, String apiKey)	Creates a client for the given CreateOS API endpoint and API key.

Method Summary

Modifier and Type	Method	Description
String	createSandbox(CreateOSSandboxRequest request)	Create a new sandbox and return its ID.
void	destroySandbox(String sandboxId)	Destroy a sandbox.
void	downloadFile(String sandboxId, String remotePath, OutputStream output)	Downloads raw bytes from an absolute path inside the sandbox.
String	getSandboxStatus(String sandboxId)	Get the current status of a sandbox.
boolean	isRunning(String sandboxId)	Reports whether a sandbox is still running.
List<CreateOSApiClient.SandboxSummary>	listSandboxes()	Lists every sandbox visible to this API key.
com.fasterxml.jackson.databind.JsonNode	runBash(String sandboxId, String script)	Run a bash script inside a sandbox and return once it exits.
CreateOSApiClient.ExecResult	runShellScript(String sandboxId, String script, PrintStream log, boolean collectStdout)	Runs a shell script inside the sandbox and streams output into the Jenkins log.
void	testConnection()	Verify that this API key can access the CreateOS sandbox endpoint.
void	uploadFile(String sandboxId, String remotePath, InputStream input)	Uploads raw bytes to an absolute path inside the sandbox.
void	waitForRunning(String sandboxId, Duration timeout)	Poll until sandbox reaches "running" state.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

CreateOSApiClient

public CreateOSApiClient(String baseUrl,
 String apiKey)

Creates a client for the given CreateOS API endpoint and API key.

Method Details

testConnection

public void testConnection()
                    throws IOException

Verify that this API key can access the CreateOS sandbox endpoint.

Throws:

IOException

createSandbox

public String createSandbox(CreateOSSandboxRequest request)
                     throws IOException

Create a new sandbox and return its ID.

POST /v1/sandboxes

Throws:

IOException

getSandboxStatus

public String getSandboxStatus(String sandboxId)
                        throws IOException

Get the current status of a sandbox.

Throws:

IOException

isRunning

public boolean isRunning(String sandboxId)

Reports whether a sandbox is still running.

Any failure to answer counts as "not running". This backs decisions about adopting a sandbox the controller believes it owns, and treating an unreachable or deleted sandbox as alive would attach an agent to nothing.

listSandboxes

public List<CreateOSApiClient.SandboxSummary> listSandboxes()
                                                     throws IOException

Lists every sandbox visible to this API key.

Throws:

IOException

runBash

public com.fasterxml.jackson.databind.JsonNode runBash(String sandboxId,
 String script)
                                                throws IOException

Run a bash script inside a sandbox and return once it exits.

POST /v1/sandboxes/{id}/exec Body: { "cmd": "bash", "args": ["-c", "..."] }

Throws:

IOException

runShellScript

public CreateOSApiClient.ExecResult runShellScript(String sandboxId,
 String script,
 PrintStream log,
 boolean collectStdout)
                                            throws IOException

Runs a shell script inside the sandbox and streams output into the Jenkins log.

Throws:

IOException

uploadFile

public void uploadFile(String sandboxId,
 String remotePath,
 InputStream input)
                throws IOException

Uploads raw bytes to an absolute path inside the sandbox.

Throws:

IOException

downloadFile

public void downloadFile(String sandboxId,
 String remotePath,
 OutputStream output)
                  throws IOException

Downloads raw bytes from an absolute path inside the sandbox.

Throws:

IOException

destroySandbox

public void destroySandbox(String sandboxId)
                    throws IOException

Destroy a sandbox.

DELETE /v1/sandboxes/{id}

Throws:

IOException

waitForRunning

public void waitForRunning(String sandboxId,
 Duration timeout)
                    throws IOException,
InterruptedException

Poll until sandbox reaches "running" state.

Throws:

IOException

InterruptedException