Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(cli): support tenant identity defaults and overrides (#1019)

Jiahui Zhouc5033b0bcdd5
diff --git a/crates/ov_cli/README.md b/crates/ov_cli/README.md
index 133e4120c..a8382b55b 100644
--- a/crates/ov_cli/README.md
+++ b/crates/ov_cli/README.md
@@ -25,10 +25,15 @@ Create `~/.openviking/ovcli.conf`:
```json
{
"url": "http://localhost:1933",
- "api_key": "your-api-key"
+ "api_key": "your-api-key",
+ "account": "acme",
+ "user": "alice",
+ "agent_id": "assistant-1"
}
```
+`account` and `user` are optional with a regular user key because the server can derive them from the key. They are recommended when you use `trusted` auth mode or a root key against tenant-scoped APIs.
+
## Quick Start
```bash
@@ -126,6 +131,9 @@ ov find "API authentication" --threshold 0.7 --limit 5
# Recursive list
ov ls viking://resources --recursive
+# Temporarily override identity from CLI flags
+ov --account acme --user alice --agent-id assistant-2 ls viking://
+
# Glob search
ov glob "**/*.md" --uri viking://resources
diff --git a/crates/ov_cli/src/client.rs b/crates/ov_cli/src/client.rs
index 2fa6467f9..5f9c670bf 100644
--- a/crates/ov_cli/src/client.rs
+++ b/crates/ov_cli/src/client.rs
@@ -4,8 +4,8 @@ use serde_json::Value;
use std::fs::File;
use std::path::Path;
use tempfile::NamedTempFile;
-use zip::write::FileOptions;
use zip::CompressionMethod;
+use zip::write::FileOptions;
use crate::error::{Error, Result};
@@ -15,6 +15,8 @@ pub struct HttpClient {
http: ReqwestClient,
base_url: String,
api_key: Option<String>,
+ account: Option<String>,
+ user: Option<String>,
agent_id: Option<String>,
}
@@ -24,6 +26,8 @@ impl HttpClient {
base_url: impl Into<String>,
api_key: Option<String>,
agent_id: Option<String>,
+ account: Option<String>,
+ user: Option<String>,
timeout_secs: f64,
) -> Self {
let http = ReqwestClient::builder()
@@ -35,6 +39,8 @@ impl HttpClient {
http,
base_url: base_url.into().trim_end_matches('/').to_string(),
api_key,
+ account,
+ user,
agent_id,
}
}
@@ -51,7 +57,8 @@ impl HttpClient {
let temp_file = NamedTempFile::new()?;
let file = File::create(temp_file.path())?;
let mut zip = zip::ZipWriter::new(file);
- let options: FileOptions<'_, ()> = FileOptions::default().compression_method(CompressionMethod::Deflated);
+ let options: FileOptions<'_, ()> =
+ FileOptions::default().compression_method(CompressionMethod::Deflated);
let walkdir = walkdir::WalkDir::new(dir_path);
for entry in walkdir.into_iter().filter_map(|e| e.ok()) {
@@ -78,14 +85,13 @@ impl HttpClient {
// Read file content
let file_content = tokio::fs::read(file_path).await?;
-
+
// Create multipart form
- let part = reqwest::multipart::Part::bytes(file_content)
- .file_name(file_name.to_string());
-
- let part = part.mime_str("application/octet-stream").map_err(|e| {
- Error::Network(format!("Failed to set mime type: {}", e))
- })?;
+ let part = reqwest::multipart::Part::bytes(file_content).file_name(file_name.to_string());
+
+ let part = part
+ .mime_str("application/octet-stream")
+ .map_err(|e| Error::Network(format!("Failed to set mime type: {}", e)))?;
let form = reqwest::multipart::Form::new().part("file", part);
@@ -126,6 +132,16 @@ impl HttpClient {
headers.insert("X-OpenViking-Agent", value);
}
}
+ if let Some(account) = &self.account {
+ if let Ok(value) = reqwest::header::HeaderValue::from_str(account) {
+ headers.insert("X-OpenViking-Account", value);
+ }
+ }
+ if let Some(user) = &self.user {
+ if let Ok(value) = reqwest::header::HeaderValue::from_str(user) {
+ headers.insert("X-OpenViking-User", value);
+ }
+ }
headers
}
@@ -224,10 +240,7 @@ impl HttpClient {
self.handle_response(response).await
}
- async fn handle_response<T: DeserializeOwned>(
- &self,
- response: reqwest::Response,
- ) -> Result<T> {
+ async fn handle_response<T: DeserializeOwned>(&self, response: reqwest::Response) -> Result<T> {
let status = response.status();
// Handle empty response (204 No Content, etc.)
@@ -248,7 +261,11 @@ impl HttpClient {
.and_then(|e| e.get("message"))
.and_then(|m| m.as_str())
.map(|s| s.to_string())
- .or_else(|| json.get("detail").and_then(|d| d.as_str()).map(|s| s.to_string()))
+ .or_else(|| {
+ json.get("detail")
+ .and_then(|d| d.as_str())
+ .map(|s| s.to_string())
+ })
.unwrap_or_else(|| format!("HTTP error {}", status));
return Err(Error::Api(error_msg));
}
@@ -296,7 +313,12 @@ impl HttpClient {
self.get("/api/v1/content/overview", &params).await
}
- pub async fn reindex(&self, uri: &str, regenerate: bool, wait: bool) -> Result<serde_json::Value> {
+ pub async fn reindex(
+ &self,
+ uri: &str,
+ regenerate: bool,
+ wait: bool,
+ ) -> Result<serde_json::Value> {
let body = serde_json::json!({
"uri": uri,
"regenerate": regenerate,
@@ -309,7 +331,7 @@ impl HttpClient {
pub async fn get_bytes(&self, uri: &str) -> Result<Vec<u8>> {
let url = format!("{}/api/v1/content/download", self.base_url);
let params = vec![("uri".to_string(), uri.to_string())];
-
+
let response = self
.http
.get(&url)
@@ -326,20 +348,22 @@ impl HttpClient {
.json()
.await
.map_err(|e| Error::Network(format!("Failed to parse error response: {}", e)));
-
+
let error_msg = match json_result {
- Ok(json) => {
- json
- .get("error")
- .and_then(|e| e.get("message"))
- .and_then(|m| m.as_str())
- .map(|s| s.to_string())
- .or_else(|| json.get("detail").and_then(|d| d.as_str()).map(|s| s.to_string()))
- .unwrap_or_else(|| format!("HTTP error {}", status))
- }
+ Ok(json) => json
+ .get("error")
+ .and_then(|e| e.get("message"))
+ .and_then(|m| m.as_str())
+ .map(|s| s.to_string())
+ .or_else(|| {
+ json.get("detail")
+ .and_then(|d| d.as_str())
+ .map(|s| s.to_string())
+ })
+ .unwrap_or_else(|| format!("HTTP error {}", status)),
Err(_) => format!("HTTP error {}", status),
};
-
+
return Err(Error::Api(error_msg));
}
@@ -352,7 +376,16 @@ impl HttpClient {
// ============ Filesystem Methods ============
- pub async fn ls(&self, uri: &str, simple: bool, recursive: bool, output: &str, abs_limit: i32, show_all_hidden: bool, node_limit: i32) -> Result<serde_json::Value> {
+ pub async fn ls(
+ &self,
+ uri: &str,
+ simple: bool,
+ recursive: bool,
+ output: &str,
+ abs_limit: i32,
+ show_all_hidden: bool,
+ node_limit: i32,
+ ) -> Result<serde_json::Value> {
let params = vec![
("uri".to_string(), uri.to_string()),
("simple".to_string(), simple.to_string()),
@@ -365,7 +398,15 @@ impl HttpClient {
self.get("/api/v1/fs/ls", &params).await
}
- pub async fn tree(&self, uri: &str, output: &str, abs_limit: i32, show_all_hidden: bool, node_limit: i32, level_limit: i32) -> Result<serde_json::Value> {
+ pub async fn tree(
+ &self,
+ uri: &str,
+ output: &str,
+ abs_limit: i32,
+ show_all_hidden: bool,
+ node_limit: i32,
+ level_limit: i32,
+ ) -> Result<serde_json::Value> {
let params = vec![
("uri".to_string(), uri.to_string()),
("output".to_string(), output.to_string()),
@@ -442,7 +483,13 @@ impl HttpClient {
self.post("/api/v1/search/search", &body).await
}
- pub async fn grep(&self, uri: &str, pattern: &str, ignore_case: bool, node_limit: i32) -> Result<serde_json::Value> {
+ pub async fn grep(
+ &self,
+ uri: &str,
+ pattern: &str,
+ ignore_case: bool,
+ node_limit: i32,
+ ) -> Result<serde_json::Value> {
let body = serde_json::json!({
"uri": uri,
"pattern": pattern,
@@ -452,8 +499,12 @@ impl HttpClient {
self.post("/api/v1/search/grep", &body).await
}
-
- pub async fn glob(&self, pattern: &str, uri: &str, node_limit: i32) -> Result<serde_json::Value> {
+ pub async fn glob(
+ &self,
+ pattern: &str,
+ uri: &str,
+ node_limit: i32,
+ ) -> Result<serde_json::Value> {
let body = serde_json::json!({
"pattern": pattern,
"uri": uri,
@@ -726,11 +777,7 @@ impl HttpClient {
self.put(&path, &body).await
}
- pub async fn admin_regenerate_key(
- &self,
- account_id: &str,
- user_id: &str,
- ) -> Result<Value> {
+ pub async fn admin_regenerate_key(&self, account_id: &str, user_id: &str) -> Result<Value> {
let path = format!(
"/api/v1/admin/accounts/{}/users/{}/key",
account_id, user_id
@@ -790,3 +837,47 @@ impl HttpClient {
Ok(count)
}
}
+
+#[cfg(test)]
+mod tests {
+ use super::HttpClient;
+
+ #[test]
+ fn build_headers_includes_tenant_identity_headers() {
+ let client = HttpClient::new(
+ "http://localhost:1933",
+ Some("test-key".to_string()),
+ Some("assistant-1".to_string()),
+ Some("acme".to_string()),
+ Some("alice".to_string()),
+ 5.0,
+ );
+
+ let headers = client.build_headers();
+
+ assert_eq!(
+ headers
+ .get("X-API-Key")
+ .and_then(|value| value.to_str().ok()),
+ Some("test-key")
+ );
+ assert_eq!(
+ headers
+ .get("X-OpenViking-Agent")
+ .and_then(|value| value.to_str().ok()),
+ Some("assistant-1")
+ );
+ assert_eq!(
+ headers
+ .get("X-OpenViking-Account")
+ .and_then(|value| value.to_str().ok()),
+ Some("acme")
+ );
+ assert_eq!(
+ headers
+ .get("X-OpenViking-User")
+ .and_then(|value| value.to_str().ok()),
+ Some("alice")
+ );
+ }
+}
diff --git a/crates/ov_cli/src/config.rs b/crates/ov_cli/src/config.rs
index e27b3a650..ca1c613f1 100644
--- a/crates/ov_cli/src/config.rs
+++ b/crates/ov_cli/src/config.rs
@@ -10,6 +10,8 @@ pub struct Config {
#[serde(default = "default_url")]
pub url: String,
pub api_key: Option<String>,
+ pub account: Option<String>,
+ pub user: Option<String>,
pub agent_id: Option<String>,
#[serde(default = "default_timeout")]
pub timeout: f64,
@@ -40,6 +42,8 @@ impl Default for Config {
Self {
url: "http://localhost:1933".to_string(),
api_key: None,
+ account: None,
+ user: None,
agent_id: None,
timeout: 60.0,
output: "table".to_string(),
@@ -108,3 +112,26 @@ pub fn get_or_create_machine_id() -> Result<String> {
Err(_) => Ok("default".to_string()),
}
}
+
+#[cfg(test)]
+mod tests {
+ use super::Config;
+
+ #[test]
+ fn config_deserializes_account_and_user_fields() {
+ let config: Config = serde_json::from_str(
+ r#"{
+ "url": "http://localhost:1933",
+ "api_key": "test-key",
+ "account": "acme",
+ "user": "alice",
+ "agent_id": "assistant-1"
+ }"#,
+ )
+ .expect("config should deserialize");
+
+ assert_eq!(config.account.as_deref(), Some("acme"));
+ assert_eq!(config.user.as_deref(), Some("alice"));
+ assert_eq!(config.agent_id.as_deref(), Some("assistant-1"));
+ }
+}
diff --git a/crates/ov_cli/src/main.rs b/crates/ov_cli/src/main.rs
index 5e49d0319..240d30434 100644
--- a/crates/ov_cli/src/main.rs
+++ b/crates/ov_cli/src/main.rs
@@ -20,13 +20,46 @@ pub struct CliContext {
}
impl CliContext {
- pub fn new(output_format: OutputFormat, compact: bool) -> Result<Self> {
+ pub fn new(
+ output_format: OutputFormat,
+ compact: bool,
+ account: Option<String>,
+ user: Option<String>,
+ agent_id: Option<String>,
+ ) -> Result<Self> {
let config = Config::load()?;
- Ok(Self {
+ Ok(Self::from_config(
config,
output_format,
compact,
- })
+ account,
+ user,
+ agent_id,
+ ))
+ }
+
+ fn from_config(
+ mut config: Config,
+ output_format: OutputFormat,
+ compact: bool,
+ account: Option<String>,
+ user: Option<String>,
+ agent_id: Option<String>,
+ ) -> Self {
+ if account.is_some() {
+ config.account = account;
+ }
+ if user.is_some() {
+ config.user = user;
+ }
+ if agent_id.is_some() {
+ config.agent_id = agent_id;
+ }
+ Self {
+ config,
+ output_format,
+ compact,
+ }
}
pub fn get_client(&self) -> client::HttpClient {
@@ -34,6 +67,8 @@ impl CliContext {
&self.config.url,
self.config.api_key.clone(),
self.config.agent_id.clone(),
+ self.config.account.clone(),
+ self.config.user.clone(),
self.config.timeout,
)
}
@@ -53,6 +88,18 @@ struct Cli {
#[arg(short, long, global = true, default_value = "true")]
compact: bool,
+ /// Account identifier to send as X-OpenViking-Account
+ #[arg(long, global = true)]
+ account: Option<String>,
+
+ /// User identifier to send as X-OpenViking-User
+ #[arg(long, global = true)]
+ user: Option<String>,
+
+ /// Agent identifier to send as X-OpenViking-Agent
+ #[arg(long = "agent-id", global = true)]
+ agent_id: Option<String>,
+
#[command(subcommand)]
command: Commands,
}
@@ -202,7 +249,12 @@ enum Commands {
#[arg(short, long)]
all: bool,
/// Maximum number of nodes to list
- #[arg(long = "node-limit", short = 'n', alias = "limit", default_value = "256")]
+ #[arg(
+ long = "node-limit",
+ short = 'n',
+ alias = "limit",
+ default_value = "256"
+ )]
node_limit: i32,
},
/// Get directory tree
@@ -216,7 +268,12 @@ enum Commands {
#[arg(short, long)]
all: bool,
/// Maximum number of nodes to list
- #[arg(long = "node-limit", short = 'n', alias = "limit", default_value = "256")]
+ #[arg(
+ long = "node-limit",
+ short = 'n',
+ alias = "limit",
+ default_value = "256"
+ )]
node_limit: i32,
/// Maximum depth level to traverse (default: 3)
#[arg(short = 'L', long = "level-limit", default_value = "3")]
@@ -290,7 +347,12 @@ enum Commands {
#[arg(short, long, default_value = "")]
uri: String,
/// Maximum number of results
- #[arg(short = 'n', long = "node-limit", alias = "limit", default_value = "10")]
+ #[arg(
+ short = 'n',
+ long = "node-limit",
+ alias = "limit",
+ default_value = "10"
+ )]
node_limit: i32,
/// Score threshold
#[arg(short, long)]
@@ -307,7 +369,12 @@ enum Commands {
#[arg(long)]
session_id: Option<String>,
/// Maximum number of results
- #[arg(short = 'n', long = "node-limit", alias = "limit", default_value = "10")]
+ #[arg(
+ short = 'n',
+ long = "node-limit",
+ alias = "limit",
+ default_value = "10"
+ )]
node_limit: i32,
/// Score threshold
#[arg(short, long)]
@@ -324,7 +391,12 @@ enum Commands {
#[arg(short, long)]
ignore_case: bool,
/// Maximum number of results
- #[arg(short = 'n', long = "node-limit", alias = "limit", default_value = "256")]
+ #[arg(
+ short = 'n',
+ long = "node-limit",
+ alias = "limit",
+ default_value = "256"
+ )]
node_limit: i32,
},
/// Run file glob pattern search
@@ -335,7 +407,12 @@ enum Commands {
#[arg(short, long, default_value = "viking://")]
uri: String,
/// Maximum number of results
- #[arg(short = 'n', long = "node-limit", alias = "limit", default_value = "256")]
+ #[arg(
+ short = 'n',
+ long = "node-limit",
+ alias = "limit",
+ default_value = "256"
+ )]
node_limit: i32,
},
/// Add memory in one shot (creates session, adds messages, commits)
@@ -522,7 +599,13 @@ async fn main() {
let output_format = cli.output;
let compact = cli.compact;
- let ctx = match CliContext::new(output_format, compact) {
+ let ctx = match CliContext::new(
+ output_format,
+ compact,
+ cli.account.clone(),
+ cli.user.clone(),
+ cli.agent_id.clone(),
+ ) {
Ok(ctx) => ctx,
Err(e) => {
eprintln!("Error: {}", e);
@@ -564,65 +647,71 @@ async fn main() {
)
.await
}
- Commands::AddSkill { data, wait, timeout } => {
- handle_add_skill(data, wait, timeout, ctx).await
- }
- Commands::Relations { uri } => {
- handle_relations(uri, ctx).await
- }
- Commands::Link { from_uri, to_uris, reason } => {
- handle_link(from_uri, to_uris, reason, ctx).await
- }
- Commands::Unlink { from_uri, to_uri } => {
- handle_unlink(from_uri, to_uri, ctx).await
- }
- Commands::Export { uri, to } => {
- handle_export(uri, to, ctx).await
- }
- Commands::Import { file_path, target_uri, force, no_vectorize } => {
- handle_import(file_path, target_uri, force, no_vectorize, ctx).await
- }
+ Commands::AddSkill {
+ data,
+ wait,
+ timeout,
+ } => handle_add_skill(data, wait, timeout, ctx).await,
+ Commands::Relations { uri } => handle_relations(uri, ctx).await,
+ Commands::Link {
+ from_uri,
+ to_uris,
+ reason,
+ } => handle_link(from_uri, to_uris, reason, ctx).await,
+ Commands::Unlink { from_uri, to_uri } => handle_unlink(from_uri, to_uri, ctx).await,
+ Commands::Export { uri, to } => handle_export(uri, to, ctx).await,
+ Commands::Import {
+ file_path,
+ target_uri,
+ force,
+ no_vectorize,
+ } => handle_import(file_path, target_uri, force, no_vectorize, ctx).await,
Commands::Wait { timeout } => {
let client = ctx.get_client();
commands::system::wait(&client, timeout, ctx.output_format, ctx.compact).await
- },
+ }
Commands::Status => {
let client = ctx.get_client();
commands::observer::system(&client, ctx.output_format, ctx.compact).await
- },
+ }
Commands::Health => handle_health(ctx).await,
Commands::System { action } => handle_system(action, ctx).await,
Commands::Observer { action } => handle_observer(action, ctx).await,
Commands::Session { action } => handle_session(action, ctx).await,
Commands::Admin { action } => handle_admin(action, ctx).await,
- Commands::Ls { uri, simple, recursive, abs_limit, all, node_limit } => {
- handle_ls(uri, simple, recursive, abs_limit, all, node_limit, ctx).await
- }
- Commands::Tree { uri, abs_limit, all, node_limit, level_limit } => {
- handle_tree(uri, abs_limit, all, node_limit, level_limit, ctx).await
- }
- Commands::Mkdir { uri } => {
- handle_mkdir(uri, ctx).await
- }
- Commands::Rm { uri, recursive } => {
- handle_rm(uri, recursive, ctx).await
- }
- Commands::Mv { from_uri, to_uri } => {
- handle_mv(from_uri, to_uri, ctx).await
- }
- Commands::Stat { uri } => {
- handle_stat(uri, ctx).await
- }
- Commands::AddMemory { content } => {
- handle_add_memory(content, ctx).await
- }
- Commands::Tui { uri } => {
- handle_tui(uri, ctx).await
- }
- Commands::Chat { message, session, sender, stream, no_format, no_history } => {
+ Commands::Ls {
+ uri,
+ simple,
+ recursive,
+ abs_limit,
+ all,
+ node_limit,
+ } => handle_ls(uri, simple, recursive, abs_limit, all, node_limit, ctx).await,
+ Commands::Tree {
+ uri,
+ abs_limit,
+ all,
+ node_limit,
+ level_limit,
+ } => handle_tree(uri, abs_limit, all, node_limit, level_limit, ctx).await,
+ Commands::Mkdir { uri } => handle_mkdir(uri, ctx).await,
+ Commands::Rm { uri, recursive } => handle_rm(uri, recursive, ctx).await,
+ Commands::Mv { from_uri, to_uri } => handle_mv(from_uri, to_uri, ctx).await,
+ Commands::Stat { uri } => handle_stat(uri, ctx).await,
+ Commands::AddMemory { content } => handle_add_memory(content, ctx).await,
+ Commands::Tui { uri } => handle_tui(uri, ctx).await,
+ Commands::Chat {
+ message,
+ session,
+ sender,
+ stream,
+ no_format,
+ no_history,
+ } => {
let session_id = session.or_else(|| config::get_or_create_machine_id().ok());
let cmd = commands::chat::ChatCommand {
- endpoint: std::env::var("VIKINGBOT_ENDPOINT").unwrap_or_else(|_| "http://localhost:1933/bot/v1".to_string()),
+ endpoint: std::env::var("VIKINGBOT_ENDPOINT")
+ .unwrap_or_else(|_| "http://localhost:1933/bot/v1".to_string()),
api_key: std::env::var("VIKINGBOT_API_KEY").ok(),
session: session_id,
sender,
@@ -641,23 +730,37 @@ async fn main() {
Commands::Read { uri } => handle_read(uri, ctx).await,
Commands::Abstract { uri } => handle_abstract(uri, ctx).await,
Commands::Overview { uri } => handle_overview(uri, ctx).await,
- Commands::Reindex { uri, regenerate, wait } => {
- handle_reindex(uri, regenerate, wait, ctx).await
- }
+ Commands::Reindex {
+ uri,
+ regenerate,
+ wait,
+ } => handle_reindex(uri, regenerate, wait, ctx).await,
Commands::Get { uri, local_path } => handle_get(uri, local_path, ctx).await,
- Commands::Find { query, uri, node_limit, threshold } => {
- handle_find(query, uri, node_limit, threshold, ctx).await
- }
- Commands::Search { query, uri, session_id, node_limit, threshold } => {
- handle_search(query, uri, session_id, node_limit, threshold, ctx).await
- }
- Commands::Grep { uri, pattern, ignore_case, node_limit } => {
- handle_grep(uri, pattern, ignore_case, node_limit, ctx).await
- }
+ Commands::Find {
+ query,
+ uri,
+ node_limit,
+ threshold,
+ } => handle_find(query, uri, node_limit, threshold, ctx).await,
+ Commands::Search {
+ query,
+ uri,
+ session_id,
+ node_limit,
+ threshold,
+ } => handle_search(query, uri, session_id, node_limit, threshold, ctx).await,
+ Commands::Grep {
+ uri,
+ pattern,
+ ignore_case,
+ node_limit,
+ } => handle_grep(uri, pattern, ignore_case, node_limit, ctx).await,
- Commands::Glob { pattern, uri, node_limit } => {
- handle_glob(pattern, uri, node_limit, ctx).await
- }
+ Commands::Glob {
+ pattern,
+ uri,
+ node_limit,
+ } => handle_glob(pattern, uri, node_limit, ctx).await,
};
if let Err(e) = result {
@@ -682,32 +785,35 @@ async fn handle_add_resource(
watch_interval: f64,
ctx: CliContext,
) -> Result<()> {
- let is_url = path.starts_with("http://")
- || path.starts_with("https://")
- || path.starts_with("git@");
-
+ let is_url =
+ path.starts_with("http://") || path.starts_with("https://") || path.starts_with("git@");
+
if !is_url {
use std::path::Path;
-
+
// Unescape path: replace backslash followed by space with just space
let unescaped_path = path.replace("\\ ", " ");
let path_obj = Path::new(&unescaped_path);
if !path_obj.exists() {
eprintln!("Error: Path '{}' does not exist.", path);
-
+
// Check if there might be unquoted spaces
use std::env;
let args: Vec<String> = env::args().collect();
-
- if let Some(add_resource_pos) = args.iter().position(|s| s == "add-resource" || s == "add") {
+
+ if let Some(add_resource_pos) =
+ args.iter().position(|s| s == "add-resource" || s == "add")
+ {
if args.len() > add_resource_pos + 2 {
let extra_args = &args[add_resource_pos + 2..];
let suggested_path = format!("{} {}", path, extra_args.join(" "));
- eprintln!("\nIt looks like you may have forgotten to quote a path with spaces.");
+ eprintln!(
+ "\nIt looks like you may have forgotten to quote a path with spaces."
+ );
eprintln!("Suggested command: ov add-resource \"{}\"", suggested_path);
}
}
-
+
std::process::exit(1);
}
path = unescaped_path;
@@ -731,6 +837,8 @@ async fn handle_add_resource(
&ctx.config.url,
ctx.config.api_key.clone(),
ctx.config.agent_id.clone(),
+ ctx.config.account.clone(),
+ ctx.config.user.clone(),
effective_timeout,
);
commands::resources::add_resource(
@@ -750,7 +858,8 @@ async fn handle_add_resource(
watch_interval,
ctx.output_format,
ctx.compact,
- ).await
+ )
+ .await
}
async fn handle_add_skill(
@@ -761,14 +870,19 @@ async fn handle_add_skill(
) -> Result<()> {
let client = ctx.get_client();
commands::resources::add_skill(
- &client, &data, wait, timeout, ctx.output_format, ctx.compact
- ).await
+ &client,
+ &data,
+ wait,
+ timeout,
+ ctx.output_format,
+ ctx.compact,
+ )
+ .await
}
async fn handle_relations(uri: String, ctx: CliContext) -> Result<()> {
let client = ctx.get_client();
- commands::relations::list_relations(&client, &uri, ctx.output_format, ctx.compact
- ).await
+ commands::relations::list_relations(&client, &uri, ctx.output_format, ctx.compact).await
}
async fn handle_link(
@@ -779,25 +893,24 @@ async fn handle_link(
) -> Result<()> {
let client = ctx.get_client();
commands::relations::link(
- &client, &from_uri, &to_uris, &reason, ctx.output_format, ctx.compact
- ).await
+ &client,
+ &from_uri,
+ &to_uris,
+ &reason,
+ ctx.output_format,
+ ctx.compact,
+ )
+ .await
}
-async fn handle_unlink(
- from_uri: String,
- to_uri: String,
- ctx: CliContext,
-) -> Result<()> {
+async fn handle_unlink(from_uri: String, to_uri: String, ctx: CliContext) -> Result<()> {
let client = ctx.get_client();
- commands::relations::unlink(
- &client, &from_uri, &to_uri, ctx.output_format, ctx.compact
- ).await
+ commands::relations::unlink(&client, &from_uri, &to_uri, ctx.output_format, ctx.compact).await
}
async fn handle_export(uri: String, to: String, ctx: CliContext) -> Result<()> {
let client = ctx.get_client();
- commands::pack::export(&client, &uri, &to, ctx.output_format, ctx.compact
- ).await
+ commands::pack::export(&client, &uri, &to, ctx.output_format, ctx.compact).await
}
async fn handle_import(
@@ -809,8 +922,15 @@ async fn handle_import(
) -> Result<()> {
let client = ctx.get_client();
commands::pack::import(
- &client, &file_path, &target_uri, force, no_vectorize, ctx.output_format, ctx.compact
- ).await
+ &client,
+ &file_path,
+ &target_uri,
+ force,
+ no_vectorize,
+ ctx.output_format,
+ ctx.compact,
+ )
+ .await
}
async fn handle_system(cmd: SystemCommands, ctx: CliContext) -> Result<()> {
@@ -823,8 +943,7 @@ async fn handle_system(cmd: SystemCommands, ctx: CliContext) -> Result<()> {
commands::system::status(&client, ctx.output_format, ctx.compact).await
}
SystemCommands::Health => {
- let _ =
- commands::system::health(&client, ctx.output_format, ctx.compact).await?;
+ let _ = commands::system::health(&client, ctx.output_format, ctx.compact).await?;
Ok(())
}
SystemCommands::Crypto { action } => commands::crypto::handle_crypto(action).await,
@@ -865,21 +984,31 @@ async fn handle_session(cmd: SessionCommands, ctx: CliContext) -> Result<()> {
commands::session::list_sessions(&client, ctx.output_format, ctx.compact).await
}
SessionCommands::Get { session_id } => {
- commands::session::get_session(&client, &session_id, ctx.output_format, ctx.compact
- ).await
+ commands::session::get_session(&client, &session_id, ctx.output_format, ctx.compact)
+ .await
}
SessionCommands::Delete { session_id } => {
- commands::session::delete_session(&client, &session_id, ctx.output_format, ctx.compact
- ).await
+ commands::session::delete_session(&client, &session_id, ctx.output_format, ctx.compact)
+ .await
}
- SessionCommands::AddMessage { session_id, role, content } => {
+ SessionCommands::AddMessage {
+ session_id,
+ role,
+ content,
+ } => {
commands::session::add_message(
- &client, &session_id, &role, &content, ctx.output_format, ctx.compact
- ).await
+ &client,
+ &session_id,
+ &role,
+ &content,
+ ctx.output_format,
+ ctx.compact,
+ )
+ .await
}
SessionCommands::Commit { session_id } => {
- commands::session::commit_session(&client, &session_id, ctx.output_format, ctx.compact
- ).await
+ commands::session::commit_session(&client, &session_id, ctx.output_format, ctx.compact)
+ .await
}
}
}
@@ -887,43 +1016,84 @@ async fn handle_session(cmd: SessionCommands, ctx: CliContext) -> Result<()> {
async fn handle_admin(cmd: AdminCommands, ctx: CliContext) -> Result<()> {
let client = ctx.get_client();
match cmd {
- AdminCommands::CreateAccount { account_id, admin_user_id } => {
+ AdminCommands::CreateAccount {
+ account_id,
+ admin_user_id,
+ } => {
commands::admin::create_account(
- &client, &account_id, &admin_user_id, ctx.output_format, ctx.compact,
- ).await
+ &client,
+ &account_id,
+ &admin_user_id,
+ ctx.output_format,
+ ctx.compact,
+ )
+ .await
}
AdminCommands::ListAccounts => {
commands::admin::list_accounts(&client, ctx.output_format, ctx.compact).await
}
AdminCommands::DeleteAccount { account_id } => {
- commands::admin::delete_account(
- &client, &account_id, ctx.output_format, ctx.compact,
- ).await
+ commands::admin::delete_account(&client, &account_id, ctx.output_format, ctx.compact)
+ .await
}
- AdminCommands::RegisterUser { account_id, user_id, role } => {
+ AdminCommands::RegisterUser {
+ account_id,
+ user_id,
+ role,
+ } => {
commands::admin::register_user(
- &client, &account_id, &user_id, &role, ctx.output_format, ctx.compact,
- ).await
+ &client,
+ &account_id,
+ &user_id,
+ &role,
+ ctx.output_format,
+ ctx.compact,
+ )
+ .await
}
AdminCommands::ListUsers { account_id } => {
- commands::admin::list_users(
- &client, &account_id, ctx.output_format, ctx.compact,
- ).await
+ commands::admin::list_users(&client, &account_id, ctx.output_format, ctx.compact).await
}
- AdminCommands::RemoveUser { account_id, user_id } => {
+ AdminCommands::RemoveUser {
+ account_id,
+ user_id,
+ } => {
commands::admin::remove_user(
- &client, &account_id, &user_id, ctx.output_format, ctx.compact,
- ).await
+ &client,
+ &account_id,
+ &user_id,
+ ctx.output_format,
+ ctx.compact,
+ )
+ .await
}
- AdminCommands::SetRole { account_id, user_id, role } => {
+ AdminCommands::SetRole {
+ account_id,
+ user_id,
+ role,
+ } => {
commands::admin::set_role(
- &client, &account_id, &user_id, &role, ctx.output_format, ctx.compact,
- ).await
+ &client,
+ &account_id,
+ &user_id,
+ &role,
+ ctx.output_format,
+ ctx.compact,
+ )
+ .await
}
- AdminCommands::RegenerateKey { account_id, user_id } => {
+ AdminCommands::RegenerateKey {
+ account_id,
+ user_id,
+ } => {
commands::admin::regenerate_key(
- &client, &account_id, &user_id, ctx.output_format, ctx.compact,
- ).await
+ &client,
+ &account_id,
+ &user_id,
+ ctx.output_format,
+ ctx.compact,
+ )
+ .await
}
}
}
@@ -940,21 +1110,17 @@ async fn handle_config(cmd: ConfigCommands, _ctx: CliContext) -> Result<()> {
output::output_success(
&serde_json::to_value(config).unwrap(),
output::OutputFormat::Json,
- true
+ true,
);
Ok(())
}
- ConfigCommands::Validate => {
- match Config::load() {
- Ok(_) => {
- println!("Configuration is valid");
- Ok(())
- }
- Err(e) => {
- Err(Error::Config(e.to_string()))
- }
+ ConfigCommands::Validate => match Config::load() {
+ Ok(_) => {
+ println!("Configuration is valid");
+ Ok(())
}
- }
+ Err(e) => Err(Error::Config(e.to_string())),
+ },
}
}
@@ -975,7 +1141,15 @@ async fn handle_overview(uri: String, ctx: CliContext) -> Result<()> {
async fn handle_reindex(uri: String, regenerate: bool, wait: bool, ctx: CliContext) -> Result<()> {
let client = ctx.get_client();
- commands::content::reindex(&client, &uri, regenerate, wait, ctx.output_format, ctx.compact).await
+ commands::content::reindex(
+ &client,
+ &uri,
+ regenerate,
+ wait,
+ ctx.output_format,
+ ctx.compact,
+ )
+ .await
}
async fn handle_get(uri: String, local_path: String, ctx: CliContext) -> Result<()> {
@@ -997,7 +1171,16 @@ async fn handle_find(
params.push(format!("\"{}\"", query));
print_command_echo("ov find", &params.join(" "), ctx.config.echo_command);
let client = ctx.get_client();
- commands::search::find(&client, &query, &uri, node_limit, threshold, ctx.output_format, ctx.compact).await
+ commands::search::find(
+ &client,
+ &query,
+ &uri,
+ node_limit,
+ threshold,
+ ctx.output_format,
+ ctx.compact,
+ )
+ .await
}
async fn handle_search(
@@ -1018,7 +1201,17 @@ async fn handle_search(
params.push(format!("\"{}\"", query));
print_command_echo("ov search", &params.join(" "), ctx.config.echo_command);
let client = ctx.get_client();
- commands::search::search(&client, &query, &uri, session_id, node_limit, threshold, ctx.output_format, ctx.compact).await
+ commands::search::search(
+ &client,
+ &query,
+ &uri,
+ session_id,
+ node_limit,
+ threshold,
+ ctx.output_format,
+ ctx.compact,
+ )
+ .await
}
/// Print command with specified parameters for debugging
@@ -1028,35 +1221,81 @@ fn print_command_echo(command: &str, params: &str, echo_enabled: bool) {
}
}
-async fn handle_ls(uri: String, simple: bool, recursive: bool, abs_limit: i32, show_all_hidden: bool, node_limit: i32, ctx: CliContext) -> Result<()> {
+async fn handle_ls(
+ uri: String,
+ simple: bool,
+ recursive: bool,
+ abs_limit: i32,
+ show_all_hidden: bool,
+ node_limit: i32,
+ ctx: CliContext,
+) -> Result<()> {
let mut params = vec![
uri.clone(),
format!("-l {}", abs_limit),
format!("-n {}", node_limit),
];
- if simple { params.push("-s".to_string()); }
- if recursive { params.push("-r".to_string()); }
- if show_all_hidden { params.push("-a".to_string()); }
+ if simple {
+ params.push("-s".to_string());
+ }
+ if recursive {
+ params.push("-r".to_string());
+ }
+ if show_all_hidden {
+ params.push("-a".to_string());
+ }
print_command_echo("ov ls", &params.join(" "), ctx.config.echo_command);
let client = ctx.get_client();
let api_output = if ctx.compact { "agent" } else { "original" };
- commands::filesystem::ls(&client, &uri, simple, recursive, api_output, abs_limit, show_all_hidden, node_limit, ctx.output_format, ctx.compact).await
+ commands::filesystem::ls(
+ &client,
+ &uri,
+ simple,
+ recursive,
+ api_output,
+ abs_limit,
+ show_all_hidden,
+ node_limit,
+ ctx.output_format,
+ ctx.compact,
+ )
+ .await
}
-async fn handle_tree(uri: String, abs_limit: i32, show_all_hidden: bool, node_limit: i32, level_limit: i32, ctx: CliContext) -> Result<()> {
+async fn handle_tree(
+ uri: String,
+ abs_limit: i32,
+ show_all_hidden: bool,
+ node_limit: i32,
+ level_limit: i32,
+ ctx: CliContext,
+) -> Result<()> {
let mut params = vec![
uri.clone(),
format!("-l {}", abs_limit),
format!("-n {}", node_limit),
format!("-L {}", level_limit),
];
- if show_all_hidden { params.push("-a".to_string()); }
+ if show_all_hidden {
+ params.push("-a".to_string());
+ }
print_command_echo("ov tree", &params.join(" "), ctx.config.echo_command);
let client = ctx.get_client();
let api_output = if ctx.compact { "agent" } else { "original" };
- commands::filesystem::tree(&client, &uri, api_output, abs_limit, show_all_hidden, node_limit, level_limit, ctx.output_format, ctx.compact).await
+ commands::filesystem::tree(
+ &client,
+ &uri,
+ api_output,
+ abs_limit,
+ show_all_hidden,
+ node_limit,
+ level_limit,
+ ctx.output_format,
+ ctx.compact,
+ )
+ .await
}
async fn handle_mkdir(uri: String, ctx: CliContext) -> Result<()> {
@@ -1079,29 +1318,57 @@ async fn handle_stat(uri: String, ctx: CliContext) -> Result<()> {
commands::filesystem::stat(&client, &uri, ctx.output_format, ctx.compact).await
}
-async fn handle_grep(uri: String, pattern: String, ignore_case: bool, node_limit: i32, ctx: CliContext) -> Result<()> {
+async fn handle_grep(
+ uri: String,
+ pattern: String,
+ ignore_case: bool,
+ node_limit: i32,
+ ctx: CliContext,
+) -> Result<()> {
let mut params = vec![format!("--uri={}", uri), format!("-n {}", node_limit)];
- if ignore_case { params.push("-i".to_string()); }
+ if ignore_case {
+ params.push("-i".to_string());
+ }
params.push(format!("\"{}\"", pattern));
print_command_echo("ov grep", &params.join(" "), ctx.config.echo_command);
let client = ctx.get_client();
- commands::search::grep(&client, &uri, &pattern, ignore_case, node_limit, ctx.output_format, ctx.compact).await
+ commands::search::grep(
+ &client,
+ &uri,
+ &pattern,
+ ignore_case,
+ node_limit,
+ ctx.output_format,
+ ctx.compact,
+ )
+ .await
}
-
async fn handle_glob(pattern: String, uri: String, node_limit: i32, ctx: CliContext) -> Result<()> {
- let params = vec![format!("--uri={}", uri), format!("-n {}", node_limit), format!("\"{}\"", pattern)];
+ let params = vec![
+ format!("--uri={}", uri),
+ format!("-n {}", node_limit),
+ format!("\"{}\"", pattern),
+ ];
print_command_echo("ov glob", &params.join(" "), ctx.config.echo_command);
let client = ctx.get_client();
- commands::search::glob(&client, &pattern, &uri, node_limit, ctx.output_format, ctx.compact).await
+ commands::search::glob(
+ &client,
+ &pattern,
+ &uri,
+ node_limit,
+ ctx.output_format,
+ ctx.compact,
+ )
+ .await
}
async fn handle_health(ctx: CliContext) -> Result<()> {
let client = ctx.get_client();
-
+
// Reuse the system health command
let _ = commands::system::health(&client, ctx.output_format, ctx.compact).await?;
-
+
Ok(())
}
@@ -1109,3 +1376,57 @@ async fn handle_tui(uri: String, ctx: CliContext) -> Result<()> {
let client = ctx.get_client();
tui::run_tui(client, &uri).await
}
+
+#[cfg(test)]
+mod tests {
+ use super::{Cli, CliContext};
+ use crate::config::Config;
+ use crate::output::OutputFormat;
+ use clap::Parser;
+
+ #[test]
+ fn cli_parses_global_identity_override_flags() {
+ let cli = Cli::try_parse_from([
+ "ov",
+ "--account",
+ "acme",
+ "--user",
+ "alice",
+ "--agent-id",
+ "assistant-1",
+ "ls",
+ ])
+ .expect("cli should parse");
+
+ assert_eq!(cli.account.as_deref(), Some("acme"));
+ assert_eq!(cli.user.as_deref(), Some("alice"));
+ assert_eq!(cli.agent_id.as_deref(), Some("assistant-1"));
+ }
+
+ #[test]
+ fn cli_context_overrides_identity_from_cli_flags() {
+ let config = Config {
+ url: "http://localhost:1933".to_string(),
+ api_key: Some("test-key".to_string()),
+ account: Some("from-config-account".to_string()),
+ user: Some("from-config-user".to_string()),
+ agent_id: Some("from-config-agent".to_string()),
+ timeout: 60.0,
+ output: "table".to_string(),
+ echo_command: true,
+ };
+
+ let ctx = CliContext::from_config(
+ config,
+ OutputFormat::Json,
+ true,
+ Some("from-cli-account".to_string()),
+ Some("from-cli-user".to_string()),
+ Some("from-cli-agent".to_string()),
+ );
+
+ assert_eq!(ctx.config.account.as_deref(), Some("from-cli-account"));
+ assert_eq!(ctx.config.user.as_deref(), Some("from-cli-user"));
+ assert_eq!(ctx.config.agent_id.as_deref(), Some("from-cli-agent"));
+ }
+}
diff --git a/docs/en/api/01-overview.md b/docs/en/api/01-overview.md
index ae4ddbd44..f9bf74f87 100644
--- a/docs/en/api/01-overview.md
+++ b/docs/en/api/01-overview.md
@@ -73,6 +73,8 @@ export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf
{
"url": "http://localhost:1933",
"api_key": "your-key",
+ "account": "acme",
+ "user": "alice",
"agent_id": "my-agent"
}
```
@@ -81,6 +83,9 @@ export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf
|-------|-------------|---------|
| `url` | Server address | (required) |
| `api_key` | API key | `null` (no auth) |
+| `account` | Default account header for tenant-scoped requests | `null` |
+| `user` | Default user header for tenant-scoped requests | `null` |
+| `agent_id` | Agent identifier header | `null` |
| `timeout` | HTTP request timeout in seconds | `60.0` |
| `output` | Default output format: `"table"` or `"json"` | `"table"` |
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.md
index bd6fe9d55..47dc551e5 100644
--- a/docs/en/guides/01-configuration.md
+++ b/docs/en/guides/01-configuration.md
@@ -766,6 +766,8 @@ Config file for the HTTP client (`SyncHTTPClient` / `AsyncHTTPClient`) and CLI t
{
"url": "http://localhost:1933",
"api_key": "your-secret-key",
+ "account": "acme",
+ "user": "alice",
"agent_id": "my-agent",
"output": "table"
}
@@ -775,9 +777,17 @@ Config file for the HTTP client (`SyncHTTPClient` / `AsyncHTTPClient`) and CLI t
|-------|-------------|---------|
| `url` | Server address | (required) |
| `api_key` | API key for authentication (root key or user key) | `null` (no auth) |
+| `account` | Default account sent as `X-OpenViking-Account` | `null` |
+| `user` | Default user sent as `X-OpenViking-User` | `null` |
| `agent_id` | Agent identifier for agent space isolation | `null` |
| `output` | Default output format: `"table"` or `"json"` | `"table"` |
+CLI flags can override these identity fields per command:
+
+```bash
+openviking --account acme --user alice --agent-id assistant-2 ls viking://
+```
+
See [Deployment](./03-deployment.md) for details.
## server Section
@@ -789,6 +799,7 @@ When running OpenViking as an HTTP service, add a `server` section to `ov.conf`:
"server": {
"host": "0.0.0.0",
"port": 1933,
+ "auth_mode": "api_key",
"root_api_key": "your-secret-root-key",
"cors_origins": ["*"]
}
@@ -799,10 +810,13 @@ When running OpenViking as an HTTP service, add a `server` section to `ov.conf`:
|-------|------|-------------|---------|
| `host` | str | Bind address | `0.0.0.0` |
| `port` | int | Bind port | `1933` |
-| `root_api_key` | str | Root API key for multi-tenant auth, disabled if not set | `null` |
+| `auth_mode` | str | Authentication mode: `"api_key"` or `"trusted"` | `"api_key"` |
+| `root_api_key` | str | Root API key for multi-tenant auth in `api_key` mode | `null` |
| `cors_origins` | list | Allowed CORS origins | `["*"]` |
-When `root_api_key` is configured, the server enables multi-tenant authentication. Use the Admin API to create accounts and user keys. When not set, the server runs in dev mode with no authentication.
+`api_key` mode uses API keys. `trusted` mode trusts `X-OpenViking-Account` / `X-OpenViking-User` headers from a trusted gateway or internal caller.
+
+When `root_api_key` is configured, the server enables multi-tenant authentication. Use the Admin API to create accounts and user keys. Development mode only applies when `auth_mode = "api_key"` and `root_api_key` is not set.
For startup and deployment details see [Deployment](./03-deployment.md), for authentication see [Authentication](./04-authentication.md).
diff --git a/docs/en/guides/04-authentication.md b/docs/en/guides/04-authentication.md
index 950c35990..f7f68be20 100644
--- a/docs/en/guides/04-authentication.md
+++ b/docs/en/guides/04-authentication.md
@@ -1,6 +1,6 @@
# Authentication
-OpenViking Server supports multi-tenant API key authentication with role-based access control.
+OpenViking Server supports two authentication modes with role-based access control: `api_key` and `trusted`.
## Overview
@@ -13,13 +13,21 @@ OpenViking uses a two-layer API key system:
All API keys are plain random tokens with no embedded identity. The server resolves identity by first comparing against the root key, then looking up the user key index.
+## Authentication Modes
+
+| Mode | `server.auth_mode` | Identity Source | Typical Use |
+|------|--------------------|-----------------|-------------|
+| API key mode | `"api_key"` | API key, with optional tenant headers for root requests | Standard multi-tenant deployment |
+| Trusted mode | `"trusted"` | `X-OpenViking-Account` / `X-OpenViking-User` / optional `X-OpenViking-Agent` headers | Behind a trusted gateway or internal network boundary |
+
## Setting Up (Server Side)
-Configure the root API key in the `server` section of `ov.conf`:
+Configure the authentication mode in the `server` section of `ov.conf`:
```json
{
"server": {
+ "auth_mode": "api_key",
"root_api_key": "your-secret-root-key"
}
}
@@ -87,10 +95,20 @@ client = ov.SyncHTTPClient(
{
"url": "http://localhost:1933",
"api_key": "<user-key>",
+ "account": "acme",
+ "user": "alice",
"agent_id": "my-agent"
}
```
+When you use a regular user key, `account` and `user` are optional because the server can derive them from the key. They are recommended when you use `trusted` mode or a root key against tenant-scoped APIs.
+
+**CLI override flags**
+
+```bash
+openviking --account acme --user alice --agent-id my-agent ls viking://
+```
+
### Accessing Tenant Data with Root Key
When using the root key to access tenant-scoped data APIs (e.g. `ls`, `find`, `sessions`), you must specify the target account and user. The server will reject the request otherwise. Admin API and system status endpoints are not affected.
@@ -124,10 +142,53 @@ client = ov.SyncHTTPClient(
"url": "http://localhost:1933",
"api_key": "your-secret-root-key",
"account": "acme",
- "user": "alice"
+ "user": "alice",
+ "agent_id": "my-agent"
+}
+```
+
+## Trusted Mode
+
+Trusted mode skips user-key lookup and instead trusts explicit identity headers on each request:
+
+```json
+{
+ "server": {
+ "auth_mode": "trusted",
+ "host": "127.0.0.1"
+ }
}
```
+Rules in trusted mode:
+
+- `X-OpenViking-Account` and `X-OpenViking-User` are required on tenant-scoped requests.
+- `X-OpenViking-Agent` is optional and defaults to `default`.
+- If `root_api_key` is also configured, every request must still provide a matching API key.
+- Only expose this mode behind a trusted network boundary or an identity-injecting gateway.
+
+**curl**
+
+```bash
+curl http://localhost:1933/api/v1/fs/ls?uri=viking:// \
+ -H "X-OpenViking-Account: acme" \
+ -H "X-OpenViking-User: alice" \
+ -H "X-OpenViking-Agent: my-agent"
+```
+
+**Python SDK**
+
+```python
+import openviking as ov
+
+client = ov.SyncHTTPClient(
+ url="http://localhost:1933",
+ account="acme",
+ user="alice",
+ agent_id="my-agent",
+)
+```
+
## Roles and Permissions
| Role | Scope | Capabilities |
@@ -138,7 +199,7 @@ client = ov.SyncHTTPClient(
## Development Mode
-When no `root_api_key` is configured, authentication is disabled. All requests are accepted as ROOT with the default account. **This is only allowed when the server binds to localhost** (`127.0.0.1`, `localhost`, or `::1`). If `host` is set to a non-loopback address (e.g. `0.0.0.0`) without a `root_api_key`, the server will refuse to start.
+When `auth_mode = "api_key"` and no `root_api_key` is configured, authentication is disabled. All requests are accepted as ROOT with the default account. **This is only allowed when the server binds to localhost** (`127.0.0.1`, `localhost`, or `::1`). If `host` is set to a non-loopback address (e.g. `0.0.0.0`) without a `root_api_key`, the server will refuse to start.
```json
{
diff --git a/docs/zh/api/01-overview.md b/docs/zh/api/01-overview.md
index 3b1346098..48675085a 100644
--- a/docs/zh/api/01-overview.md
+++ b/docs/zh/api/01-overview.md
@@ -73,6 +73,8 @@ export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf
{
"url": "http://localhost:1933",
"api_key": "your-key",
+ "account": "acme",
+ "user": "alice",
"agent_id": "my-agent"
}
```
@@ -81,6 +83,8 @@ export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf
|------|------|--------|
| `url` | 服务端地址 | (必填) |
| `api_key` | API Key | `null`(无认证) |
+| `account` | 面向租户请求的默认 account 请求头 | `null` |
+| `user` | 面向租户请求的默认 user 请求头 | `null` |
| `agent_id` | Agent 标识符 | `null` |
| `timeout` | HTTP 请求超时时间(秒) | `60.0` |
| `output` | 默认输出格式:`"table"` 或 `"json"` | `"table"` |
diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.md
index 675c34234..e357e42f6 100644
--- a/docs/zh/guides/01-configuration.md
+++ b/docs/zh/guides/01-configuration.md
@@ -743,6 +743,8 @@ HTTP 客户端(`SyncHTTPClient` / `AsyncHTTPClient`)和 CLI 工具连接远
{
"url": "http://localhost:1933",
"api_key": "your-secret-key",
+ "account": "acme",
+ "user": "alice",
"agent_id": "my-agent",
"output": "table"
}
@@ -752,9 +754,17 @@ HTTP 客户端(`SyncHTTPClient` / `AsyncHTTPClient`)和 CLI 工具连接远
|------|------|--------|
| `url` | 服务端地址 | (必填) |
| `api_key` | API Key 认证(root key 或 user key) | `null`(无认证) |
+| `account` | 默认发送为 `X-OpenViking-Account` 的租户标识 | `null` |
+| `user` | 默认发送为 `X-OpenViking-User` 的用户标识 | `null` |
| `agent_id` | Agent 标识,用于 agent space 隔离 | `null` |
| `output` | 默认输出格式:`"table"` 或 `"json"` | `"table"` |
+也可以在单次命令里用 CLI 参数覆盖这些身份字段:
+
+```bash
+openviking --account acme --user alice --agent-id assistant-2 ls viking://
+```
+
详见 [服务部署](./03-deployment.md)。
## server 段
@@ -766,6 +776,7 @@ HTTP 客户端(`SyncHTTPClient` / `AsyncHTTPClient`)和 CLI 工具连接远
"server": {
"host": "0.0.0.0",
"port": 1933,
+ "auth_mode": "api_key",
"root_api_key": "your-secret-root-key",
"cors_origins": ["*"]
}
@@ -776,10 +787,13 @@ HTTP 客户端(`SyncHTTPClient` / `AsyncHTTPClient`)和 CLI 工具连接远
|------|------|------|--------|
| `host` | str | 绑定地址 | `0.0.0.0` |
| `port` | int | 绑定端口 | `1933` |
-| `root_api_key` | str | Root API Key,启用多租户认证,不设则为开发模式 | `null` |
+| `auth_mode` | str | 认证模式:`"api_key"` 或 `"trusted"` | `"api_key"` |
+| `root_api_key` | str | Root API Key。在 `api_key` 模式下启用多租户认证 | `null` |
| `cors_origins` | list | CORS 允许的来源 | `["*"]` |
-配置 `root_api_key` 后,服务端启用多租户认证。通过 Admin API 创建工作区和用户 key。不配置时为开发模式,不需要认证。
+`api_key` 模式使用 API Key 认证;`trusted` 模式信任上游网关或受信调用方注入的 `X-OpenViking-Account` / `X-OpenViking-User` 请求头。
+
+配置 `root_api_key` 后,服务端启用多租户认证。通过 Admin API 创建工作区和用户 key。只有在 `auth_mode = "api_key"` 且未配置 `root_api_key` 时,服务端才会进入开发模式。
启动方式和部署详情见 [服务部署](./03-deployment.md),认证详情见 [认证](./04-authentication.md)。
diff --git a/docs/zh/guides/04-authentication.md b/docs/zh/guides/04-authentication.md
index cf937104d..d1d5d7159 100644
--- a/docs/zh/guides/04-authentication.md
+++ b/docs/zh/guides/04-authentication.md
@@ -1,6 +1,6 @@
# 认证
-OpenViking Server 支持多租户 API Key 认证和基于角色的访问控制。
+OpenViking Server 支持两种认证模式,并带有基于角色的访问控制:`api_key` 和 `trusted`。
## 概述
@@ -13,13 +13,21 @@ OpenViking 使用两层 API Key 体系:
所有 API Key 均为纯随机 token,不携带身份信息。服务端通过先比对 root key、再查 user key 索引的方式确定身份。
+## 认证模式
+
+| 模式 | `server.auth_mode` | 身份来源 | 典型使用场景 |
+|------|--------------------|----------|--------------|
+| API Key 模式 | `"api_key"` | API Key,root 请求可附带租户请求头 | 标准多租户部署 |
+| Trusted 模式 | `"trusted"` | `X-OpenViking-Account` / `X-OpenViking-User` / 可选 `X-OpenViking-Agent` 请求头 | 部署在受信网关或内网边界之后 |
+
## 服务端配置
-在 `ov.conf` 的 `server` 段配置 root API key:
+在 `ov.conf` 的 `server` 段配置认证模式:
```json
{
"server": {
+ "auth_mode": "api_key",
"root_api_key": "your-secret-root-key"
}
}
@@ -87,10 +95,20 @@ client = ov.SyncHTTPClient(
{
"url": "http://localhost:1933",
"api_key": "<user-key>",
+ "account": "acme",
+ "user": "alice",
"agent_id": "my-agent"
}
```
+如果使用普通 `user key`,`account` 和 `user` 可以省略,因为服务端可以从 key 反查出来;如果使用 `trusted` 模式,或者用 `root key` 访问租户级 API,则建议明确配置。
+
+**CLI 覆盖参数**
+
+```bash
+openviking --account acme --user alice --agent-id my-agent ls viking://
+```
+
### 使用 Root Key 访问租户数据
使用 root key 访问租户级数据 API(如 `ls`、`find`、`sessions` 等)时,必须指定目标 account 和 user,否则服务端将拒绝请求。Admin API 和系统状态端点不受此限制。
@@ -124,10 +142,53 @@ client = ov.SyncHTTPClient(
"url": "http://localhost:1933",
"api_key": "your-secret-root-key",
"account": "acme",
- "user": "alice"
+ "user": "alice",
+ "agent_id": "my-agent"
+}
+```
+
+## Trusted 模式
+
+Trusted 模式不会查 user key,而是直接信任每个请求显式携带的身份请求头:
+
+```json
+{
+ "server": {
+ "auth_mode": "trusted",
+ "host": "127.0.0.1"
+ }
}
```
+Trusted 模式规则:
+
+- 租户级请求必须包含 `X-OpenViking-Account` 和 `X-OpenViking-User`
+- `X-OpenViking-Agent` 可选,缺省为 `default`
+- 如果同时配置了 `root_api_key`,每个请求仍然必须带匹配的 API Key
+- 只应部署在受信网络边界之后,或由身份注入网关统一转发
+
+**curl**
+
+```bash
+curl http://localhost:1933/api/v1/fs/ls?uri=viking:// \
+ -H "X-OpenViking-Account: acme" \
+ -H "X-OpenViking-User: alice" \
+ -H "X-OpenViking-Agent: my-agent"
+```
+
+**Python SDK**
+
+```python
+import openviking as ov
+
+client = ov.SyncHTTPClient(
+ url="http://localhost:1933",
+ account="acme",
+ user="alice",
+ agent_id="my-agent",
+)
+```
+
## 角色与权限
| 角色 | 作用域 | 能力 |
@@ -138,7 +199,7 @@ client = ov.SyncHTTPClient(
## 开发模式
-不配置 `root_api_key` 时,认证禁用,所有请求以 ROOT 身份访问 default account。**此模式仅允许在服务器绑定 localhost 时使用**(`127.0.0.1`、`localhost` 或 `::1`)。如果 `host` 设置为非回环地址(如 `0.0.0.0`)且未配置 `root_api_key`,服务器将拒绝启动。
+当 `auth_mode = "api_key"` 且未配置 `root_api_key` 时,认证禁用,所有请求以 ROOT 身份访问 default account。**此模式仅允许在服务器绑定 localhost 时使用**(`127.0.0.1`、`localhost` 或 `::1`)。如果 `host` 设置为非回环地址(如 `0.0.0.0`)且未配置 `root_api_key`,服务器将拒绝启动。
```json
{
diff --git a/examples/ovcli.conf.example b/examples/ovcli.conf.example
index c0a6227ba..e9d8c0b37 100644
--- a/examples/ovcli.conf.example
+++ b/examples/ovcli.conf.example
@@ -1,6 +1,8 @@
{
"url": "http://localhost:1933",
"api_key": null,
+ "account": null,
+ "user": null,
"agent_id": null,
"timeout": 60.0,
"output": "table",