boxlite-ai / boxlite-ai/boxlite

Proposal: Semantics-level runtime ReadOnly mode for CLI commands

Open
#258 3 comments 2 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
2.3k
Forks
179
Avg merge
23h 25m
Merged PRs (30d)
121

Description

I’m still learning the runtime internals, so this is a **semantics-level** proposal for discussion (**NOT** an implementation proposal yet).

## Why this might help

- Better concurrency expectations for CLI usage.

## Current situation (as I understand it)

Right now, BoxLite is no daemon required. Multiple `boxlite` CLI processes against the same `BOXLITE_HOME` do not compose well.

Each CLI command creates its own runtime instance, and that runtime takes an exclusive home-level lock for the process lifetime. As a result, a second command started at the same time typically fails immediately instead of waiting or coexisting.

**user case**: I'm building an Electron App to test the boundaries of BoxLite. e.g. The Electron App process is holding the `runtime lock`, I wanna execute `boxlite list -all` and `boxlite images` to check the status of images and boxes.

## Proposal (semantics only)

Introduce two runtime access modes at the command-semantics level:

- `RuntimeMode::ReadOnly`
- `RuntimeMode::ReadWrite`

Initial command grouping proposal:

- `list/images/info` -> `RuntimeMode::ReadOnly`
- `exec/run/create/start/stop/rm/pull` -> `RuntimeMode::ReadWrite`

## Expected semantics

- `ReadOnly` commands should be safe to run alongside `ReadWrite` operations when possible.
- `ReadWrite` commands keep full mutation authority and correctness guarantees.

This proposal only defines command intent/semantics, **NOT** internal locking/mechanism.

Would love to hear your thoughts on this.

Contributor guide

Open the contributing guide

Research direction

No files, tests, or concrete entry points are named. Start by reviewing the CLI command grouping and runtime lock behavior described in the issue, then map those commands to the runtime access semantics. Done means the project has agreed on the ReadOnly and ReadWrite command semantics before implementation begins.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
backend, cli
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.