Struct Client 

pub struct Client { /* private fields */ }

A client for a hosted boxxkite control-plane’s /v1/* REST API.

Construct one with Client::new for the common case, or Client::builder for control over the timeout or the underlying reqwest::Client (e.g. to point it at a test server). Cheap to clone – clone freely instead of wrapping in Arc yourself.

Implementations

impl Client

pub async fn account(&self) -> Result<Account, BoxxkiteError>

GET /v1/account – the account identity for the API key in use.

pub async fn usage(&self) -> Result<UsageSummary, BoxxkiteError>

GET /v1/usage – current usage against this account’s fair-use limits (the same shape returned inline on Client::create_sandbox).

pub async fn request_password_reset( &self, email: &str, ) -> Result<MessageResponse, BoxxkiteError>

POST /v1/auth/password-reset/request – request a password-reset email. Opt-in server-side (BOXXKITE_PASSWORD_RESET_ENABLED); 404s with code feature_disabled if the deployment hasn’t enabled it. Always returns the same message whether or not the email is registered, so it can’t be used to enumerate accounts.

pub async fn confirm_password_reset( &self, token: &str, new_password: &str, ) -> Result<MessageResponse, BoxxkiteError>

POST /v1/auth/password-reset/confirm – consume a single-use token from Client::request_password_reset and set a new password. Also revokes every outstanding refresh token for the account, if refresh tokens are enabled server-side.

pub async fn verify_email( &self, token: &str, ) -> Result<MessageResponse, BoxxkiteError>

POST /v1/auth/verify-email – consume a single-use email-verification token. Opt-in server-side (BOXXKITE_EMAIL_VERIFICATION_ENABLED).

pub async fn resend_verification( &self, access_token: &str, ) -> Result<MessageResponse, BoxxkiteError>

POST /v1/auth/resend-verification – re-send the verification email for the dashboard-JWT-authenticated account. access_token is a dashboard session token (the JWT returned by /v1/auth/login or /v1/auth/signup) – a different, non-interchangeable credential type from this client’s own api_key, so it overrides this call’s Authorization header rather than using the client’s key.

pub async fn refresh_token( &self, refresh_token: &str, ) -> Result<TokenPair, BoxxkiteError>

POST /v1/auth/refresh – exchange a still-valid refresh token for a brand new access_token + refresh_token pair. Opt-in server-side (BOXXKITE_REFRESH_TOKENS_ENABLED). Revokes the presented token in the same request (rotation, not reuse) – store the new refresh_token from the response and discard the one presented here.

pub async fn logout(&self, refresh_token: &str) -> Result<(), BoxxkiteError>

POST /v1/auth/logout – revoke one refresh token immediately. Opt-in server-side (BOXXKITE_REFRESH_TOKENS_ENABLED). Always succeeds (204) whether or not the token was valid – never leaks which.

pub async fn get_allowed_commands( &self, ) -> Result<AllowedCommandsResponse, BoxxkiteError>

GET /v1/account/allowed-commands – the current per-account command allowlist. An empty rules means unrestricted (the default). This allowlist is an opt-in guardrail, not a sandbox-escape boundary.

pub async fn set_allowed_commands( &self, rules: Vec<AllowedCommandRule>, ) -> Result<AllowedCommandsResponse, BoxxkiteError>

PUT /v1/account/allowed-commands – replace the per-account command allowlist wholesale. rules must be non-empty; use Client::clear_allowed_commands to reset to unrestricted.

pub async fn clear_allowed_commands(&self) -> Result<(), BoxxkiteError>

DELETE /v1/account/allowed-commands – remove the per-account command allowlist, back to the unrestricted default.

impl Client

pub async fn get_log( &self, session_id: &str, options: GetLogOptions, ) -> Result<AuditLogResponse, BoxxkiteError>

GET /v1/sandboxes/{id}/log – paginated exec/file-op audit history.

pub fn watch( &self, session_id: &str, ) -> Pin<Box<dyn Stream<Item = Result<AuditLogEntry, BoxxkiteError>> + Send + 'static>>

GET /v1/sandboxes/{id}/watch – streams new audit-log entries as they’re written, one AuditLogEntry per Server-Sent Event. This is a live feed of exec/file operations as the control-plane logs them, not a live terminal (that’s Client::takeover).

The stream ends when the sandbox session is destroyed or the caller drops it. Bring futures_util::StreamExt (or any other Stream combinator crate) into scope to consume it:

let mut entries = client.watch(session_id);
while let Some(entry) = entries.next().await {
    match entry {
        Ok(entry) => println!("{entry:?}"),
        Err(err) => {
            eprintln!("watch error: {err}");
            break;
        }
    }
}

impl Client

pub fn new( base_url: impl Into<String>, api_key: impl Into<String>, ) -> Result<Self, BoxxkiteError>

Shorthand for Client::builder().base_url(base_url).api_key(api_key).build().

pub fn builder() -> ClientBuilder

Start building a Client with non-default options (timeout, a preconfigured reqwest::Client, etc).

impl Client

pub async fn desktop_takeover( &self, session_id: &str, ) -> Result<DesktopStream, BoxxkiteError>

WS /v1/sandboxes/{id}/desktop – interactive GUI/remote-desktop human takeover of a sandbox session.

Reuses Client::takeover’s RBAC gate as-is: requires an "admin"-role API key (see POST /v1/api-keys’s role field) – a "member"-role key closes the connection with close code 4403. There is no dedicated can_initiate_desktop permission yet, and no read-only variant of this connection. A missing/invalid/expired credential closes with 4401; an unowned or already-destroyed session_id closes with 4404 – this deployment closes with 4404 as well when BOXXKITE_DESKTOP_ENABLED is unset. All surface as a BoxxkiteError::WebSocket (or, for a close that happens after a clean handshake, as a close frame on the returned stream itself – inspect it if the connection ends unexpectedly).

impl Client

pub async fn exec( &self, session_id: &str, command: &str, options: ExecOptions, ) -> Result<ExecResult, BoxxkiteError>

POST /v1/sandboxes/{id}/exec – run a shell command inside the session’s sandbox and return its exit code, stdout, and stderr. Commands run synchronously; there is no streaming of partial output.

pub async fn http_request( &self, session_id: &str, method: &str, url: &str, options: HttpRequestOptions, ) -> Result<HttpRequestResult, BoxxkiteError>

POST /v1/sandboxes/{id}/http-request – the secrets-broker HTTP request proxy (docs/SECRETS-DESIGN.md). options.headers/ options.body may contain a literal {{secret:name}} reference for a secret granted to this session via CreateSandboxOptions::secret_names; the sidecar substitutes the real value in-process – this SDK never sees the credential.

pub async fn file_create( &self, session_id: &str, path: &str, content: &str, options: FileOptions, ) -> Result<FileCreateResult, BoxxkiteError>

POST /v1/sandboxes/{id}/files – create or overwrite a file in the session’s sandbox workspace.

pub async fn view( &self, session_id: &str, path: &str, options: ViewOptions, ) -> Result<ViewResult, BoxxkiteError>

POST /v1/sandboxes/{id}/files/view – read a text file’s contents (optionally a line range), or list a directory’s entries. Binary/image files are not supported (text-only, mirroring the sidecar’s own /view route).

pub async fn str_replace( &self, session_id: &str, path: &str, old_str: &str, new_str: &str, options: StrReplaceOptions, ) -> Result<StrReplaceResult, BoxxkiteError>

POST /v1/sandboxes/{id}/files/str-replace – replace old_str with new_str in a file; old_str must appear exactly once unless options.replace_all(true) is set.

pub async fn ls( &self, session_id: &str, options: LsOptions, ) -> Result<LsResult, BoxxkiteError>

POST /v1/sandboxes/{id}/files/ls – list a directory’s direct children.

pub async fn glob( &self, session_id: &str, pattern: &str, options: GlobOptions, ) -> Result<GlobResult, BoxxkiteError>

POST /v1/sandboxes/{id}/files/glob – find files by name pattern (e.g. "**/*.py").

