Package io.agentscope.harness.agent.sandbox

Interface Sandbox

All Superinterfaces:

AutoCloseable

All Known Implementing Classes:

AbstractBaseSandbox, DockerSandbox

public interface Sandbox
extends AutoCloseable

An active sandbox with a fully isolated workspace.

Lifecycle:

1. Acquire via SandboxClient.create(io.agentscope.harness.agent.sandbox.WorkspaceSpec, io.agentscope.harness.agent.sandbox.snapshot.SandboxSnapshotSpec, O) (new) or SandboxClient.resume(io.agentscope.harness.agent.sandbox.SandboxState) (existing)
2. Call start() — initializes or restores the workspace
3. Use exec(io.agentscope.core.agent.RuntimeContext, java.lang.String, java.lang.Integer) for command execution, persistWorkspace()/hydrateWorkspace(java.io.InputStream) for archive operations
4. Call stop() — persists the snapshot (does NOT destroy resources)
5. Call shutdown() — destroys backend resources (tmpdir, container)
6. Or use close() which calls stop + shutdown in sequence

The distinction between stop() and shutdown() is critical:

• stop(): persist snapshot only — safe for both self-managed and user-managed sandboxes
• shutdown(): destroy backend resources — only called on self-managed sandboxes

Method Summary

Modifier and Type	Method	Description
void	close()
ExecResult	exec(io.agentscope.core.agent.RuntimeContext runtimeContext, String command, Integer timeoutSeconds)	Runs a shell command in the sandbox workspace.
SandboxState	getState()	Returns the current serializable state of this sandbox.
void	hydrateWorkspace(InputStream archive)
boolean	isRunning()
InputStream	persistWorkspace()
default void	shutdown()
void	start()
void	stop()

Method Details

start

void start()
    throws Exception

Throws:

Exception

stop

void stop()
   throws Exception

Throws:

Exception

shutdown

default void shutdown()
               throws Exception

Throws:

Exception

close

void close()
    throws Exception

Specified by:

close in interface AutoCloseable

Throws:

Exception

isRunning

boolean isRunning()

getState

SandboxState getState()

Returns the current serializable state of this sandbox.

Returns:

state (may be modified by lifecycle methods)

exec

ExecResult exec(io.agentscope.core.agent.RuntimeContext runtimeContext,
 String command,
 Integer timeoutSeconds)
         throws Exception

Runs a shell command in the sandbox workspace.

Parameters:

runtimeContext - per-call agent context (session, user, attributes); may be null

command - shell command

timeoutSeconds - max wait; null for implementation default

Throws:

Exception

persistWorkspace

InputStream persistWorkspace()
                      throws Exception

Throws:

Exception

hydrateWorkspace

void hydrateWorkspace(InputStream archive)
               throws Exception

Throws:

Exception