arcbox-core 0.9.0

Core orchestration layer for ArcBox
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

# arcbox-core

Core orchestration runtime for ArcBox.

## Overview

`arcbox-core` provides the host-side runtime that coordinates machine lifecycle,
VM readiness, guest-agent connectivity, and networking/port-forward state.

The main entry point is `Runtime`:

- `Runtime::new(config)` creates the runtime synchronously
- `runtime.init().await` prepares runtime state and assets
- `runtime.ensure_vm_ready().await` ensures the default machine is running

## Key Components

- `Runtime`: top-level orchestrator
- `MachineManager`: named machine lifecycle and metadata
- `VmLifecycleManager`: automatic start/health/recovery for default machine
- `AgentClient`: guest RPC client over vsock
- `NetworkManager`: network lifecycle and IP allocation

## Usage

```rust
use arcbox_core::{Config, Runtime};

let runtime = Runtime::new(Config::default())?;
runtime.init().await?;
let cid = runtime.ensure_vm_ready().await?;
println!("default machine CID: {cid}");
```

## Architecture

```text
arcbox-api / arcbox-cli
          |
          v
      arcbox-core::Runtime
          |
          +-- MachineManager
          +-- VmLifecycleManager
          +-- NetworkManager
          +-- AgentClient accessors
```

## Storage recovery

`Runtime::recover_storage` owns recovery independently of the client connection. Recovery requires a stable System VM lifecycle and retains exclusive storage maintenance through checks and write verification. A client disconnect does not cancel recovery.

The recovery owner retains storage maintenance if the durable hold cannot be written or the recovery worker fails. A retry reuses that reservation. Protected shutdown retains the reservation until the runtime is dropped, so a missing hold cannot permit another System VM boot.

Daemon shutdown closes recovery admission, cancels dedicated guest RPCs, and joins recovery work before stopping the reserved VM. Interrupted or unverified recovery retains its durable hold. Cancellation during write verification does not confirm guest Docker probe cleanup; daemon or VM shutdown can interrupt that cleanup. Successful recovery removes protection only after write verification and Docker probe cleanup both complete.

## License

MIT OR Apache-2.0