pub async fn grep( &self, session_id: &str, pattern: &str, options: GrepOptions, ) -> Result<GrepResult, BoxxkiteError>

POST /v1/sandboxes/{id}/files/grep – search file contents by regex.

impl Client

pub async fn create_image( &self, options: CreateImageOptions, ) -> Result<Image, BoxxkiteError>

POST /v1/images – build a custom sandbox image (a base image plus exact-version-pinned Python/apt/npm packages). Returns immediately with a pending record; poll Client::get_image for status to reach a terminal state.

pub async fn get_image(&self, image_id: &str) -> Result<Image, BoxxkiteError>

GET /v1/images/{id} – a custom sandbox image’s build status and details.

pub async fn list_images(&self) -> Result<Vec<Image>, BoxxkiteError>

GET /v1/images – every custom sandbox image built for this account.

pub async fn delete_image(&self, image_id: &str) -> Result<(), BoxxkiteError>

DELETE /v1/images/{id} – delete a custom sandbox image.

impl Client

pub async fn lsp_start( &self, session_id: &str, language: &str, ) -> Result<LspStartResult, BoxxkiteError>

POST /v1/sandboxes/{session_id}/lsp/start – start a persistent language server (pyright for "python", typescript-language-server for "typescript"/"javascript"). Returns the opaque lsp_id handle for the other LSP calls.

