ArcBox

The arcbox-transport crate provides transport abstractions for communication between an ArcBox host and guest. It offers implementations for both Unix domain sockets and virtio-vsock endpoints, allowing for transport-agnostic code via the Transport and TransportListener traits.

Available transport types:

• UnixTransport: Uses Unix domain sockets.
• VsockTransport: Uses virtio-vsock endpoints via VsockAddr.
• VsockStream: Provides raw async byte streams for callers who already own a connected file descriptor (fd).

use arcbox_transport::{Transport, UnixTransport, VsockTransport};
use arcbox_transport::vsock::VsockAddr;
use bytes::Bytes;

// Example: Using Unix Domain Sockets
let mut unix = UnixTransport::new("/var/run/arcbox.sock");
unix.connect().await?;
unix.send(Bytes::from("hello")).await?;

// Example: Using Vsock
let mut vsock = VsockTransport::new(VsockAddr::new(3, 1024));
vsock.connect().await?;
vsock.send(Bytes::from("ping")).await?;

The Python SDK is currently in development (Phases 2a and 2b of CORE-58) and supports both synchronous and asynchronous surfaces. The following features are currently shipped:

Sandbox Management

• Sandbox.create, connect, list, kill, pause, info: Note that pause/resume are handled daemon-side; data-plane calls will automatically resume a paused sandbox.
• sandbox.events(): Provides typed lifecycle events (sync reads are blocking; mid-stream drops raise ConnectionLostError).
• sandbox.set_lifecycle(): Tri-state management (UNCHANGED to omit, None to restore default, or a specific value to replace).
• sandbox.checkpoint(): Pauses and snapshots the sandbox, returning a Snapshot catalog row.
• ArcBox.restore(snapshot_id): Creates a new READY sandbox from a snapshot. Supports fresh_network=True for concurrent restores. Includes list_snapshots (auto-paginating) and delete_snapshot.
• arcbox.capabilities(): Performs a daemon handshake to retrieve version, protocol, features, and nested virtualization support (cached per client).

Command Execution

• commands.run: Executes commands. Returns a foreground result and a background CommandHandle. Supports stdin as str|bytes (write-then-close) or True (keep open), and pty=PtySize(cols, rows).
• CommandHandle: Provides streamed output with transparent offset-resume (raises ConnectionLostError on persistent failure), wait_for_exit, kill, write_stdin, close_stdin, stdin_status, and resize.
• handle.wait_for_log(pattern): Waits for the first log line matching a substring or compiled regex. Uses SDK-side replayed offset-addressed output. Raises TimeoutError on deadline expiration.
• commands.get(id) / commands.list(): Re-attach a handle via execution ID or list running/exited executions as CommandInfo summaries.

File System

• files: Supports whole-file read/write and path verbs: stat, list, mkdir (with mkdir -p semantics), remove, and move. Uses a frozen FileStat dataclass. Paths accept str or PurePosixPath.
• files.watch(path): Provides a typed FsEvent stream via AsyncFileWatch/FileWatch context managers. Renames are paired and keepalives are filtered. Mid-stream drops raise ConnectionLostError (events cannot be replayed).

Networking

• ports.wait_for_port(port): Waits for a guest-side listen-table entry (no client polling). Raises TimeoutError on expiry (daemon default 30s, cap 600s).
• ports.expose(port) / unexpose / list: Publishes a guest port on the host loopback (TCP/UDP). list reads the daemon's authoritative live listener table.

Templates

• Template.build(name, ...): Builds a catalog template from a single source (image= local Docker ref, dockerfile= inline content, or snapshot= checkpoint promotion). Supports ready_probe_port, ready_probe_command, and prewarm=True (boot-to-READY warm snapshot). Builds block until complete.
• Template.get, list, delete_reference: Resolves name[:version] (bare name is newest published; otherwise draft). Supports auto-paginating lists.
• instance.publish(version) / delete(): publish freezes a draft immutably; delete removes it.
• create(template=Template | "name[:version]"): Creates a sandbox. A Template instance pins its exact reference. Overriding vcpus or memory_mib replaces limits wholesale; no_default_cmd or no_default_env suppresses inherited values.

The arcbox-container crate provides the foundational data models and execution primitives for managing containers within the ArcBox ecosystem. It is designed to be used by higher-level services rather than acting as a standalone container manager.

Key components include:

• Container Configuration: Use ContainerConfig to define parameters for container creation.
• Container Identity & Lifecycle: Use Container and ContainerState to track container identity and its current lifecycle status.
• Execution Orchestration: Use ExecManager and related types (like ExecInstance, ExecConfig, and ExecId) to implement docker exec-style workflows.
• Agent-backed Execution: Supports optional execution operations via ExecAgentConnection.

use arcbox_container::{Container, ContainerConfig, ContainerState};

let config = ContainerConfig {
    image: "alpine:latest".to_string(),
    cmd: vec!["sh".to_string()],
    ..Default::default()
};

let container = Container::with_config("demo", config);
assert_eq!(container.state, ContainerState::Created);

splicetcp is a userspace TCP-termination and splice bridge used in ArcBox. It acts as a frame plane between an L2/L3 packet source and an egress dialer.

Key Characteristics:

• Not a full TCP/IP stack: The guest kernel maintains ownership of the guest TCP state. splicetcp only manages outbound SYNs, synthesizes the handshake, mirrors minimal sequence/ack state, and splices bytes between guest frames and host sockets.
• Flow Promotion: It classifies Ethernet frames and promotes established TCP flows to a "fast path" backed by a real host TcpStream.
• Core Components:
  • classifier::FrameClassifier: A pure Ethernet-frame demultiplexer.
  • tcp_bridge::TcpBridge: Handles SYN gating, handshake synthesis, and the fast path.
  • egress::EgressResolver: The policy/dial seam used to map flows to outbound connections.
  • direct_rx::{ConnSink, PromotedConn}: Allows callers to take ownership of host→guest reads.
  • shim: Adapts L3 links (like utun) to the L2 classifier by adding/removing synthetic Ethernet headers.