Crate boxxkite_client

Expand description

Rust client for a hosted boxxkite control-plane – create sandboxes, run commands, edit files, stream the audit log, take over a session’s shell, over HTTP/WebSocket. Not the boxxkite package itself (the self-hosted Python core that embeds SandboxManager against your own Kubernetes cluster) – use this to talk to someone else’s running control-plane, hosted or self-hosted, over its /v1/* REST API. See docs/API.md in the boxxkite repository for the full route/schema reference this crate wraps.

§Quickstart

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

let client = Client::new("https://your-control-plane.example.com", "bxk_live_...")?;

let sandbox = client
    .create_sandbox(CreateSandboxOptions::new().label("demo"))
    .await?;

let result = client.exec(&sandbox.id, "python3 -c 'print(1 + 1)'", ExecOptions::new()).await?;
println!("{}", result.stdout); // "2\n"

client.destroy_sandbox(&sandbox.id).await?;

§Error handling

Every fallible call returns Result<T, BoxxkiteError>. A non-2xx response becomes BoxxkiteError::Api (.status()/.code()); a transport-level failure becomes BoxxkiteError::Connection. See BoxxkiteError for the full set of variants.

§Scope

This crate wraps the same /v1/* API surface sdk-python/sdk-js/ sdk-go wrap: sandbox lifecycle, exec/file operations, the http_request secrets-broker proxy, background processes (start_process/list_processes/get_process_output/ send_process_input/stop_process), the audit log (get_log/watch), human/desktop takeover, network-ingress preview URLs (create_preview_url/revoke_preview_url), agent-invokable LSP completions (lsp_start/lsp_open/lsp_completion/lsp_stop), account/usage introspection, dashboard auth-flow helpers (password reset/verify/resend/refresh/logout), the per-account command allowlist (get_allowed_commands/set_allowed_commands/clear_allowed_commands), the SandboxSession/Client::with_sandbox convenience helper, and CRUD for images/volumes/outbound-MCP connections/webhooks/secrets.

Deliberately not included (see sdk-rust/README.md’s “Scope” section for the full disclosure): a LangChain-style tool-factory wrapper (no dominant Rust agent-framework tool-spec convention exists yet to mirror), a synchronous/blocking client variant (this crate is async-first via tokio, matching Rust’s ecosystem convention), and the control-plane’s filesystem-snapshot routes (a real endpoint, but not wrapped by sdk-python/sdk-js/sdk-go either as of this writing).

§Retries

Automatic retry with exponential backoff + jitter is opt-in via ClientBuilder::max_retries/ClientBuilder::retry; see RetryConfig for exactly which failures are retried (and which never are). Off by default.

Structs§

Account: The account identity for the API key in use (GET /v1/account).
AllowedCommandRule: One account-level command-allowlist rule – either a bare command name (args_allow/args_deny both empty) or a command name plus argument allow/deny regex lists.
AllowedCommandsResponse: Body shape shared by Client::get_allowed_commands/ Client::set_allowed_commands. An empty rules means unrestricted – the default for every account.
AuditLogEntry: One row of GET /v1/sandboxes/{id}/log’s audit trail – one exec/file operation, whether issued by the agent (source: "agent") or by a human during a takeover session (source: "human_takeover").
AuditLogResponse: GET /v1/sandboxes/{id}/log’s response.
Client: A client for a hosted boxxkite control-plane’s /v1/* REST API.
ClientBuilder: Builder for Client. base_url and api_key are required; everything else has a sensible default.
CreateImageOptions: Builder for POST /v1/images’s optional fields.
CreateSandboxOptions: Builder for POST /v1/sandboxes’s optional fields. All fields are unset (server defaults apply) unless set via the chained setters.
CreateSecretOptions: Builder for POST /v1/secrets’s optional fields.
CreateVolumeOptions: Builder for POST /v1/volumes’s optional fields.
CreateWebhookOptions: Builder for POST /v1/webhooks’s optional fields.
ExecOptions: Optional exec parameters.
ExecResult: POST /v1/sandboxes/{id}/exec’s response.
FileCreateResult: POST /v1/sandboxes/{id}/files’s response.
FileOptions: A single optional description field shared by every file-op request – a caller-supplied annotation surfaced later in get_log’s audit trail.
GetLogOptions: Optional get_log pagination parameters.
GlobOptions: Optional glob parameters.
GlobResult: POST /v1/sandboxes/{id}/files/glob’s response.
GrepOptions: Optional grep parameters.
GrepResult: POST /v1/sandboxes/{id}/files/grep’s response.
HttpRequestOptions: Optional http_request parameters.
HttpRequestResult: POST /v1/sandboxes/{id}/http-request’s response.
Image: A custom sandbox image (SandboxImageOut/SandboxImageBuildAccepted). Client::create_image’s response only ever populates id/label/ status/created_at – the rest fill in once you poll Client::get_image and the build reaches a terminal state.
IngestMemoryOptions: Builder for Client::ingest_memory’s optional fields.
ListMemoriesOptions: Options for Client::list_memories.
ListWebhookDeliveriesOptions: Optional list_webhook_deliveries pagination parameters.
LsOptions: Optional ls parameters.
LsResult: POST /v1/sandboxes/{id}/files/ls’s response. Each entry’s shape isn’t pinned by the API contract (list[dict] server-side), so entries are left as raw JSON rather than an over-fitted struct.
LspCompletionResult: POST /v1/sandboxes/{id}/lsp/{lsp_id}/completion’s response. Each item is a raw LSP CompletionItem object – left as raw JSON rather than an over-fitted struct, since the shape is the language server’s, not this API’s (matching how ls/glob leave their entries untyped).
LspOpenResult: POST /v1/sandboxes/{id}/lsp/{lsp_id}/open’s response.
LspStartResult: POST /v1/sandboxes/{id}/lsp/start’s response. lsp_id is an opaque handle to pass to the other LSP calls.
LspStopResult: POST /v1/sandboxes/{id}/lsp/{lsp_id}/stop’s response.
McpConnection: A granted outbound-MCP connection (McpConnectionOut).
Memory: One durable, account-scoped memory (POST/GET /v1/memory).
MemoryIngestResponse: Response from Client::ingest_memory and Client::import_memories.
MemoryProfileResponse: Response from Client::memory_profile – stable, long-lived memories separated from recently-touched ones.
MemoryRelation: One edge from Client::memory_relations.
MemoryRelationsResponse: Response from Client::memory_relations (GET /v1/memory/{id}/relations).
MemorySearchHit: A memory returned from Client::recall, with its retrieval score.
MemorySearchResponse: Response from Client::recall (GET /v1/memory/search).
MessageResponse: A generic ack body (e.g. a password-reset request, which returns the same message whether or not the email is registered).
PreviewRevokeResult: POST /v1/sandboxes/{id}/preview/{port}/revoke’s response.
PreviewUrl: A signed, time-limited preview URL (POST /v1/sandboxes/{id}/preview/{port}’s response). The URL carries its own authorization – no API key is needed to use it, only to mint it.
ProcessInfo: One tracked background process (SandboxProcessInfo), as returned by Client::list_processes.
ProcessInputResult: POST /v1/sandboxes/{id}/processes/{process_id}/input’s response.
ProcessListResult: GET /v1/sandboxes/{id}/processes’s response.
ProcessOutputResult: GET /v1/sandboxes/{id}/processes/{process_id}/output’s response.
ProcessStartResult: POST /v1/sandboxes/{id}/processes’s response.
ProcessStopResult: POST /v1/sandboxes/{id}/processes/{process_id}/stop’s response.
RememberOptions: Builder for Client::remember’s optional fields.
RetryConfig: Automatic-retry policy for a Client, set via ClientBuilder::retry.
Sandbox: A sandbox session (SandboxSessionOut/SandboxCreatedResponse). usage is only present on Client::create_sandbox’s response, not on Client::get_sandbox/Client::list_sandboxes.
SandboxConnectInfo: How to reach the sandbox session – an opaque handle for operators with cluster access; external callers operate on the session through this client’s own exec/file-op methods instead (see docs/API.md).
SandboxSession: A Client bound to one sandbox session id – obtained from Client::with_sandbox. Holds a cheap clone of the underlying Client (see Client’s own note on cloning), so it is Clone and can outlive the borrow that produced it.
Secret: A secret’s metadata (SecretOut/SecretCreatedResponse). The raw value is never included here or anywhere else after creation.
StartProcessOptions: Builder for POST /v1/sandboxes/{id}/processes’s optional fields.
StrReplaceOptions: Optional str_replace parameters.
StrReplaceResult: POST /v1/sandboxes/{id}/files/str-replace’s response.
TokenPair: A fresh access_token + refresh_token pair plus the account identity, returned by Client::refresh_token.
UsageSummary: Usage against this account’s fair-use limits, included on Client::create_sandbox’s response.
ViewOptions: Optional view parameters.
ViewResult: POST /v1/sandboxes/{id}/files/view’s response.
Volume: An independent, PVC-backed storage volume (VolumeOut/VolumeAccepted). Client::create_volume’s response only ever populates id/label/ status/created_at – poll Client::get_volume for status to reach "ready" (or "failed") before mounting it via crate::CreateSandboxOptions::volume_mounts.
Webhook: A webhook subscription (WebhookOut/WebhookCreatedResponse). secret is only ever populated on Client::create_webhook’s response – the raw signing secret, shown exactly once; it cannot be retrieved again.
WebhookDelivery: One delivery attempt for a webhook subscription (GET /v1/webhooks/{id}/deliveries’s WebhookDeliveryOut).

Enums§

BoxxkiteError: Everything this crate’s Result<T, BoxxkiteError> can fail with.
ImageBase: Pre-approved base image for Client::create_image. Each variant is itself a separate, boxxkite-maintained hardened image – never a caller-supplied arbitrary base OS.
McpCatalogId: A curated outbound-MCP catalog entry – restricted to boxxkite’s own reviewed allowlist, never a caller-supplied hostname.
ProcessStreamEvent: One event from GET /v1/sandboxes/{id}/processes/{process_id}/stream: an Output per new stdout chunk, then a terminal Exit once the process finishes.
SandboxSize: CPU/memory size preset for a sandbox. Capped per-account by the deployment’s BOXXKITE_MAX_SANDBOX_SIZE – requesting a larger size than the account is allowed returns 429.
WebhookEventType: Event types a webhook subscription can receive. See docs/WEBHOOKS-DESIGN.md for the full event catalog.

Type Aliases§

DesktopStream: The duplex byte stream returned by Client::desktop_takeover. Send and receive raw bytes on it exactly as you would over a local terminal – there is no separate message envelope.
TakeoverStream: The duplex byte stream returned by Client::takeover. Send and receive raw bytes on it exactly as you would over a local terminal – there is no separate message envelope.