pub async fn lsp_open( &self, session_id: &str, lsp_id: &str, path: &str, content: &str, ) -> Result<LspOpenResult, BoxxkiteError>

POST /v1/sandboxes/{session_id}/lsp/{lsp_id}/open – open (or full-document-replace) a document on a running language server.

pub async fn lsp_completion( &self, session_id: &str, lsp_id: &str, path: &str, line: u32, character: u32, ) -> Result<LspCompletionResult, BoxxkiteError>

POST /v1/sandboxes/{session_id}/lsp/{lsp_id}/completion – request completions at a 0-indexed (line, character) position. path must already be open on this handle (see Client::lsp_open).

pub async fn lsp_stop( &self, session_id: &str, lsp_id: &str, ) -> Result<LspStopResult, BoxxkiteError>

POST /v1/sandboxes/{session_id}/lsp/{lsp_id}/stop – gracefully shut down a running language server.

impl Client

pub async fn create_mcp_connection( &self, label: &str, catalog_id: McpCatalogId, ) -> Result<McpConnection, BoxxkiteError>

POST /v1/mcp-connections – grant this account access to one curated outbound-MCP catalog entry.

label must be unique per account; catalog_id selects the catalog entry to grant.

pub async fn list_mcp_connections( &self, ) -> Result<Vec<McpConnection>, BoxxkiteError>

GET /v1/mcp-connections – outbound-MCP connection grants for this account.

pub async fn delete_mcp_connection( &self, connection_id: &str, ) -> Result<(), BoxxkiteError>

DELETE /v1/mcp-connections/{id} – delete an outbound-MCP connection grant owned by this account. 404s if already gone or never owned by this account.

impl Client

pub async fn remember( &self, content: &str, options: RememberOptions, ) -> Result<Memory, BoxxkiteError>

POST /v1/memory – store one durable, account-scoped memory directly. See the MemoryBase developer guide for the full model (opt-in, self-hosted retrieval by default, no third-party memory API).

pub async fn ingest_memory( &self, content: &str, options: IngestMemoryOptions, ) -> Result<MemoryIngestResponse, BoxxkiteError>

POST /v1/memory/ingest – split a bounded document or conversation into atomic memories. Works with no model provider configured (the default extractor is deterministic).

pub async fn recall( &self, query: &str, scope: Option<&str>, limit: Option<u32>, ) -> Result<MemorySearchResponse, BoxxkiteError>

GET /v1/memory/search – rank live account memories against a query using lexical evidence, phrase match, recency, and importance.

pub async fn memory_profile( &self, scope: Option<&str>, limit: Option<u32>, ) -> Result<MemoryProfileResponse, BoxxkiteError>

GET /v1/memory/profile – stable, long-lived memories separated from recently-touched ones.

pub async fn list_memories( &self, options: ListMemoriesOptions, ) -> Result<Vec<Memory>, BoxxkiteError>

GET /v1/memory – live memories for this account.

pub async fn get_memory(&self, memory_id: &str) -> Result<Memory, BoxxkiteError>

GET /v1/memory/{id} – one live memory owned by this account.

pub async fn memory_relations( &self, memory_id: &str, limit: Option<u32>, ) -> Result<MemoryRelationsResponse, BoxxkiteError>

GET /v1/memory/{id}/relations – other memories related to this one (updates/extends/related/derives edges).

pub async fn forget_memory(&self, memory_id: &str) -> Result<(), BoxxkiteError>

DELETE /v1/memory/{id} – permanently delete one memory. Not a soft-delete; a forgotten memory cannot be recalled again.

pub async fn export_memories( &self, scope: Option<&str>, ) -> Result<Value, BoxxkiteError>

GET /v1/memory/export – export live memories (and their relations) for this account, for backup or migration.

pub async fn import_memories( &self, memories: Vec<Value>, relations: Vec<Value>, ) -> Result<MemoryIngestResponse, BoxxkiteError>

POST /v1/memory/import – import memories (and optionally their relations) previously produced by Client::export_memories.

impl Client

pub async fn create_preview_url( &self, session_id: &str, port: u16, ttl_seconds: Option<u32>, ) -> Result<PreviewUrl, BoxxkiteError>

