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.4"
version = "0.1.5"
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.4" }
sparkplane-ipc = { path = "crates/sparkplane-ipc", version = "=0.1.4" }
sparkplane-core = { path = "crates/sparkplane-core", version = "=0.1.5" }
sparkplane-ipc = { path = "crates/sparkplane-ipc", version = "=0.1.5" }

[package]
name = "sparkplane"
Expand Down
6 changes: 6 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +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
```

Use the pinned Rust 1.95.0 toolchain (selected automatically by rustup), a
Expand All @@ -18,6 +19,11 @@ 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.

## Architecture

The unprivileged HTTPS agent owns state and protocol translation. A separate,
Expand Down
13 changes: 13 additions & 0 deletions docs/how-to/serve-a-model-on-spark.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,19 @@ 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:

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

This is a per-launch opt-in, also available as
`SPARKPLANE_LAUNCH_ALLOW_NETWORK=true`; it does not disable filesystem
sandboxing or change approval policy. OpenCode already has network access,
so its existing tool permissions are left alone. See
[network controls and limitations](../reference/spark.md#internet-access-for-development).

7. Stop when you are done. An already-absent instance is an idempotent success:

```bash
Expand Down
49 changes: 48 additions & 1 deletion 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>] [--config] [--restore] [-y] [-- <agent-args>...]
sparkplane <host> launch <codex|claude|opencode> [--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 @@ -253,6 +253,53 @@ inference-only token and pinned CA, never the administrator credential. Claude
uses the native Anthropic route, Codex uses a Sparkplane-owned Responses profile and
catalog, and OpenCode uses process-local `OPENCODE_CONFIG_CONTENT`.

### Internet access for development

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
```

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;
Sparkplane does not impose its own workstation sandbox.

| Agent | Effect of `--allow-network` |
| --- | --- |
| Codex | Sets `sandbox_workspace_write.network_access=true`. Filesystem sandbox mode and approval policy are unchanged. |
| Claude Code | Passes session-only `sandbox.network.allowedDomains=["*"]` through `--settings`. Filesystem restrictions and explicit domain denials remain in force. |
| OpenCode | No extra permission override: OpenCode already has direct network access. Existing shell, web-fetch and other tool approval rules remain in force. |

For Codex, the network setting applies to `workspace-write` sessions. If the
workspace is not trusted or Codex is configured read-only, explicitly select
the development sandbox with `-- --sandbox workspace-write`. Named permission
profiles, managed organization restrictions and explicit forwarded overrides
can impose different policies; this flag does not bypass them. It does not
enable the hosted Responses web-search tool, which the model gateway does not
provide. Commands such as `curl`, package managers and Git can use the network.

Do not combine Claude's forwarded `--settings` with `--allow-network`: the
launcher rejects that ambiguous combination before contacting the appliance.
Use normal Claude settings files for other settings, or omit the flag and pass
your complete session settings yourself.

Codex receives its pinned Spark CA through `CODEX_CA_CERTIFICATE`, not a
launcher-supplied `SSL_CERT_FILE`. This keeps private inference TLS verification
separate from the public/system CA trust used by development subprocesses.
Existing user-supplied certificate and proxy settings are not erased.

Internet access lets subprocesses transmit data they can read; opt in only for
trusted work. This option changes neither the inference-token scope nor the
appliance's private engine networking. Agent controls are documented in the
[Codex sandbox configuration](https://developers.openai.com/codex/security),
[Claude sandbox guide](https://code.claude.com/docs/en/sandboxing), and
[OpenCode permissions reference](https://opencode.ai/docs/permissions/).

## Examples

```bash
Expand Down
79 changes: 79 additions & 0 deletions specs/bugs/BUG-20260922-0144.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
# BUG-20260922-0144: Coding-agent launches cannot reach the internet

## Summary

Sparkplane needs an explicit per-launch internet opt-in without disabling the
coding agent's filesystem sandbox or weakening the appliance's private network.

## Reproduction

On Codex 0.155.1, run from a development checkout:

```sh
codex sandbox -c 'sandbox_mode="workspace-write"' -- \
curl --fail --max-time 10 https://example.com
```

The command fails with `Could not resolve host: example.com`. Adding
`-c sandbox_workspace_write.network_access=true` succeeds. With Sparkplane's
inherited `SSL_CERT_FILE` pointing at the Spark CA, the network-enabled command
instead fails with `unable to get local issuer certificate`. Using
`CODEX_CA_CERTIFICATE` for that CA succeeds without replacing curl's trust store.

## Expected

`sparkplane dgx-spark launch codex --allow-network` permits network access for
workspace-sandboxed development commands. Default launch permissions are
unchanged. The option also configures Claude's sandbox domain allowlist;
OpenCode already has direct network access and retains its tool permissions.

## Actual

The launcher has no network opt-in and exports a process-wide private trust store.

## Root cause

The launcher directly executes local agents, which own their sandbox policy.
Codex disables network access in its workspace sandbox by default. Additionally,
exporting `SSL_CERT_FILE` to the entire child process tree replaces public CA
trust for development tools. Neither failure is in the GPU engine network.

## Fix

Add invocation-only `--allow-network` / `SPARKPLANE_LAUNCH_ALLOW_NETWORK`.
Use each agent's narrow network setting, leave filesystem and approval policy
alone, and retain managed policy restrictions. Reject configuration-only and
restore combinations rather than silently persisting an access grant. Use
`CODEX_CA_CERTIFICATE` for Codex-specific private CA trust.

## Traceability

- CLI regressions: `tests/standalone_cli.rs`.
- Adapter and CA regressions: `src/spark/launch.rs`, `src/spark/client.rs`.
- Manual verification: the Codex sandbox commands above (no model invocation).

## Verification

- CLI tests cover the flag, environment equivalent, forwarded arguments,
conflicting Claude settings, and rejection of persistent/restore grants.
- Adapter tests cover default permissions, Codex/Claude network-only overrides,
unchanged OpenCode permissions, and Codex-specific CA scoping.
- The optional native sandbox regression was executed successfully on Codex
0.155.1: default DNS is blocked, opted-in public HTTPS returns 200, and attempted
writes outside the workspace fail in both cases.

```sh
cargo test --locked --lib native_codex_network_opt_in_keeps_filesystem_confinement -- --ignored
make lint
make test
make test-client
make audit
```

The live launch dry-run reused the healthy `qwen38-vllm` instance and reported
`allow_network: true`; the environment-variable form was checked separately.
The production launch path also delivered the scoped CA to a Codex sandbox
diagnostic: HTTPS returned 200 and the workstation configuration remained
read-only. Codex's `sandbox` diagnostic reads subcommand-local configuration,
so this particular probe repeats the network override after `sandbox`; ordinary
TUI/exec launches receive the root-level override directly.
7 changes: 6 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 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\nEnvironment:\n SPARKPLANE_LAUNCH_MODEL, 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 --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"
)]
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,
/// 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,
#[arg(long, env = "SPARKPLANE_LAUNCH_MODEL")]
pub model: Option<String>,
#[arg(long = "config", env = "SPARKPLANE_LAUNCH_CONFIG")]
Expand Down Expand Up @@ -2723,6 +2726,7 @@ mod tests {
"codex",
"--model",
"ornith-1.5:9b",
"--allow-network",
"--",
"--sandbox",
"workspace-write",
Expand All @@ -2732,6 +2736,7 @@ mod tests {
panic!("launch command should parse");
};
assert_eq!(args.extra_args, ["--sandbox", "workspace-write"]);
assert!(args.allow_network);
}

#[test]
Expand Down
3 changes: 2 additions & 1 deletion src/spark/client.rs
Original file line number Diff line number Diff line change
Expand Up @@ -183,7 +183,7 @@ fn build_codex_config(
base_url,
env_key: ENV_KEY.into(),
wire_api: "responses".into(),
ca_env_key: "SSL_CERT_FILE".into(),
ca_env_key: "CODEX_CA_CERTIFICATE".into(),
ca_path: config_dir.join("spark").join(format!("{host}.ca.pem")),
config_path: "$CODEX_HOME/config.toml (defaults to ~/.codex/config.toml)".into(),
toml,
Expand Down Expand Up @@ -1037,6 +1037,7 @@ mod tests {
let parsed: toml::Value = toml::from_str(&config.toml).unwrap();
assert_eq!(parsed["web_search"].as_str(), Some("disabled"));
assert_eq!(config.base_url, "https://10.1.30.143:9843/openai/ornith/v1");
assert_eq!(config.ca_env_key, "CODEX_CA_CERTIFICATE");
}

#[test]
Expand Down
Loading
Loading