Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 3 additions & 3 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ members = [".", "crates/sparkplane-core", "crates/sparkplane-ipc"]
resolver = "3"

[workspace.package]
version = "0.1.5"
version = "0.1.6"
edition = "2024"
rust-version = "1.95"
license = "MIT"
Expand All @@ -22,8 +22,8 @@ tracing = "0.1"
tracing-subscriber = { version = "0.3", default-features = false, features = ["env-filter", "fmt", "json", "registry", "std"] }
metrics = "0.24"
tempfile = "3"
sparkplane-core = { path = "crates/sparkplane-core", version = "=0.1.5" }
sparkplane-ipc = { path = "crates/sparkplane-ipc", version = "=0.1.5" }
sparkplane-core = { path = "crates/sparkplane-core", version = "=0.1.6" }
sparkplane-ipc = { path = "crates/sparkplane-ipc", version = "=0.1.6" }

[package]
name = "sparkplane"
Expand Down
10 changes: 5 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ cargo build --locked --release
./target/release/sparkplane --help
./target/release/sparkplane dgx-spark status --json
./target/release/sparkplane dgx-spark serve qwen3.8:flash-next --dry-run --json
./target/release/sparkplane dgx-spark launch codex --allow-network -- --sandbox workspace-write
./target/release/sparkplane dgx-spark launch codex
```

Use the pinned Rust 1.95.0 toolchain (selected automatically by rustup), a
Expand All @@ -19,10 +19,10 @@ Install the Minisign executable for the encrypted release-signing tests.
The client runs on Linux x86-64/ARM64; the appliance targets Linux ARM64 with
NVIDIA GB10, Docker and the NVIDIA container toolkit already installed.

Enable sandboxed internet access with `launch --allow-network`;
[agent-specific network controls](docs/reference/spark.md#internet-access-for-development)
leave filesystem and approval policies intact. Without the flag, agents retain
their existing permissions.
Agent launches default to `--mode auto`: full filesystem and network access
without action approval prompts. Use `--mode inherit` to keep the agent's own
permission settings. In inherit mode, `--allow-network` grants network access
within a supported sandbox. See [launch permissions](docs/reference/spark.md#internet-access-for-development).

## Architecture

Expand Down
9 changes: 5 additions & 4 deletions docs/how-to/serve-a-model-on-spark.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ healthy, and confirm the OpenAI-compatible gateway path answers.

```bash
sparkplane dgx-spark launch codex --model ornith-1.5:9b
sparkplane dgx-spark launch claude --model ornith-1.5:9b -- --permission-mode plan
sparkplane dgx-spark launch claude --mode inherit --model ornith-1.5:9b -- --permission-mode plan
sparkplane dgx-spark launch opencode --model ornith-1.5:9b
```

Expand All @@ -84,11 +84,12 @@ healthy, and confirm the OpenAI-compatible gateway path answers.
remediation. `launch` does not edit the primary Claude/OpenCode config or
the main Codex config.

Add `--allow-network` when development commands need internet access:
Launches default to full access without approvals (`--mode auto`). To retain
agent sandbox settings while allowing internet access, use inherit mode:

```bash
sparkplane dgx-spark launch codex --allow-network -- --sandbox workspace-write
sparkplane dgx-spark launch claude --allow-network
sparkplane dgx-spark launch codex --mode inherit --allow-network -- --sandbox workspace-write
sparkplane dgx-spark launch claude --mode inherit --allow-network
```

This is a per-launch opt-in, also available as
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -139,7 +139,7 @@ sparkplane dgx-spark token create --name reader --scope models:read \
--scope operations:read --detach --json
sparkplane dgx-spark client-config ornith --client codex
sparkplane dgx-spark launch codex --model ornith-1.5:9b
sparkplane dgx-spark launch claude --model ornith-1.5:9b -- --permission-mode plan
sparkplane dgx-spark launch claude --mode inherit --model ornith-1.5:9b -- --permission-mode plan
sparkplane dgx-spark launch opencode --model ornith-1.5:9b
```