POST /v1/sandboxes/{session_id}/preview/{port} – mint a signed, time-limited URL that proxies HTTP traffic to a port a background process opened inside this session (see StartProcessOptions::expose_port).

ttl_seconds bounds how long the minted URL stays valid (30-86400); defaults to 900 (15 minutes) server-side when None.

pub async fn revoke_preview_url( &self, session_id: &str, port: u16, token_id: &str, ) -> Result<PreviewRevokeResult, BoxxkiteError>

POST /v1/sandboxes/{session_id}/preview/{port}/revoke – invalidate one specific preview-URL token (its token_id from Client::create_preview_url) before its TTL expires, without tearing down the session and without affecting any other token minted for the same session/port. Idempotent: revoking an already-revoked, already-expired, or unrecognized token_id still returns revoked = true rather than erroring.

impl Client

pub async fn start_process( &self, session_id: &str, command: &str, options: StartProcessOptions, ) -> Result<ProcessStartResult, BoxxkiteError>

POST /v1/sandboxes/{session_id}/processes – start a background process (a dev server, a test watcher, a long build, a REPL) that keeps running after this call returns. Not reachable over the network from any other call by default – same per-exec network isolation applies here – unless options.expose_port(..) is set.

pub async fn list_processes( &self, session_id: &str, ) -> Result<ProcessListResult, BoxxkiteError>

GET /v1/sandboxes/{session_id}/processes – every background process currently tracked for this session (running, exited, or stopped).

pub async fn get_process_output( &self, session_id: &str, process_id: &str, since_offset: i64, ) -> Result<ProcessOutputResult, BoxxkiteError>

GET /v1/sandboxes/{session_id}/processes/{process_id}/output – poll a background process’s output since a given byte offset. Polling-style, not streaming. since_offset (from a previous call’s next_offset, or 0 the first time) fetches only the new output since the last check.

pub fn stream_process_output( &self, session_id: &str, process_id: &str, since_offset: i64, ) -> Pin<Box<dyn Stream<Item = Result<ProcessStreamEvent, BoxxkiteError>> + Send + 'static>>

GET /v1/sandboxes/{session_id}/processes/{process_id}/stream – live SSE stream of a background process’s stdout, the streaming counterpart to get_process_output. Yields an ProcessStreamEvent::Output per new chunk, then a terminal ProcessStreamEvent::Exit. Bring futures_util::StreamExt into scope to consume it; the stream ends when the process finishes, the session is destroyed, or the caller drops it.

pub async fn send_process_input( &self, session_id: &str, process_id: &str, data: &str, ) -> Result<ProcessInputResult, BoxxkiteError>

POST /v1/sandboxes/{session_id}/processes/{process_id}/input – write to a tracked background process’s stdin pipe (e.g. answering an interactive prompt).

pub async fn stop_process( &self, session_id: &str, process_id: &str, ) -> Result<ProcessStopResult, BoxxkiteError>

POST /v1/sandboxes/{session_id}/processes/{process_id}/stop – stop a tracked background process: SIGTERM, a short grace period, then SIGKILL if still alive.

impl Client

pub async fn create_sandbox( &self, options: CreateSandboxOptions, ) -> Result<Sandbox, BoxxkiteError>

POST /v1/sandboxes – create a single sandbox. Use Client::create_sandbox_batch instead if options.count(n) with n > 1 – the server responds with a JSON array in that case, which won’t deserialize as a single Sandbox.

pub async fn create_sandbox_batch( &self, options: CreateSandboxOptions, ) -> Result<Vec<Sandbox>, BoxxkiteError>

POST /v1/sandboxes with options.count(n), n > 1 – creates a batch of sandboxes in one call and returns all of them. Each session in the batch is created and limit-checked one at a time, so a later item can still fail the concurrent-sandbox or monthly-usage cap even if earlier items succeeded (surfaces as a BoxxkiteError::Api for the whole call, per the underlying REST contract).

pub async fn get_sandbox( &self, session_id: &str, ) -> Result<Sandbox, BoxxkiteError>

GET /v1/sandboxes/{session_id} – fetch one sandbox session by id. Resolves destroyed sessions too (a lookup, not an operational route that requires a live pod).

pub async fn list_sandboxes( &self, active_only: bool, ) -> Result<Vec<Sandbox>, BoxxkiteError>

GET /v1/sandboxes – list sandbox sessions owned by this account.

pub async fn destroy_sandbox( &self, session_id: &str, ) -> Result<(), BoxxkiteError>

DELETE /v1/sandboxes/{session_id} – tear down a sandbox session.

impl Client

