Documentation Index
Fetch the complete documentation index at: https://mintlify.com/dallay/corvus/llms.txt
Use this file to discover all available pages before exploring further.
File Operations
Corvus provides two file operation tools with strict security enforcement:
file_read — Read file contentsfile_write — Write or create files
Both tools enforce workspace-only access by default and validate all paths to prevent traversal attacks.
file_read
Parameters
Relative path to the file within the workspace
Security
Path Validation (from src/tools/file_read.rs:58-64):
if !self.security.is_path_allowed(path) {
return Ok(ToolResult {
success: false,
error: Some(format!("Path not allowed: {path}")),
..Default::default()
});
}
let resolved_path = tokio::fs::canonicalize(&full_path).await?;
if !self.security.is_resolved_path_allowed(&resolved_path) {
return Err("Resolved path escapes workspace");
}
const MAX_FILE_SIZE_BYTES: u64 = 10 * 1024 * 1024;
Example
// Input
{"path": "README.md"}
// Output
{
"success": true,
"output": "# Corvus\n\nFast AI agent runtime...\n",
"error": null
}
file_write
Parameters
Relative path to the file within the workspace
Content to write to the file
Explicit approval flag for overwriting existing files in supervised mode
Security
Workspace-Only Mode (default):
[autonomy]
workspace_only = true # blocks all writes outside workspace
const FORBIDDEN_PATHS: &[&str] = &[
"/etc", "/root", "/proc", "/sys", "/boot",
"/.ssh", "/.gnupg", "/.aws", "/.env"
];
if path.contains('\0') {
return Err("Path contains null byte (path injection attempt)");
}
{
"path": "config.toml",
"content": "[updated config]",
"approved": true
}
Example
// Input
{
"path": "notes.txt",
"content": "Meeting notes from 2026-03-05"
}
// Output
{
"success": true,
"output": "File written: notes.txt (29 bytes)",
"error": null
}
Autonomy Levels
| Level | file_read | file_write |
|---|
| ReadOnly | ✅ Allowed | ❌ Blocked |
| Supervised | ✅ Allowed | ✅ Allowed (approval for overwrites) |
| Full | ✅ Allowed | ✅ Allowed |
Implementation Reference
pub struct FileReadTool {
security: Arc<SecurityPolicy>,
}
impl FileReadTool {
pub fn new(security: Arc<SecurityPolicy>) -> Self {
Self { security }
}
}
#[async_trait]
impl Tool for FileReadTool {
fn name(&self) -> &str { "file_read" }
async fn execute(&self, args: Value) -> Result<ToolResult> {
let path = args["path"].as_str()?;
// 1. Check allowlist
// 2. Record action (rate limit)
// 3. Canonicalize path
// 4. Validate resolved path
// 5. Check file size
// 6. Read and return
}
}
Path Validation Rules
Relative Path Check
Absolute paths and .. traversal are rejected
Canonicalization
Path is resolved to its absolute canonical form
Workspace Boundary Check
Resolved path must start with workspace directory
Forbidden Path Check
System directories and sensitive files are blocked
Common Errors
| Error | Cause | Solution |
|---|
| ”Path not allowed” | Path escapes workspace or uses .. | Use relative paths only |
| ”File too large” | File exceeds 10MB limit | Split file or use streaming |
| ”Failed to resolve” | File doesn’t exist or symlink is broken | Check path spelling |
| ”Rate limit exceeded” | Too many actions in last hour | Wait or increase max_actions_per_hour |
Best Practices
Always use forward slashes (/) in paths, even on Windows. Corvus normalizes paths internally.
Never disable workspace_only mode in production. It’s your primary defense against path traversal.