Expand Down
29 changes: 23 additions & 6 deletions docs/reference/spark.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ sparkplane <host> status --json
sparkplane <host> doctor --json
sparkplane <host> qualify --manifest <json> --signature <minisig> (--dry-run | --yes) [--detach] [--json]
sparkplane <host> serve <model> [--name <instance>] [--detach] [--dry-run] [--json]
sparkplane <host> launch <codex|claude|opencode> [--model <model>] [--allow-network] [--config] [--restore] [-y] [-- <agent-args>...]
sparkplane <host> launch <codex|claude|opencode> [--mode auto|inherit] [--model <model>] [--allow-network] [--config] [--restore] [-y] [-- <agent-args>...]
sparkplane <host> ls [--json]
sparkplane <host> ps [--json]
sparkplane <host> logs <instance> [--limit N]
Expand Down Expand Up @@ -255,18 +255,35 @@ catalog, and OpenCode uses process-local `OPENCODE_CONFIG_CONTENT`.

### Internet access for development

Use `--allow-network` (or `SPARKPLANE_LAUNCH_ALLOW_NETWORK=true`) when the
Launches default to `--mode auto` (`SPARKPLANE_LAUNCH_MODE=auto`): full
filesystem and network access without action approval prompts. This applies
to the launched local agent session. It is not saved to agent configuration.

| Agent | Auto mode |
| --- | --- |
| Codex | `approval_policy="never"`, `sandbox_mode="danger-full-access"` |
| Claude Code | `bypassPermissions`, sandbox disabled, bypass onboarding prompt skipped |
| OpenCode | All tool permissions allowed in the generated session configuration |

Use `--mode inherit` to keep the agent's own permissions. Forwarded sandbox,
approval, or Claude settings options require inherit mode to avoid conflicting
policies. Managed agent restrictions still apply. Sparkplane's auto mode is
distinct from an agent's similarly named automatic-review mode.
`--dry-run --json` includes `mode`; `--config` and `--restore` never launch an
agent or change its permission settings.

In inherit mode, use `--allow-network` (or `SPARKPLANE_LAUNCH_ALLOW_NETWORK=true`) when the
agent needs to download dependencies, fetch documentation or use remote APIs:

```bash
sparkplane dgx-spark launch codex --allow-network
sparkplane dgx-spark launch claude --allow-network
sparkplane dgx-spark launch codex --mode inherit --allow-network
sparkplane dgx-spark launch claude --mode inherit --allow-network
```

The grant applies only to this invocation. It is not saved in launch state or
agent configuration, and cannot be combined with `--config` or `--restore`.
`--dry-run --json` reports the requested `allow_network` value without changing
anything. Without the flag, the agent's existing permissions remain unchanged;
anything. In inherit mode without the flag, the agent's existing permissions remain unchanged;
Sparkplane does not impose its own workstation sandbox.