pub async fn create_secret( &self, name: &str, value: &str, allowed_hosts: &[String], options: CreateSecretOptions, ) -> Result<Secret, BoxxkiteError>

POST /v1/secrets – register a new org-scoped secret.

name must be unique per account; value is the real credential value, write-only (never returned by this or any other route); allowed_hosts are the destination hostnames this secret may be used against via http_request – required, not optional, since an unscoped secret usable against any destination defeats the point of this feature. A host that resolves to a private/link-local/ loopback/metadata address is rejected at creation time (a best-effort backstop; see docs/SECRETS-DESIGN.md section 5 for why the real control is the sidecar’s request-time check).

pub async fn list_secrets(&self) -> Result<Vec<Secret>, BoxxkiteError>

GET /v1/secrets – secrets registered for this account. Raw values are never returned here.

pub async fn delete_secret(&self, secret_id: &str) -> Result<(), BoxxkiteError>

DELETE /v1/secrets/{id} – delete a secret owned by this account. 404s if already gone or never owned by this account.

impl Client

pub async fn with_sandbox<F, Fut, T>( &self, options: CreateSandboxOptions, f: F, ) -> Result<T, BoxxkiteError>

where F: FnOnce(SandboxSession) -> Fut, Fut: Future<Output = Result<T, BoxxkiteError>>,

Create a sandbox, run f against a SandboxSession bound to it, and tear the sandbox down when f returns – even on error. Teardown is best-effort (an already-gone session doesn’t turn a successful f into an error), mirroring every sibling SDK’s cleanup semantics.

use boxxkite_client::{Client, CreateSandboxOptions, ExecOptions};

let client = Client::new("https://cp.example.com", "bxk_live_...")?;
let stdout = client
    .with_sandbox(CreateSandboxOptions::new().label("demo"), |sb| async move {
        let result = sb.exec("echo hi", ExecOptions::new()).await?;
        Ok(result.stdout)
    })
    .await?;
assert_eq!(stdout, "hi\n");

impl Client

pub async fn takeover( &self, session_id: &str, ) -> Result<TakeoverStream, BoxxkiteError>

WS /v1/sandboxes/{id}/takeover – interactive human takeover of a sandbox session’s shell.

Requires an "admin"-role API key (see POST /v1/api-keys’s role field) – a "member"-role key closes the connection with close code 4403. A missing/invalid/expired credential closes with 4401; an unowned or already-destroyed session_id closes with 4404. All three surface as a BoxxkiteError::WebSocket (or, for a close that happens after a clean handshake, as a close frame on the returned stream itself – inspect it if the connection ends unexpectedly).

impl Client

pub async fn create_volume( &self, size_gb: f64, options: CreateVolumeOptions, ) -> Result<Volume, BoxxkiteError>

POST /v1/volumes – create an independent storage volume. Returns immediately with a pending record; poll Client::get_volume for status before mounting it into a sandbox.

size_gb is required (max 1024).

pub async fn get_volume(&self, volume_id: &str) -> Result<Volume, BoxxkiteError>

GET /v1/volumes/{id} – a storage volume’s status and details.

pub async fn list_volumes(&self) -> Result<Vec<Volume>, BoxxkiteError>

GET /v1/volumes – every storage volume created for this account.

pub async fn delete_volume(&self, volume_id: &str) -> Result<(), BoxxkiteError>

DELETE /v1/volumes/{id} – delete a storage volume.

impl Client

pub async fn create_webhook( &self, url: &str, event_types: &[WebhookEventType], options: CreateWebhookOptions, ) -> Result<Webhook, BoxxkiteError>

POST /v1/webhooks – register a webhook subscription.

url is the HTTPS (or HTTP, for local testing) URL the control plane will POST events to; event_types must be non-empty.

pub async fn list_webhooks(&self) -> Result<Vec<Webhook>, BoxxkiteError>

GET /v1/webhooks – webhook subscriptions for this account. The signing secret is never returned here.

pub async fn delete_webhook( &self, subscription_id: &str, ) -> Result<(), BoxxkiteError>

DELETE /v1/webhooks/{id} – delete a webhook subscription owned by this account. 404s if already gone or never owned by this account.

pub async fn list_webhook_deliveries( &self, subscription_id: &str, options: ListWebhookDeliveriesOptions, ) -> Result<Vec<WebhookDelivery>, BoxxkiteError>

GET /v1/webhooks/{id}/deliveries – recent delivery attempts (pending/delivered/failed) for this subscription, newest first.

Trait Implementations

impl Clone for Client

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Client

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.