Getting Started

This guide walks you through creating your first sandbox and running commands in under 5 minutes.

Prerequisites

Rust

Capsa requires Rust 1.70 or later (edition 2021). Install or update Rust via rustup:

rustup update stable

Platform Requirements

• KVM support: Your CPU must support hardware virtualization (Intel VT-x or AMD-V)
• Access to /dev/kvm: Your user must have permission to access the KVM device

Check KVM availability:

ls -la /dev/kvm

# Add your user to the kvm group if needed
sudo usermod -aG kvm $USER

TIP

After adding yourself to the kvm group, log out and back in for the change to take effect.

Installation

Not Yet Published

Capsa is not yet available on crates.io. For now, add it as a git dependency:

[dependencies]
capsa = { git = "https://github.com/luizribeiro/capsa" }
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }

Capsa automatically selects the appropriate backend for your platform (KVM on Linux, Virtualization.framework on macOS).

Your First Sandbox

Create a sandbox, connect to the agent, and run a command:

#[tokio::main]
async fn main() -> capsa::Result<()> {
    // Create a sandbox
    let vm = capsa::sandbox().build().await?;

    // Connect to the built-in agent
    let agent = vm.agent().await?;

    // Run a command and get structured output
    let result = agent.exec("echo").arg("Hello from the sandbox!").run().await?;
    println!("Output: {}", result.stdout);
    println!("Exit code: {}", result.exit_code);

    // Query system information
    let info = agent.info().await?;
    println!("Kernel: {}", info.kernel_version);
    println!("CPUs: {}", info.cpus);

    // Clean shutdown
    vm.shutdown().await?;

    Ok(())
}

Run it:

cargo run

You should see output like:

Output: Hello from the sandbox!
Exit code: 0
Kernel: 6.1.0
CPUs: 1

What Just Happened?

1. capsa::sandbox() - Creates a sandbox builder with a managed kernel and init system
2. .build().await - Boots the VM and waits for it to be ready
3. vm.agent().await - Connects to the built-in agent over vsock
4. agent.exec() - Runs a command and returns structured output (stdout, stderr, exit code)
5. vm.shutdown() - Cleanly shuts down the VM

The agent provides a proper RPC interface - no more parsing terminal output!

Adding Resources

Configure CPU and memory for your sandbox:

let vm = capsa::sandbox()
    .cpus(4)           // 4 virtual CPUs
    .memory_mb(2048)   // 2 GB memory
    .build()
    .await?;

Sharing Files

Share a host directory with the sandbox:

let vm = capsa::sandbox()
    .share("./my-project", "/project", AccessMode::ReadOnly)
    .build()
    .await?;

let agent = vm.agent().await?;

// Files are automatically mounted at /project
let result = agent.exec("ls").arg("/project").run().await?;
println!("Project files: {}", result.stdout);

Network Policies

Restrict network access with policies:

let policy = NetworkPolicy::deny_all()
    .allow_domain("api.github.com");

let network = VirtualNetwork::with_gateway(
    Gateway::new("10.0.2.0/24").unwrap().policy(policy).unwrap()
);

let vm = capsa::sandbox()
    .network(&network)?
    .build()
    .await?;

// Only api.github.com is accessible from this sandbox

Or disable networking entirely:

let vm = capsa::sandbox()
    .no_network()
    .build()
    .await?;

Next Steps

• Running Commands - Command execution, environment variables, timeouts
• Working with Files - File operations and shared directories
• Network Security - Detailed network policy configuration
• Custom VMs - For advanced use cases requiring custom kernels