| Agent | Effect of `--allow-network` |
Expand Down Expand Up @@ -305,7 +322,7 @@ appliance's private engine networking. Agent controls are documented in the
```bash
sparkplane dgx-spark serve ornith-1.5:9b --dry-run --json
sparkplane dgx-spark launch codex --model ornith-1.5:9b
sparkplane dgx-spark launch claude --model ornith-1.5:9b -- --permission-mode plan
sparkplane dgx-spark launch claude --mode inherit --model ornith-1.5:9b -- --permission-mode plan
sparkplane dgx-spark launch opencode --model ornith-1.5:9b
sparkplane dgx-spark serve ornith-1.5:9b --name ornith
sparkplane dgx-spark ps --json
Expand Down
39 changes: 38 additions & 1 deletion src/spark/cli.rs
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ pub enum SparkCommand {
Serve(ServeArgs),
/// Configure and launch a local coding agent against a managed Spark model.
#[command(
after_help = "Examples:\n sparkplane dgx-spark launch codex --model ornith-1.5:35b\n sparkplane dgx-spark launch codex --allow-network -- --sandbox workspace-write\n sparkplane dgx-spark launch claude --model ornith-1.5:35b -- --permission-mode plan\n sparkplane dgx-spark launch opencode --config --model ornith-1.5:35b\n sparkplane dgx-spark launch codex --model ornith-1.5:35b --dry-run --json\n\nArguments after `--` are passed directly to the selected local agent without a shell. The Spark administrator credential is never given to the child process.\n\n--allow-network requests invocation-only network access: Codex workspace-write networking, or Claude sandbox domains. OpenCode already has network access; its tool permissions remain unchanged. Filesystem sandboxing and approval policies are not disabled. Managed restrictions still apply. Claude --settings cannot be forwarded with this flag.\n\nEnvironment:\n SPARKPLANE_LAUNCH_MODEL, SPARKPLANE_LAUNCH_ALLOW_NETWORK, SPARKPLANE_LAUNCH_CONFIG, SPARKPLANE_LAUNCH_RESTORE, SPARKPLANE_YES, SPARKPLANE_DRY_RUN, SPARKPLANE_JSON, SPARKPLANE_CONFIG_DIR"
after_help = "Examples:\n sparkplane dgx-spark launch codex --model ornith-1.5:35b\n sparkplane dgx-spark launch codex --mode inherit --allow-network -- --sandbox workspace-write\n sparkplane dgx-spark launch claude --mode inherit --model ornith-1.5:35b -- --permission-mode plan\n sparkplane dgx-spark launch opencode --config --model ornith-1.5:35b\n sparkplane dgx-spark launch codex --model ornith-1.5:35b --dry-run --json\n\nArguments after `--` are passed directly to the selected local agent without a shell. The Spark administrator credential is never given to the child process.\n\nAuto mode (default) gives agents full access without action approvals. Use --mode inherit to retain agent permissions. --allow-network requests invocation-only network access: Codex workspace-write networking, or Claude sandbox domains. OpenCode already has network access; its tool permissions remain unchanged. Filesystem sandboxing and approval policies are not disabled. Managed restrictions still apply. Claude --settings cannot be forwarded with this flag.\n\nEnvironment:\n SPARKPLANE_LAUNCH_MODE, SPARKPLANE_LAUNCH_MODEL, SPARKPLANE_LAUNCH_ALLOW_NETWORK, SPARKPLANE_LAUNCH_CONFIG, SPARKPLANE_LAUNCH_RESTORE, SPARKPLANE_YES, SPARKPLANE_DRY_RUN, SPARKPLANE_JSON, SPARKPLANE_CONFIG_DIR"
)]
Launch(LaunchArgs),
/// List currently active managed model processes.
Expand Down Expand Up @@ -427,6 +427,9 @@ impl LaunchIntegration {
pub struct LaunchArgs {
#[arg(value_enum)]
pub integration: LaunchIntegration,
/// Agent permissions: auto grants full access without action approvals; inherit keeps agent settings.
#[arg(long, default_value = "auto", value_parser = ["auto", "inherit"], env = "SPARKPLANE_LAUNCH_MODE")]
pub mode: String,
/// Allow this agent session's sandbox network access; keep filesystem and approval policies.
#[arg(long, env = "SPARKPLANE_LAUNCH_ALLOW_NETWORK", conflicts_with_all = ["configure", "restore"])]
pub allow_network: bool,
Expand Down Expand Up @@ -2737,6 +2740,40 @@ mod tests {
};
assert_eq!(args.extra_args, ["--sandbox", "workspace-write"]);
assert!(args.allow_network);
assert_eq!(args.mode, "auto");
}

#[test]
fn launch_permission_mode_accepts_inherit_and_rejects_unknown() {
#[derive(clap::Parser)]
struct TestCli {
#[command(flatten)]
spark: super::SparkCli,
}
let parsed = TestCli::try_parse_from([
"sparkplane",
"dgx-spark",
"launch",
"codex",
"--mode",
"inherit",
])
.unwrap();
let super::SparkCommand::Launch(args) = parsed.spark.command else {
panic!("expected launch")
};
assert_eq!(args.mode, "inherit");
assert!(
TestCli::try_parse_from([
"sparkplane",
"dgx-spark",
"launch",
"codex",
"--mode",
"unknown"
])
.is_err()
);
}

#[test]
Expand Down
Loading
Loading