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
4 changes: 4 additions & 0 deletions oxa/docs/pages/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -120,6 +120,8 @@ $ oxa share key list

`oxa share serve` starts a foreground listener after the owner enables the native local engine and selects one or more local aliases with `--model`. It binds to the Tailscale interface by default and prints its `/v1` base URL. Set `--port` to use a fixed port, or `--bind 127.0.0.1` to put the listener behind Tailscale Serve. `--same-owner` requires the connecting peer to pass the Tailscale owner check. Clients send a guest bearer and can list models or stream text chat. Ctrl+C stops admission and joins active cleanup.

Start an interactive owner session with `oxa --share-model ALIAS` to share that session's native engine. A queued owner request goes before a waiting guest, and an active guest keeps its lease through cleanup. The startup notice gives the guest API address. Exiting the owner session drains the listener.

`oxa update --self`, `--all` and `--models` report that they are not supported: oxa does not update itself and does not refresh model catalogues. Update oxa by installing a new build.

`oxa report-issue draft` takes `--title <text>` (required), and the notes either inline with `--notes <text>` or from a file with `--notes-file <path>` (relative paths are taken from the current directory). It writes the draft under `issue-drafts/` in the agent directory and prints its path; it posts nothing. `oxa report-issue submit <draft>` posts it after you type `yes`.
Expand Down Expand Up @@ -236,6 +238,8 @@ See [tools.md](tools.md) for the tool names.
| `--yolo` | permission mode yolo, full access: no prompts, bash runs without the sandbox, no deny-list or protected paths for file tools ([security.md](security.md#standard-auto-and-yolo)) |
| `--approve`, `-a` | trust the project's configuration and resources for this run |
| `--no-approve`, `-na` | ignore the project's configuration and resources for this run |
| `--share-model <alias>` | share one native local model during the interactive owner session in a build with the `share` feature, repeat to select more aliases |
| `--share-bind <address>` | set an explicit bind address for `--share-model`. Sharing uses the Tailscale interface by default |
| `--offline` | offline mode: oxa's own non-local connections are refused, bash has no network, `web_search` is off, and `!cmd` and stdio MCP servers run without network. What it does not cover is in [security.md](security.md#offline-mode) |

See [security.md](security.md).
Expand Down
29 changes: 29 additions & 0 deletions oxa/oxa-cli/src/args.rs
Original file line number Diff line number Diff line change
Expand Up @@ -216,6 +216,12 @@ pub struct Args {
pub version: bool,
/// The hard offline switch (see the help text).
pub offline: bool,
/// Explicitly expose only these native local aliases for the current owner session.
#[cfg(feature = "share")]
pub share_models: Vec<String>,
/// Override the Tailscale bind for this owner session.
#[cfg(feature = "share")]
pub share_bind: Option<std::net::IpAddr>,
/// Flags registered by extensions (`registerFlag`): name -> value.
pub extension_flags: Vec<(String, Value)>,
/// Unknown `--long` flags seen before the extension flags are known (resolved by the
Expand Down Expand Up @@ -454,6 +460,10 @@ const OPTIONS: &[(&str, &str)] = &[
"Permission mode: standard, auto, yolo, plan (or workspace, ask); default: permissions.defaultMode, else auto",
),
("--verbose", "Show verbose startup information"),
#[cfg(feature = "share")]
("--share-model <alias>", "Share one native local model during the interactive owner session (repeatable)"),
#[cfg(feature = "share")]
("--share-bind <address>", "Explicitly bind interactive guest sharing to this address"),
(
"--offline",
"Hard offline switch: non-local connections refused, bash has no network, web_search off",
Expand Down Expand Up @@ -920,6 +930,25 @@ fn parse_flag(
no_value(inline, flag)?;
a.approve = Some(false);
}
#[cfg(feature = "share")]
"--share-model" => {
let alias = value(argv, i, inline, flag, "a native local alias")?;
if alias.is_empty() || a.share_models.len() >= 64 || a.share_models.contains(&alias) {
return Err(usage(
"specify between one and 64 distinct native local sharing aliases",
));
}
a.share_models.push(alias);
}
#[cfg(feature = "share")]
"--share-bind" => {
let address = value(argv, i, inline, flag, "an IP address")?;
a.share_bind = Some(
address
.parse()
.map_err(|_| usage("invalid --share-bind address"))?,
);
}
"--offline" => {
no_value(inline, flag)?;
a.offline = true;
Expand Down
69 changes: 61 additions & 8 deletions oxa/oxa-cli/src/dispatch.rs
Original file line number Diff line number Diff line change
Expand Up @@ -156,6 +156,31 @@ pub fn run(argv: &[String], env: &Env, io: Stdio) -> i32 {

crate::netguard::install(a.offline, env, a.session_dir.as_deref(), &cwd);

#[cfg(feature = "share")]
if !a.share_models.is_empty() || a.share_bind.is_some() {
let refusal = if crate::share_cmd::is_agent(env) {
Some(OxaError::new(
codes::INVALID,
"Guest serving requires the owner outside an agent tool",
))
} else if a.share_models.is_empty() {
Some(OxaError::new(
codes::USAGE,
"--share-bind requires --share-model ALIAS",
))
} else if !loads_extensions || choose_mode(&a, stdin_is_tty, stdout_is_tty) != RunMode::Interactive {
Some(OxaError::new(
codes::USAGE,
"--share-model requires an interactive owner session",
))
} else {
oxa_proto::check_online("starting the LAN sharing listener").err()
};
if let Some(error) = refusal {
return report(&mut *stderr, &error);
}
}

if let Some(sub) = a.subcommand.clone() {
let dirs = match dirs_from_env(env, None) {
Ok(d) => d,
Expand Down Expand Up @@ -185,14 +210,7 @@ pub fn run(argv: &[String], env: &Env, io: Stdio) -> i32 {
#[cfg(feature = "share")]
Subcommand::Share(words) => {
let serve = words.first().is_some_and(|word| word == "serve");
// Env::get treats empty values as unset; owner-command policy
// refuses marker presence, including an empty value.
if env.pairs().iter().any(|(name, _)| {
matches!(
name.as_str(),
"OXA_CODING_AGENT" | "AI_AGENT" | "OXA_SUBAGENT_DEPTH"
)
}) {
if crate::share_cmd::is_agent(env) {
return report(
&mut *stderr,
&OxaError::new(
Expand Down Expand Up @@ -439,6 +457,8 @@ pub fn run(argv: &[String], env: &Env, io: Stdio) -> i32 {
/// Everything decided before a session is opened.
struct Prep {
built: Built,
#[cfg(feature = "share")]
sharing: Option<crate::share_cmd::Prepared>,
open: Open,
session_id: Option<String>,
notices: Vec<(Level, String)>,
Expand Down Expand Up @@ -746,12 +766,29 @@ fn prepare(
settings.string("defaultModel")
}
});
#[cfg(feature = "share")]
let sharing = (!a.share_models.is_empty())
.then(|| {
crate::share_cmd::prepare_session(
&user_settings,
&settings,
dirs,
a.share_models.clone(),
a.share_bind,
)
})
.transpose()?;
#[cfg(feature = "share")]
let shared_local = sharing.as_ref().map(|prepared| prepared.local.clone());
#[cfg(not(feature = "share"))]
let shared_local = None;
let engine = child.wrap(crate::in_process::select_observed(
&user_settings,
&settings,
dirs,
requested_model.as_deref(),
(!child.nested() && mode != RunMode::Rpc).then(|| cloud_diagnostics.clone()),
shared_local,
|| engine_with_settings(&endpoint, &settings),
)?);

Expand Down Expand Up @@ -975,6 +1012,8 @@ fn prepare(
};
Ok(Prep {
built,
#[cfg(feature = "share")]
sharing,
open,
session_id,
notices,
Expand Down Expand Up @@ -1495,6 +1534,8 @@ fn run_tui(a: &Args, env: &Env, dirs: &Dirs, cwd: &Path, prep: Prep, stderr: &mu

let Prep {
built,
#[cfg(feature = "share")]
sharing,
open,
session_id,
mut notices,
Expand All @@ -1506,6 +1547,18 @@ fn run_tui(a: &Args, env: &Env, dirs: &Dirs, cwd: &Path, prep: Prep, stderr: &mu
Ok(s) => s,
Err(e) => return report(stderr, &e),
};
#[cfg(feature = "share")]
let _guest_listener = match sharing.map(crate::share_cmd::Prepared::start).transpose() {
Ok(Some((running, address))) => {
notices.push((
Level::Info,
format!("Guest OpenAI API listening at http://{address}/v1"),
));
Some(running)
}
Ok(None) => None,
Err(error) => return report(stderr, &error),
};
notices.extend(startup_notices(&built, &session));
let yolo = built.yolo.clone();
// Its diagnostics are among the startup notices (`prepare`).
Expand Down
52 changes: 33 additions & 19 deletions oxa/oxa-cli/src/in_process.rs
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,29 @@ pub(crate) fn select(
requested: Option<&str>,
http: impl FnOnce() -> Result<Arc<dyn Engine>, OxaError>,
) -> Result<Arc<dyn Engine>, OxaError> {
select_observed(user, effective, dirs, requested, None, http)
select_observed(user, effective, dirs, requested, None, None, http)
}

/// Native launch configuration is user-only. Stream policy follows the effective session.
pub(crate) fn local_engine_settings<'a>(
user: &'a Settings,
effective: &Settings,
) -> (Option<&'a Value>, oxa_engine::StreamOpts) {
let stream = oxa_engine::StreamOpts {
silence_limit_ms: crate::dispatch::stream_silence_timeout(effective)
.unwrap_or(365 * 24 * 3600 * 1000),
..oxa_engine::StreamOpts::default()
};
(user.get("oxa.local"), stream)
}

#[test]
fn shared_local_engine_uses_effective_stream_timeout() {
let user_values = serde_json::json!({"httpIdleTimeoutMs": 1700});
let user = Settings::from_values(user_values.clone(), serde_json::json!({}));
let effective = Settings::from_values(user_values, serde_json::json!({"httpIdleTimeoutMs": 2400}));
let (_, stream) = local_engine_settings(&user, &effective);
assert_eq!(stream.silence_limit_ms, 2400);
}

pub(crate) fn select_observed(
Expand All @@ -102,8 +124,16 @@ pub(crate) fn select_observed(
dirs: &Dirs,
requested: Option<&str>,
diagnostics: Option<oxc_gateway::diagnostics::Diagnostics>,
shared_local: Option<Arc<oxc_local::native::LocalEngine>>,
http: impl FnOnce() -> Result<Arc<dyn Engine>, OxaError>,
) -> Result<Arc<dyn Engine>, OxaError> {
let local_engine = || match shared_local {
Some(engine) => Ok(engine as Arc<dyn Engine>),
None => {
let (launch, stream) = local_engine_settings(user, effective);
oxc_local::configured_engine(launch, dirs.agent_dir.join("local-engine"), stream)
}
};
if user.bool(oxc_local::LOCAL_SETTING, false) && user.bool(SETTING, false) {
let aliases = |path| {
user.get(path)
Expand All @@ -112,15 +142,7 @@ pub(crate) fn select_observed(
.unwrap_or_default()
};
return routing::Routed {
local: oxc_local::configured_engine(
user.get("oxa.local"),
dirs.agent_dir.join("local-engine"),
oxa_engine::StreamOpts {
silence_limit_ms: crate::dispatch::stream_silence_timeout(effective)
.unwrap_or(365 * 24 * 3600 * 1000),
..oxa_engine::StreamOpts::default()
},
),
local: local_engine(),
cloud: if oxa_proto::offline() {
Err(oxa_proto::offline_error("the in-process cloud gateway"))
} else {
Expand All @@ -134,15 +156,7 @@ pub(crate) fn select_observed(
.into_engine(requested);
}
if user.bool(oxc_local::LOCAL_SETTING, false) {
return oxc_local::configured_engine(
user.get("oxa.local"),
dirs.agent_dir.join("local-engine"),
oxa_engine::StreamOpts {
silence_limit_ms: crate::dispatch::stream_silence_timeout(effective)
.unwrap_or(365 * 24 * 3600 * 1000),
..oxa_engine::StreamOpts::default()
},
);
return local_engine();
}
if !user.bool(SETTING, false) {
return http();
Expand Down
Loading
Loading