pocketenv - v1.1.0

pocketenv/sandbox

Create, manage, and interact with Pocketenv sandboxes.

A sandbox is an isolated cloud environment that can run commands, expose ports, and host services. All other resources (env vars, secrets, files, volumes, services) are attached to a sandbox.

Types

ConnectedSandbox

</>

A sandbox bundled with its client — returned by create and connect. All operations (start, stop, exec, …) work directly on this type.

pub type ConnectedSandbox {
  ConnectedSandbox(data: Sandbox, client: pocketenv.Client)
}

Constructors

ExecResult

</>

The output of a command executed inside a sandbox.

pub type ExecResult {
  ExecResult(stdout: String, stderr: String, exit_code: Int)
}

Constructors 

  • ExecResult(stdout: String, stderr: String, exit_code: Int)

Sandbox

</>

Full details of a Pocketenv sandbox.

pub type Sandbox {
  Sandbox(
    id: String,
    name: String,
    provider: option.Option(String),
    base_sandbox: option.Option(String),
    display_name: option.Option(String),
    uri: option.Option(String),
    description: option.Option(String),
    topics: option.Option(List(String)),
    logo: option.Option(String),
    readme: option.Option(String),
    repo: option.Option(String),
    vcpus: option.Option(Int),
    memory: option.Option(Int),
    disk: option.Option(Int),
    installs: option.Option(Int),
    status: option.Option(String),
    started_at: option.Option(String),
    created_at: String,
  )
}

Constructors

SandboxBuilder

opaque </>

A builder for configuring a new sandbox before calling create.

pub opaque type SandboxBuilder

Values

connect

</> 
pub fn connect(
  sandbox: Sandbox,
  client: pocketenv.Client,
) -> ConnectedSandbox

Wraps a Sandbox obtained from get/list with a client, producing a ConnectedSandbox that can be passed to start, stop, exec, etc.

Example

let assert Ok(#(sandboxes, _)) = sandbox.list(client, None, None)
let assert [first, ..] = sandboxes
let sb = first |> sandbox.connect(client)
sb |> sandbox.exec("ls")

create

</> 
pub fn create(
  builder: SandboxBuilder,
) -> Result(ConnectedSandbox, pocketenv.PocketenvError)

Creates the sandbox and returns a ConnectedSandbox ready for use.

Example

let assert Ok(sb) =
  client
  |> sandbox.new("my-app", "openclaw", "cloudflare")
  |> sandbox.create()

sb |> sandbox.start(None, None)
sb |> sandbox.exec("echo hello")
sb |> sandbox.stop()

delete

</> 
pub fn delete(
  sb: ConnectedSandbox,
) -> Result(Nil, pocketenv.PocketenvError)

Permanently deletes the sandbox.

Example

sb |> sandbox.delete()

exec

</> 
pub fn exec(
  sb: ConnectedSandbox,
  command: String,
) -> Result(ExecResult, pocketenv.PocketenvError)

Executes a shell command inside the running sandbox. Returns stdout, stderr, and the exit code.

Example

let assert Ok(res) = sb |> sandbox.exec("ls /app")
io.println(res.stdout)

exec_decoder

</> 
pub fn exec_decoder() -> decode.Decoder(ExecResult)

JSON decoder for ExecResult.

expose_vscode

</> 
pub fn expose_vscode(
  sb: ConnectedSandbox,
) -> Result(Nil, pocketenv.PocketenvError)

Exposes a VS Code server on the sandbox.

Example

sb |> sandbox.expose_vscode()

get

</> 
pub fn get(
  client: pocketenv.Client,
  id: String,
) -> Result(option.Option(Sandbox), pocketenv.PocketenvError)

Fetches a single sandbox by id. Returns None if not found.

Example

let assert Ok(Some(sb)) = sandbox.get(client, "sandbox-abc123")

get_actor_sandboxes

</> 
pub fn get_actor_sandboxes(
  client: pocketenv.Client,
  did: String,
  limit: option.Option(Int),
  offset: option.Option(Int),
) -> Result(List(Sandbox), pocketenv.PocketenvError)

Lists sandboxes owned by the actor identified by did.

list

</> 
pub fn list(
  client: pocketenv.Client,
  limit: option.Option(Int),
  offset: option.Option(Int),
) -> Result(#(List(Sandbox), Int), pocketenv.PocketenvError)

Lists sandboxes visible to the authenticated actor. Returns a tuple of #(sandboxes, total_count). Optionally paginate with limit and offset.

Example

let assert Ok(#(sandboxes, total)) = sandbox.list(client, Some(10), None)

new

</> 
pub fn new(
  client: pocketenv.Client,
  name: String,
  base: String,
  provider: String,
) -> SandboxBuilder

Starts a sandbox builder with the three required fields. Chain optional with_* setters then call create().

Example

let assert Ok(sb) =
  client
  |> sandbox.new("my-app", "openclaw", "cloudflare")
  |> sandbox.with_description("My app sandbox")
  |> sandbox.create()

sandbox_decoder

</> 
pub fn sandbox_decoder() -> decode.Decoder(Sandbox)

JSON decoder for Sandbox.

start

</> 
pub fn start(
  sb: ConnectedSandbox,
  repo: option.Option(String),
  keep_alive: option.Option(Bool),
) -> Result(Nil, pocketenv.PocketenvError)

Starts the sandbox. Optionally clone a repo on start and keep the sandbox alive with keep_alive.

Example

sb |> sandbox.start(None, Some(True))

stop

</> 
pub fn stop(
  sb: ConnectedSandbox,
) -> Result(Nil, pocketenv.PocketenvError)

Stops the sandbox.

Example

sb |> sandbox.stop()

with_description

</> 
pub fn with_description(
  builder: SandboxBuilder,
  description: String,
) -> SandboxBuilder

Sets a human-readable description for the sandbox.

with_repo

</> 
pub fn with_repo(
  builder: SandboxBuilder,
  repo: String,
) -> SandboxBuilder

Sets the Git repo URL to clone when the sandbox starts.

✨ Search Document