boxxkite_client/
lib.rs

1//! Rust client for a **hosted** boxxkite control-plane -- create sandboxes,
2//! run commands, edit files, stream the audit log, take over a session's
3//! shell, over HTTP/WebSocket. Not the `boxxkite` package itself (the
4//! self-hosted Python core that embeds `SandboxManager` against your own
5//! Kubernetes cluster) -- use this to talk to *someone else's* running
6//! control-plane, hosted or self-hosted, over its `/v1/*` REST API. See
7//! `docs/API.md` in the [boxxkite repository](https://github.com/EvAlssment/boxxkite)
8//! for the full route/schema reference this crate wraps.
9//!
10//! # Quickstart
11//!
12//! ```no_run
13//! use boxxkite_client::{Client, CreateSandboxOptions, ExecOptions};
14//!
15//! # async fn example() -> Result<(), boxxkite_client::BoxxkiteError> {
16//! let client = Client::new("https://your-control-plane.example.com", "bxk_live_...")?;
17//!
18//! let sandbox = client
19//!     .create_sandbox(CreateSandboxOptions::new().label("demo"))
20//!     .await?;
21//!
22//! let result = client.exec(&sandbox.id, "python3 -c 'print(1 + 1)'", ExecOptions::new()).await?;
23//! println!("{}", result.stdout); // "2\n"
24//!
25//! client.destroy_sandbox(&sandbox.id).await?;
26//! # Ok(())
27//! # }
28//! ```
29//!
30//! # Error handling
31//!
32//! Every fallible call returns `Result<T, BoxxkiteError>`. A non-2xx
33//! response becomes [`BoxxkiteError::Api`] (`.status()`/`.code()`); a
34//! transport-level failure becomes [`BoxxkiteError::Connection`]. See
35//! [`BoxxkiteError`] for the full set of variants.
36//!
37//! # Scope
38//!
39//! This crate wraps the same `/v1/*` API surface `sdk-python`/`sdk-js`/
40//! `sdk-go` wrap: sandbox lifecycle, exec/file operations, the
41//! `http_request` secrets-broker proxy, background processes
42//! (`start_process`/`list_processes`/`get_process_output`/
43//! `send_process_input`/`stop_process`), the audit log (`get_log`/`watch`),
44//! human/desktop takeover, network-ingress preview URLs
45//! (`create_preview_url`/`revoke_preview_url`), agent-invokable LSP
46//! completions (`lsp_start`/`lsp_open`/`lsp_completion`/`lsp_stop`),
47//! account/usage introspection, dashboard auth-flow helpers (password
48//! reset/verify/resend/refresh/logout), the per-account command allowlist
49//! (`get_allowed_commands`/`set_allowed_commands`/`clear_allowed_commands`),
50//! the [`SandboxSession`]/[`Client::with_sandbox`] convenience helper, and
51//! CRUD for images/volumes/outbound-MCP connections/webhooks/secrets.
52//!
53//! Deliberately **not** included (see `sdk-rust/README.md`'s "Scope"
54//! section for the full disclosure): a LangChain-style tool-factory wrapper
55//! (no dominant Rust agent-framework tool-spec convention exists yet to
56//! mirror), a synchronous/blocking client variant (this crate is
57//! async-first via `tokio`, matching Rust's ecosystem convention), and the
58//! control-plane's filesystem-snapshot routes (a real endpoint, but not
59//! wrapped by `sdk-python`/`sdk-js`/`sdk-go` either as of this writing).
60//!
61//! # Retries
62//!
63//! Automatic retry with exponential backoff + jitter is opt-in via
64//! [`ClientBuilder::max_retries`]/[`ClientBuilder::retry`]; see
65//! [`RetryConfig`] for exactly which failures are retried (and which never
66//! are). Off by default.
67
68mod account;
69mod audit;
70mod client;
71mod desktop;
72mod error;
73mod files;
74mod images;
75mod lsp;
76mod mcp_connections;
77mod memory;
78mod preview;
79mod processes;
80mod sandboxes;
81mod secrets;
82mod session;
83mod takeover;
84mod volumes;
85mod webhooks;
86
87pub use account::{
88    Account, AllowedCommandRule, AllowedCommandsResponse, MessageResponse, TokenPair,
89};
90pub use audit::{AuditLogEntry, AuditLogResponse, GetLogOptions};
91pub use client::{Client, ClientBuilder, RetryConfig};
92pub use desktop::DesktopStream;
93pub use error::BoxxkiteError;
94pub use files::{
95    ExecOptions, ExecResult, FileCreateResult, FileOptions, GlobOptions, GlobResult, GrepOptions,
96    GrepResult, HttpRequestOptions, HttpRequestResult, LsOptions, LsResult, StrReplaceOptions,
97    StrReplaceResult, ViewOptions, ViewResult,
98};
99pub use images::{CreateImageOptions, Image, ImageBase};
100pub use lsp::{LspCompletionResult, LspOpenResult, LspStartResult, LspStopResult};
101pub use mcp_connections::{McpCatalogId, McpConnection};
102pub use memory::{
103    IngestMemoryOptions, ListMemoriesOptions, Memory, MemoryIngestResponse,
104    MemoryProfileResponse, MemoryRelation, MemoryRelationsResponse, MemorySearchHit,
105    MemorySearchResponse, RememberOptions,
106};
107pub use preview::{PreviewRevokeResult, PreviewUrl};
108pub use processes::{
109    ProcessInfo, ProcessInputResult, ProcessListResult, ProcessOutputResult, ProcessStartResult,
110    ProcessStopResult, ProcessStreamEvent, StartProcessOptions,
111};
112pub use sandboxes::{CreateSandboxOptions, Sandbox, SandboxConnectInfo, SandboxSize, UsageSummary};
113pub use secrets::{CreateSecretOptions, Secret};
114pub use session::SandboxSession;
115pub use takeover::TakeoverStream;
116pub use volumes::{CreateVolumeOptions, Volume};
117pub use webhooks::{
118    CreateWebhookOptions, ListWebhookDeliveriesOptions, Webhook, WebhookDelivery, WebhookEventType,
119};
boxxkite_client/lib.rs

boxxkite_client/
lib.rs
